Passer au contenu principal
Permettez aux utilisateurs d’autoriser votre application à accéder à leur profil Ace Data Cloud, à leurs abonnements de services, à leurs clés API, à leur utilisation ou à leurs commandes. Utilisez le standard Authorization Code + S256 PKCE : l’application ouvre la page d’autorisation, l’utilisateur consent puis reçoit un code à usage unique, qui est ensuite échangé contre un jeton d’accès OAuth. Le jeton d’accès OAuth est utilisé pour accéder aux interfaces de ressources du compte ; l’appel de l’API de modèles utilise la clé API correspondante. L’autorisation OAuth ne crée pas automatiquement de clé API, n’active pas de service et n’augmente pas le solde.

Choisir le mode d’intégration

La redirection standard ne requiert pas embed=studio, embed_origin ou postMessage. Le mode composant Studio crée la page d’autorisation et maintient le pont de messagerie par l’hôte ; les tiers doivent s’intégrer selon le protocole de composant à la fin de cet article, sans assembler eux-mêmes ces deux paramètres.

Points de terminaison et document de découverte

L’interface de gestion des applications requiert une authentification par connexion au compte ; il ne s’agit pas d’une interface d’enregistrement dynamique anonyme (DCR). Les adresses de découverte/d’enregistrement propres au service MCP sont des points d’entrée différents des points de terminaison OAuth de compte de ce tableau ; lors de la connexion à un MCP spécifique, procédez conformément à la documentation et aux résultats de découverte de ce service. Le document de découverte est utilisé pour obtenir les points de terminaison et les capacités du protocole. Le flux actuel renvoie un jeton OAuth, mais pas de id_token ; ne traitez pas cela comme un flux de connexion OpenID Connect complet uniquement parce que le scope openid existe.

Étendues d’autorisation : utiliser les noms de scope actuels

scope est un nom d’autorisation sensible à la casse, séparé par des espaces. Les nouvelles applications utilisent des autorisations spécifiques telles que profile:read, email:read, phone:read.

Où obtenir les autorisations demandables

Après connexion, l’interface de liste des applications OAuth GET /api/v1/oauth2/applications/ renvoie available_scopes ; le sélecteur d’autorisations de la page de gestion des applications utilise le même catalogue. Il s’agit des étendues disponibles que les applications libre-service ordinaires doivent adopter. Le scopes_supported de Discovery contient tous les noms d’autorisations reconnus par la plateforme ; cela ne signifie pas que votre application peut demander chacun d’entre eux. L’autorisation vérifie simultanément :
  1. si l’autorisation peut être déléguée à ce type d’application ;
  2. si l’autorisation est déjà enregistrée dans les étendues autorisées de cette application OAuth ;
  3. si l’utilisateur actuel possède l’autorisation demandée.
Les autorisations inconnues, non enregistrées, non délégables ou non détenues par l’utilisateur renvoient invalid_scope. Elles sont également vérifiées à nouveau lors de l’échange du code d’autorisation et de l’actualisation, et ne sont pas automatiquement complétées ou élevées.

Autorisations disponibles pour les applications libre-service ordinaires

Voici le catalogue actuel (2026-10-09) ; lors de l’intégration, référez-vous à available_scopes. Par exemple, utilisez profile:read pour lire uniquement le profil personnel ; ajoutez email:read si l’e-mail est également nécessaire ; utilisez profile:read credentials:read pour lire les clés API existantes. Demandez credentials:write uniquement lorsqu’il est réellement nécessaire de créer ou de modifier des clés, et ajoutez offline_access lorsqu’une actualisation est requise. Certaines autorisations sont réservées aux applications de confiance approuvées par la plateforme, par exemple sites:read, sites:write, platform-tokens:read ; d’autres autorisations ne sont pas ouvertes aux applications OAuth tierces ordinaires. Les types de client public/confidential décrivent la capacité à conserver un secret et ne sont pas liés au fait que l’application soit de confiance. Les applications créées en libre-service ne peuvent pas activer elles-mêmes des autorisations de confiance. account est un sélecteur d’autorisation de compte utilisé par le MCP officiel spécifié de gestion des comptes, et non le scope « toutes les autorisations » pour les applications tierces ; il ne peut pas être mélangé avec d’autres scopes. Les tiers doivent répertorier explicitement les autorisations spécifiques dont ils ont besoin.

Migrer depuis l’ancienne documentation

Les anciens noms ne sont pas acceptés comme alias de compatibilité. Mettez à jour simultanément les scopes enregistrés de l’application OAuth, l’URL d’autorisation et votre propre vérification des autorisations ; la modification de la configuration de l’application n’ajoute pas d’autorisations aux jetons déjà émis, l’utilisateur doit réautoriser.

Étape 1 : enregistrer l’application OAuth

Ouvrez la gestion des applications OAuth, créez une application et renseignez :
  • Nom, description, logo de l’application : affichés du côté de l’application sur la page d’autorisation.
  • Type de client : choisissez Public pour un client purement frontend, mobile ou desktop ; choisissez Confidential pour un service pouvant conserver le secret côté backend.
  • Adresse de rappel : utilisez HTTPS en production et enregistrez l’URL complète réellement utilisée par l’application pour traiter le rappel.
  • Autorisations : sélectionnez les scopes réellement nécessaires dans le catalogue fourni par la page.
Enregistrez le client_id. Les clients Confidential conservent le client_secret côté serveur et ne peuvent pas le placer dans le HTML, les variables de build frontend ou les URL. Les clients Public n’utilisent pas de secret pour échanger un token ; même si la réponse d’enregistrement contient ce champ, il ne peut pas être considéré comme un identifiant que le client peut garder secret. Le redirect_uri doit être exactement identique lors de l’enregistrement, de l’autorisation et de l’échange de token, y compris le chemin, la barre oblique finale et les paramètres de requête. Chaque compte peut créer jusqu’à 20 applications. Le Secret n’est affiché qu’à la création/rotation ; après la rotation, l’ancien secret ne peut plus effectuer les échanges nécessitant une authentification client.

Étape 2 : le bouton lance l’autorisation

À chaque clic sur la connexion, générez un nouveau state et un nouveau code_verifier aléatoires, puis calculez :
Enregistrez le state, le verifier et l’adresse de rappel dans la propre session de l’application, puis ouvrez la page d’autorisation avec des paramètres encodés en URL :
Les clients Public doivent envoyer PKCE S256. Bien que Discovery liste également plain, les clients Public ne peuvent pas l’utiliser. Il est également recommandé que les clients Confidential utilisent S256 ; si PKCE a été utilisé lors du lancement de l’autorisation, le verifier correspondant doit être soumis lors de l’échange. Après le consentement de l’utilisateur, le retour vers redirect_uri contient les paramètres de requête code et state renvoyé tel quel. En cas de refus, error=access_denied, une description de l’erreur et state sont renvoyés. Avant de traiter le rappel, vérifiez d’abord que le state correspond à cette session. Le code d’autorisation est valable 10 minutes et ne peut être échangé qu’une seule fois ; après un échec, relancez la connexion, ne rafraîchissez pas de façon répétée l’ancienne URL de rappel.

Étape 3 : échanger le token OAuth

Les clients Public effectuent l’échange directement depuis le navigateur ou le client ; les clients Confidential l’effectuent dans leur propre backend. Le corps de la requête prend en charge l’encodage de formulaire, les variables suivantes représentant les données obtenues par l’application lors de cette autorisation :
Les clients Confidential doivent également ajouter le champ de formulaire client_secret côté serveur. client_secret_post est actuellement pris en charge ; ne considérez pas l’authentification client HTTP Basic comme une méthode prise en charge. Dans la réponse de succès, lisez access_token, token_type, expires_in et le scope effectivement accordé. Un refresh_token n’est présent que si offline_access a été demandé et accordé. Ne traitez pas l’OAuth access token comme l’API Key de l’API de modèles, et n’écrivez pas les token, verifier ou codes d’autorisation dans les journaux, les événements analytiques ou les liens partagés.

Étape 4 : lire les informations utilisateur et l’API Key

Utilisez d’abord l’OAuth access token pour demander UserInfo :
Les champs renvoyés dépendent du scope : id est l’identifiant utilisateur ; profile:read ou openid permettent de lire les informations de base (telles que username, nickname, avatar, is_verified, date_joined, registration_method) ; l’e-mail nécessite email:read, le numéro de téléphone et la région nécessitent phone:read. Ne supposez pas que les champs non autorisés sont toujours présents. Lorsqu’une API Key existante est nécessaire et que credentials:read a été accordé, utilisez l’id de UserInfo comme condition de filtrage :
La liste renvoyée utilise count et items, et le champ Key est items[*].token, non data[0].value. user_id=me n’est pas un ID utilisateur valide pour cette interface. Pour les données sur plusieurs pages, continuez la lecture avec offset/limit, ne considérez pas la première page comme l’ensemble des identifiants. Sélectionnez les identifiants applicables selon l’application, le service et l’état de validité, ne prenez pas aveuglément le premier. Une liste vide ne signifie pas que l’autorisation a échoué ; l’utilisateur peut ne pas avoir encore créé de Key applicable. Le contrôle des autorisations de l’OAuth access token et la portée de service, le quota et les conditions d’expiration de l’API Key elle-même sont des contraintes différentes. Autoriser la lecture d’une API Key signifie qu’un tiers peut l’enregistrer et l’utiliser. Révoquer la demande OAuth ou effacer l’état de connexion de l’application ne rendra pas l’API Key déjà copiée invalide ; l’utilisateur doit révoquer ou faire tourner cette Key séparément dans la gestion des identifiants.

Exemple de navigateur Public / PKCE exécutable

Déployez la page suivante sur votre REDIRECT_URI enregistré, remplacez CLIENT_ID et l’adresse de rappel. Le bouton lance l’autorisation standard, puis, après le retour sur la même page, lit le profil personnel et le nombre de Key existantes. L’exemple n’affiche ni ne persiste les Key ; les applications de production consomment les résultats selon leur utilisation réelle. Vérifiez d’abord dans une page de navigateur indépendante, puis validez selon les exigences iframe suivantes.
Le rappel et le point d’entrée de l’exemple doivent être de même origine et dans le même onglet de navigateur/iframe afin de pouvoir lire le sessionStorage précédemment enregistré. Une application de production doit gérer les jetons dans son propre schéma de session, traiter leur expiration et supprimer les paramètres de l’URL d’autorisation après réception de la réponse ; l’interface principale de la page doit d’abord être rendue, et les échecs réseau ne doivent affecter que l’état de connexion.

iframe dans un site en marque blanche

Le site client redirige lui-même vers la page d’autorisation

Utilisez les paramètres OAuth standard et votre propre traitement du rappel ; window.location.assign() navigue dans l’iframe actuel, tandis que la page parente reste sur le domaine de marque blanche. Il n’est pas nécessaire d’ajouter embed=studio pour l’icône ni d’implémenter le protocole de messages Studio. Les conditions suivantes doivent être remplies :
  • La page de l’application et la page de rappel utilisent HTTPS, sont réellement accessibles et autorisent l’intégration par iframe via le domaine parent de marque blanche ; vérifiez Content-Security-Policy: frame-ancestors et X-Frame-Options des deux parties.
  • Le sandbox autorise les scripts, formulaires et capacités d’origine/stockage nécessaires à la page. La prise en charge d’une connexion par fenêtre contextuelle nécessite également les capacités de fenêtre contextuelle correspondantes ; privilégiez la configuration du composant Website fourni par Studio.
  • Le navigateur autorise le stockage nécessaire à l’état d’autorisation dans le scénario d’intégration actuel. L’état de connexion au site en marque blanche et l’état de connexion à AuthFrontend peuvent différer ; ne supposez pas qu’être connecté au site en marque blanche implique déjà d’être connecté à la page d’autorisation.
  • Le service d’échange de jetons dans le rappel est disponible, et les requêtes inter-origines autorisent l’origine de l’application ; les erreurs DNS, CORS et HTTP doivent toutes afficher un état permettant de réessayer, sans empêcher le rendu de toute la page.
La partie gauche de la page d’autorisation lit le logo de l’application OAuth ; la partie droite lit le favicon/logo de ce Site lorsque le navigateur peut fournir l’origine parente et que le domaine parent passe la vérification du site validé, sinon l’icône par défaut est affichée. Cela détermine uniquement l’affichage de la marque, n’établit pas de session de connexion et ne fournit pas de permissions de compte à la page client. Limitation actuelle : lorsque OAuth standard dans un iframe nécessite une nouvelle connexion, le flux permettant de revenir à la page d’autorisation après la connexion comporte encore une lacune. Avant la mise en production, il faut valider séparément les cas « Auth déjà connecté » et « Auth non connecté/expiré ». Avant que cette lacune ne soit corrigée et validée, la première connexion peut utiliser une page indépendante pour effectuer OAuth standard, ou adopter l’autorisation du composant Studio ci-dessous ; ne promettez pas que tous les scénarios d’iframe fonctionneront en vous fondant uniquement sur les résultats de tests déjà connectés.

Utiliser l’autorisation du compte actuel de Studio

Dans Studio, activez OAuth dans « Paramètres → Accueil → Composants de site web », puis renseignez client_id et l’adresse de rappel enregistrée. Le site web et le rappel doivent utiliser la même origine HTTPS, et être différents de l’origine de Studio. La page tierce doit :
  1. Envoyer acedatacloud:oauth:ready à l’origin exact du site parent, recevoir et valider acedatacloud:oauth:init.
  2. Le bouton génère state et le vérificateur PKCE, puis envoie acedatacloud:oauth:authorize (state, challenge S256) ; le vérificateur reste dans sa propre page.
  3. Valider la fenêtre parente, l’origin et state, traiter code ou error dans acedatacloud:oauth:result, puis échanger via le point de terminaison de jetons standard. Studio affiche la page d’autorisation dans la zone des composants. Après consentement de l’utilisateur, le code d’autorisation est renvoyé par message, et l’application n’a pas besoin de rediriger. En l’absence de connexion, renvoie login_required ; en cas de refus, renvoie access_denied ; en cas d’expiration de l’attente, renvoie authorization_timeout. Un changement de compte recrée l’iframe de l’application et annule les autorisations inachevées.
Le composant demande actuellement profile:read credentials:read, sans inclure offline_access. Ne supposez pas qu’un refresh token sera systématiquement reçu. embed=studio et embed_origin sont maintenus par l’hôte Studio et la page d’autorisation ; la page cliente doit uniquement respecter le protocole de messages. Voir l’exemple complet du bouton dans le guide d’intégration OAuth des composants de site Studio.

Cycle de vie, rafraîchissement et révocation

La durée de validité par défaut de l’access token est de 15 jours ; le rafraîchissement ou la nouvelle autorisation doit être planifié selon le expires_in de chaque réponse. Le refresh token est valable 30 jours par défaut, sa durée dépendant de la configuration du service. Ne codez pas ces deux valeurs en dur comme des garanties permanentes. Après obtention de offline_access, vous pouvez appeler :
Le rafraîchissement renvoie de nouveaux tokens, et l’application doit enregistrer les valeurs les plus récentes. Lors du rafraîchissement, il est vérifié que l’application est toujours valide, que l’utilisateur est disponible et que les permissions sont toujours accordées. En cas d’échec, effacez votre propre état de connexion et réautorisez. L’implémentation actuelle du rafraîchissement OAuth ne garantit pas que l’ancien refresh token devienne immédiatement invalide après le rafraîchissement. Ne considérez pas l’obtention d’un nouveau token comme la preuve que l’ancien token a été révoqué, et ne remplacez pas la suppression des tokens existants par une rotation de secret. La méthode d’appel de la demande de révocation est :
Le point de terminaison de révocation actuel renvoie HTTP 200, mais n’implémente pas l’invalidation immédiate des JWT déjà émis. L’application doit effacer les tokens qu’elle a elle-même enregistrés et ne peut pas considérer le code 200 comme une preuve que tous les tokens émis ou toutes les API Keys sont devenus invalides. Les API Keys divulguées ou copiées doivent être révoquées ou renouvelées séparément.

Erreurs courantes et validation

Avant la livraison, vérifiez au minimum : le rappel correct, le refus, un state incorrect, un code expiré/déjà consommé, l’absence de Key, l’échec réseau, l’expiration du token, l’absence du scope requis, ainsi que la première connexion et le changement de compte dans un scénario iframe. Ne conservez pas de code, token ou API Key complet dans les preuves de test.

Vérification en deux étapes et réautorisation

Après l’activation de la vérification en deux étapes par l’utilisateur, Ace Data Cloud effectue sur la page d’autorisation la validation du code de l’application d’authentification ou d’un code de récupération à usage unique, puis délivre le code d’autorisation. Votre application continue d’utiliser le flux OAuth standard et ne doit pas demander, enregistrer ou transférer les clés d’authentificateur ni les codes de récupération de l’utilisateur. Lorsque l’utilisateur active, modifie ou désactive la vérification en deux étapes, ou récupère son compte, les sessions de compte précédentes, les tokens de rafraîchissement et les tokens d’autorisation de plateforme associés peuvent devenir invalides. Lorsque vous recevez une session invalide ou invalid_grant, relancez un processus d’autorisation visible par l’utilisateur ; ne réutilisez pas à plusieurs reprises un ancien code d’autorisation et ne tentez pas de contourner la vérification. La méthode d’authentification des API Keys ordinaires du modèle reste inchangée ; en cas de suspicion de compromission du compte, vérifiez et révoquez séparément les API Keys concernées.