Plateforme d’identités Microsoft et flux de code d’autorisation OAuth
Le type d’octroi de code d’autorisation OAuth 2.0, ou flux de code d’authentification, permet à une application cliente d’obtenir un accès autorisé à des ressources protégées telles que les API web. Le flux de code d’authentification nécessite un agent utilisateur qui prend en charge la redirection à partir du serveur d’autorisation (plateforme d’identités Microsoft) vers votre application. Par exemple, une application de navigateur web, de bureau ou mobile gérée par un utilisateur pour se connecter à votre application et accéder à ses données.
Cet article décrit les détails spécifiques du protocole requis uniquement lors de l’élaboration et de l’émission manuelles de requêtes HTTP brutes pour exécuter le flux, que nous ne recommandons pas. Utilisez plutôt une bibliothèque d’authentification intégrée et prise en charge par Microsoft pour obtenir des jetons de sécurité et appeler des API web protégées dans vos applications.
Applications qui prennent en charge le flux de code d’authentification
Utilisez le flux de code d’authentification associé à PKCE (Proof Key for Code Exchange) et OIDC (OpenID Connect) pour obtenir des jetons d’accès et des jetons d’ID dans ces types d’applications :
- Application web monopage (SPA)
- Application web standard (basée sur le serveur)
- Applications mobiles et de bureau
Détails du protocole
Le flux de code d’autorisation OAuth 2.0 est décrit dans la section 4.1 des spécifications OAuth 2.0. Les applications utilisant le flux de code d’autorisation OAuth 2.0 acquièrent un élément access_token à inclure dans les demandes aux ressources protégées par la plateforme d’identités Microsoft (généralement les API). Les applications peuvent également demander de nouveaux jetons d’ID et d’accès pour les entités précédemment authentifiées à l’aide d’un mécanisme d’actualisation.
Ce diagramme montre une vue de haut niveau du flux d’authentification :
URI de redirection pour les applications monopages (SPA)
Les URI de redirection pour les applications monopages qui utilisent le flux de code d’authentification nécessitent une configuration spéciale.
- Ajoutez un URI de redirection qui prend en charge le flux de code d’authentification avec PKCE et le partage des ressources Cross-Origin (CORS) : suivez les étapes de l’URI de redirection : MSAL.js 2.0 avec flux de code d’authentification.
- Mettez à jour un URI de redirection : définissez l’élément
typede l’URI de redirection surspaen utilisant l’éditeur du manifeste de l’application dans le Centre d’administration Microsoft Entra.
Le type de redirection spa est rétrocompatible avec le flux implicite. Les applications qui utilisent actuellement le flux implicite pour obtenir des jetons peuvent passer au type d’URI de redirection spa sans problème et continuer à utiliser le flux implicite. Malgré cette compatibilité descendante, nous vous recommandons d’utiliser le flux de code d’authentification avec PKCE pour les autorités de service.
Si vous tentez d’utiliser le flux de code d’autorisation sans configurer CORS pour votre URI de redirection, vous verrez cette erreur dans la console :
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Si c’est le cas, accédez à votre inscription d’application et mettez à jour l’URI de redirection de votre application pour utiliser le type spa.
Les applications ne peuvent pas utiliser un URI de redirection spa avec des flux non SPA, par exemple des applications natives ou des flux d’informations d’identification du client. Pour garantir la sécurité et le respect des meilleures pratiques, la Plateforme d’identités Microsoft retourne une erreur si vous tentez d’utiliser un URI de redirection spa sans en-tête Origin. De même, la Plateforme d’identités Microsoft empêche également l’utilisation des informations d’identification du client dans tous les flux en présence d’un en-tête Origin afin de s’assurer que les secrets ne sont pas utilisés depuis le navigateur.
Demander un code d’autorisation
Le flux de code d'autorisation commence par le client dirigeant l'utilisateur vers le point de terminaison /authorize . Dans cette exemple de demande, le client demande les autorisations openid, offline_access et https://graph.microsoft.com/mail.read de l’utilisateur.
Certaines autorisations sont limitées à l’administrateur, par exemple l’écriture de données dans le répertoire d’une organisation à l’aide de Directory.ReadWrite.All. Si votre application requiert l’accès à l’une de ces autorisations d’un utilisateur de l’organisation, ce dernier recevra un message d’erreur indiquant qu’il n’est pas autorisé à donner son consentement pour les permissions de votre application. Pour demander l'accès aux étendues limitées par l’administrateur, vous devez vous adresser directement à un administrateur général. Pour plus d’informations, consultez Autorisations limitées à l’administrateur.
Sauf indication contraire, il n’existe aucune valeur par défaut pour les paramètres facultatifs. Toutefois, il existe un comportement par défaut pour une requête qui omet les paramètres facultatifs. Le comportement par défaut consiste à se connecter au seul utilisateur actuel, à afficher le sélecteur de compte s’il y a plusieurs utilisateurs, ou à afficher la page de connexion si aucun utilisateur n’est connecté.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Paramètre | Obligatoire ou facultatif | Description |
|---|---|---|
tenant |
requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les utilisateurs qui peuvent se connecter à l’application. Les valeurs valides sont common, organizations, consumers et les identificateurs de locataire. Dans les scénarios d’invités, quand vous connectez l’utilisateur d’un locataire à un autre locataire, vous devez fournir l’identificateur du locataire pour connecter l’utilisateur au locataire des ressources. Pour plus d’informations, consultez Point de terminaison. |
client_id |
requis | L’ID d’application (client) que l’expérience Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application. |
response_type |
requis | Doit inclure code pour le flux de code d’autorisation. Peut également inclure id_token ou token si vous utilisez le flux hybride. |
redirect_uri |
obligatoire | redirect_uri de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Il doit correspondre exactement à l’un des URI de redirection enregistrés dans le centre d’administration Microsoft Entra, à l’exception qu’il doit être codé au format URL. Pour les applications mobiles et natives, utilisez l’une des valeurs recommandées : https://login.microsoftonline.com/common/oauth2/nativeclient pour les applications utilisant des navigateurs incorporés ou http://localhost pour les applications qui utilisent des navigateurs système. |
scope |
Obligatoire | Liste séparée par des espaces d’ étendues pour lesquelles vous souhaitez que l’utilisateur donne son consentement. Pour le tronçon /authorize de la requête, ce paramètre peut couvrir plusieurs ressources. Cette valeur permet à votre application d’obtenir le consentement pour plusieurs API web que vous souhaitez appeler. |
response_mode |
recommandé | Spécifie comment la plateforme d’identité doit retourner le jeton demandé à votre application. Valeurs prises en charge : - query : valeur par défaut lors de la demande d’un jeton d’accès. Fournit le code en tant que paramètre d’une chaîne de requête sur votre URI de redirection. Le paramètre query n’est pas pris en charge lors de la demande d’un jeton d’ID à l’aide du flux implicite. - fragment : valeur par défaut lors de la demande d’un jeton d’ID à l’aide du flux implicite. Également pris en charge en cas de demande d’un code seulement.- form_post : exécute une requête POST contenant le code pour votre URI de redirection. Pris en charge lors de la demande d’un code. |
state |
recommandé | Une valeur incluse dans la requête qui est également renvoyée dans la réponse de jeton. Il peut s’agir d’une chaîne du contenu de votre choix. Une valeur unique générée de manière aléatoire est généralement utilisée pour empêcher les falsifications de requête intersite. La valeur peut également encoder les informations sur l’état de l’utilisateur dans l’application avant la requête d’authentification. Par exemple, il peut encoder la page ou la vue où l’utilisateur se trouvait. |
prompt |
facultatif | Indique le type d’interaction utilisateur requis. Les valeurs valides sont login, none, consent et select_account.- prompt=login force l’utilisateur à saisir ses informations d’identification lors de cette requête, annulant de fait l’authentification unique.- prompt=none est le contraire. Cette valeur garantit qu’aucune invite interactive ne s’affiche pour l’utilisateur. Si la requête ne peut pas être effectuée en mode silencieux via l’authentification unique, la Plateforme d’identités Microsoft retourne une erreur interaction_required.- prompt=consent déclenche la boîte de dialogue de consentement OAuth après la connexion de l’utilisateur, afin de lui demander d’accorder des autorisations à l’application.- prompt=select_account interrompt l’authentification unique en fournissant une expérience de sélection de compte répertoriant tous les comptes dans la session ou tout compte mémorisé, ou une option pour choisir d’utiliser un autre compte. |
login_hint |
facultatif | Vous pouvez utiliser ce paramètre pour remplir au préalable le champ réservé au nom d’utilisateur et à l’adresse e-mail de la page de connexion de l’utilisateur. Les applications peuvent utiliser ce paramètre durant la réauthentification, après avoir extrait la revendication facultative login_hint d’une connexion antérieure. |
domain_hint |
facultatif | Si ce paramètre est inclus, l’application ignore le processus de découverte par e-mail que l’utilisateur rencontre sur la page de connexion, ce qui améliore légèrement l’expérience utilisateur. Par exemple, en les envoyant vers leur fournisseur d’identité fédérée. Les applications peuvent utiliser ce paramètre au cours de la réauthentification, en extrayant l’élément tid à partir d’une connexion précédente. |
code_challenge |
recommandé/obligatoire | Utilisé pour sécuriser l’octroi du code d’autorisation via PKCE (Proof Key for Code Exchange). Obligatoire si code_challenge_method est inclus. Pour plus d'informations, consultez le RFC PKCE. Ce paramètre est désormais recommandé pour tous les types d’application (clients publics et confidentiels) et requis pour la Plateforme d’identités Microsoft pour les applications monopage qui utilisent le flux de code d’autorisation. |
code_challenge_method |
recommandé/obligatoire | La méthode utilisée pour encoder le code_verifier pour le paramètre code_challenge. Ce DEVRAIT être S256, mais la spécification autorise l’utilisation de plain si le client ne peut pas prendre en charge SHA256. S’il est exclu, code_challenge est censé être dans un texte en clair si code_challenge est inclus. La plateforme d’identités Microsoft prend en charge plain et S256. Pour plus d'informations, consultez le RFC PKCE. Ce paramètre est obligatoire pour les applications monopage utilisant le flux de code d’autorisation. |
À ce stade, l’utilisateur est invité à saisir ses informations d’identification et à exécuter l’authentification. La Plateforme d’identités Microsoft s’assure également que l’utilisateur a accepté les autorisations indiquées dans le paramètre de requête scope. Si l’utilisateur n’a pas accepté l’une ou plusieurs de ces autorisations, il est invité à consentir aux autorisations nécessaires. Pour plus d’informations, consultez Autorisations et consentement dans la Plateforme d’identités Microsoft.
Une fois que l’utilisateur a procédé à l’authentification et accordé son consentement, la plateforme d’identités Microsoft retourne une réponse à votre application à l’URI redirect_uri indiqué à l’aide de la méthode spécifiée dans le paramètre response_mode.
Réponse correcte
Cet exemple montre une réponse réussie avec response_mode=query :
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Paramètre | Description |
|---|---|
code |
authorization_code que l’application a demandé. L’application peut utiliser le code d’autorisation afin de demander un jeton d’accès pour la ressource cible. Les codes d’autorisation ont des durées de vie courtes. Généralement, ils expirent au bout de 10 minutes. |
state |
Si un paramètre state est inclus dans la demande, la même valeur doit apparaître dans la réponse. L’application doit vérifier que les valeurs d’état de la demande et de la réponse sont identiques. |
Vous pouvez également recevoir un jeton d’ID si vous en demandez un et avez activé l’octroi implicite dans votre inscription d’application. Ce comportement est parfois appelé flux hybride. Il est utilisé par des infrastructures comme ASP.NET.
Réponse d’erreur
Les réponses d’erreur peuvent également être envoyées à l’élément redirect_uri , de manière à ce que l’application puisse les traiter de manière appropriée :
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Paramètre | Description |
|---|---|
error |
Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre. Cette partie de l’erreur est fournie afin que l’application puisse réagir de manière appropriée à l’erreur, mais elle n’explique pas en détail pourquoi l’erreur s’est produite. |
error_description |
Un message d’erreur spécifique qui peut aider un développeur à identifier la cause d’une erreur d’authentification. Cette partie de l’erreur contient la plupart des informations utiles sur les raisons pour lesquelles l’erreur s’est produite. |
Codes d’erreur pour les erreurs de point de terminaison d’autorisation
Le tableau suivant décrit les différents codes d’erreur qui peuvent être retournés dans le paramètre error de la réponse d’erreur.
| Code d'erreur | Description | Action du client |
|---|---|---|
invalid_request |
Erreur de protocole, tel qu’un paramètre obligatoire manquant. | Corrigez l’erreur, puis envoyez à nouveau la demande. Cette erreur est une erreur de développement généralement détectée lors des tests initiaux. |
unauthorized_client |
L’application cliente n’est pas autorisée à demander un code d’autorisation. | Cette erreur se produit généralement lorsque l’application cliente n’est pas inscrite auprès de Microsoft Entra ID ou n’est pas ajoutée au locataire Microsoft Entra de l’utilisateur. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Microsoft Entra ID. |
access_denied |
Le propriétaire de la ressource n’a pas accordé son consentement. | L’application cliente peut avertir l’utilisateur qu’il est impossible de continuer sans son consentement. |
unsupported_response_type |
Le serveur d’autorisation ne prend pas en charge le type de réponse dans la requête. | Corrigez l’erreur, puis envoyez à nouveau la demande. Cette erreur est une erreur de développement généralement détectée lors des tests initiaux. Dans le flux hybride, cette erreur signale que vous devez activer le paramètre d’octroi implicite du jeton d’ID sur l’inscription de l’application cliente. |
server_error |
Le serveur a rencontré une erreur inattendue. | Relancez la requête. Ces erreurs peuvent résulter de conditions temporaires. L’application cliente peut expliquer à l’utilisateur que sa réponse est retardée en raison d’une erreur temporaire. |
temporarily_unavailable |
Le serveur est temporairement trop occupé pour traiter la demande. | Relancez la requête. L’application cliente peut expliquer à l’utilisateur que sa réponse est reportée en raison d’une condition temporaire. |
invalid_resource |
La ressource cible n’est pas valide car elle n’existe pas, Microsoft Entra ID ne la trouve pas ou elle n’est pas configurée correctement. | Cette erreur indique que la ressource, si elle existe, n’a pas été configurée dans le locataire. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Microsoft Entra ID. |
login_required |
Trop d’utilisateurs ou aucun utilisateur trouvé. | Le client a demandé l’authentification en mode silencieux (prompt=none), mais un utilisateur unique est introuvable. Cette erreur peut signifier que plusieurs utilisateurs sont actifs dans la session, ou qu’il n’y a aucun utilisateur. Cette erreur prend en compte le locataire choisi. Par exemple, si vous disposez de deux comptes Microsoft Entra actifs et d’un compte Microsoft, et que consumers est choisi, l’authentification en mode silencieux fonctionne. |
interaction_required |
La demande nécessite une interaction utilisateur. | Une étape d’authentification ou un consentement supplémentaire est nécessaire. Relancez la requête sans prompt=none. |
Demander également un jeton d’ID ou le flux hybride
Pour savoir qui est l’utilisateur avant d’échanger un code d’autorisation, il est courant que les applications demandent également un jeton d’ID lorsqu’elles demandent le code d’autorisation. Cette approche est appelée flux hybride, car elle associe OIDC au flux du code d’autorisation OAuth2.
Le flux hybride est couramment utilisé dans les applications web afin d’afficher une page pour un utilisateur sans bloquer l’échange de code, notamment dans ASP.NET. Ce modèle permet de réduire la latence des applications monopages et des applications web traditionnelles.
Le flux hybride est similaire au flux de code d’autorisation décrit précédemment, mais comprend trois éléments supplémentaires. Ces éléments supplémentaires sont requis pour demander un jeton d’ID : nouvelles étendues, nouveau paramètre response_type et un nouveau paramètre de requête nonce.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Paramètre mis à jour | Obligatoire ou facultatif | Description |
|---|---|---|
response_type |
Obligatoire | L’ajout de id_token indique au serveur que l’application aimerait un jeton d’ID dans la réponse du point de terminaison /authorize. |
scope |
obligatoire | Pour les jetons d’ID, ce paramètre doit être mis à jour pour inclure les étendues de jeton d’ID : openid, voire profile et email (facultatif). |
nonce |
Obligatoire | Valeur incluse dans la demande (générée par l’application) qui est intégrée au jeton id_token obtenu sous la forme d’une revendication. L’application peut ensuite vérifier cette valeur afin de contrer les attaques par relecture de jetons. La valeur est généralement une chaîne unique et aléatoire qui peut être utilisée pour identifier l’origine de la requête. |
response_mode |
recommandé | Spécifie la méthode à utiliser pour envoyer le jeton résultant à votre application. La valeur par défaut est query pour un code d’autorisation uniquement, mais fragment si la requête comprend un id_token response_type tel que spécifié dans la spécification OpenID. Nous recommandons que les applications utilisent form_post, en particulier si http://localhost est utilisé comme URI de redirection. |
L’utilisation de fragment comme mode de réponse entraîne des problèmes pour les applications web qui lisent le code à partir de la redirection. Les navigateurs ne transmettent pas le fragment au serveur web. Dans ces situations, les applications doivent utiliser le mode de réponse form_post pour garantir l’envoi de toutes les données au serveur.
Réponse correcte
Cet exemple montre une réponse réussie avec response_mode=fragment :
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Paramètre | Description |
|---|---|
code |
Le code d’autorisation demandé par l’application. L’application peut utiliser ce code d’autorisation pour demander un jeton d’accès pour la ressource cible. Les codes d’autorisation présentent une durée de vie courte et expirent généralement au bout de 10 minutes. |
id_token |
Jeton d’ID pour l’utilisateur, émis via octroi implicite. Contient une revendication c_hash spéciale qui est le hachage du code dans la même requête. |
state |
Si un paramètre state est inclus dans la demande, la même valeur doit apparaître dans la réponse. L’application doit vérifier que les valeurs state de la requête et de la réponse sont identiques. |
Échanger un code pour un jeton d’accès
Tous les clients confidentiels peuvent utiliser soit les secrets du client soit les informations d’identification de certificat. Les secrets partagés symétriques sont générés par la Plateforme d’identités Microsoft. Les informations d’identification de certificat sont des clés asymétriques chargées par le développeur. Pour plus d’informations, consultez Informations d’identification de certificat d’authentification d’application de la Plateforme d’identités Microsoft.
Pour une sécurité optimale, nous vous recommandons d’utiliser des informations d’identification de certificat. Les clients publics, qui incluent des applications natives et des applications monopage, ne doivent pas utiliser de secrets ni de certificats quand vous acceptez un code d’autorisation. Vérifiez toujours que les URI de redirection incluent le type d’application et sont uniques.
Demander un jeton d’accès avec un client_secret
Maintenant que vous avez acquis un authorization_code et que l’utilisateur vous a octroyé une autorisation, vous pouvez accepter code contre un access_token sur la ressource. Acceptez code une requête en envoyant /token au point de terminaison POST :
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Paramètre | Obligatoire ou facultatif | Description |
|---|---|---|
tenant |
requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les utilisateurs qui peuvent se connecter à l’application. Les valeurs valides sont common, organizations, consumers et les identificateurs de locataire. Pour plus d’informations, consultez Point de terminaison. |
client_id |
requis | L’ID d’application (client) que la page Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application. |
scope |
facultatifs | Liste d’étendues séparées par des espaces. Les étendues doivent toutes être issues d’une seule ressource, ainsi que les étendues OIDC (profile, openid, email). Pour plus d’informations, consultez Autorisations et consentement dans la Plateforme d’identités Microsoft. Ce paramètre est une extension Microsoft du flux de code d’autorisation permettant aux applications de déclarer la ressource pour laquelle elles souhaitent obtenir le jeton lors de l’échange de jetons. |
code |
obligatoire | authorization_code que vous avez acquis lors de la première phase du flux. |
redirect_uri |
obligatoire | Même valeur redirect_uri que celle utilisée pour acquérir l’authorization_code. |
grant_type |
Obligatoire | Doit être authorization_code pour le flux de code d'autorisation. |
code_verifier |
recommandé | Même code_verifier que celui utilisé pour obtenir l’authorization_code. Obligatoire si PKCE est utilisé dans la requête d’octroi du code d’autorisation. Pour plus d'informations, consultez le RFC PKCE. |
client_secret |
obligatoire pour les applications web confidentielles | Le secret d’application que vous avez créé dans le portail d’inscription des applications pour votre application. N’utilisez pas le secret d’application dans une application native ou monopage, car un secret client_secret ne peut pas être stocké de manière fiable sur des appareils ou des pages web. Il est requis pour les applications web et les API web, qui peuvent stocker en toute sécurité l’élément client_secret côté serveur. Comme tous les paramètres décrits ici, la clé secrète client doit être encodée par URL avant d’être envoyée. Cette étape est effectuée par le kit SDK. Pour plus d’informations sur l’encodage d’URI, consultez la spécification de syntaxe générique URI. Le modèle d'authentification de base, qui consiste à fournir les informations d'identification dans l'en-tête d'autorisation, conformément à la RFC 6749, est également pris en charge. |
Demander un jeton d’accès avec des informations d’identification de certificat
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Paramètre | Obligatoire ou facultatif | Description |
|---|---|---|
tenant |
requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les utilisateurs qui peuvent se connecter à l’application. Les valeurs valides sont common, organizations, consumers et les identificateurs de locataire. Pour plus d’informations, consultez Points de terminaison. |
client_id |
requis | L’ID d’application (client) que la page Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application. |
scope |
facultatifs | Liste d’étendues séparées par des espaces. Les étendues doivent toutes être issues d’une seule ressource, ainsi que les étendues OIDC (profile, openid, email). Pour plus d’informations, consultez autorisations, consentement et étendues. Ce paramètre est une extension Microsoft du flux de code d’autorisation. Cette extension permet aux applications de déclarer la ressource pour laquelle le jeton est nécessaire pendant l’échange de jetons. |
code |
obligatoire | authorization_code que vous avez acquis lors de la première phase du flux. |
redirect_uri |
obligatoire | Même valeur redirect_uri que celle utilisée pour acquérir l’authorization_code. |
grant_type |
Obligatoire | Doit être authorization_code pour le flux de code d'autorisation. |
code_verifier |
recommandé | authorization_code identique à celui qui a été utilisé pour obtenir le code_verifier. Obligatoire si PKCE est utilisé dans la requête d’octroi du code d’autorisation. Pour plus d'informations, consultez le RFC PKCE. |
client_assertion_type |
obligatoire pour les applications web confidentielles | La valeur doit être définie sur urn:ietf:params:oauth:client-assertion-type:jwt-bearer pour utiliser des informations d’identification de certificat. |
client_assertion |
obligatoire pour les applications web confidentielles | Assertion (JSON Web Token (JWT)) dont vous avez besoin pour créer et signer avec le certificat que vous avez inscrit en tant qu’informations d’identification pour votre application. Pour découvrir comment inscrire votre certificat et le format de l’assertion, consultez la rubrique traitant des informations d’identification des certificats. |
Les paramètres sont identiques à ceux de la requête par secret partagé, sauf que le paramètre client_secret est remplacé par deux paramètres : client_assertion_type et client_assertion.
Réponse correcte
Cet exemple montre une réponse de jeton réussie :
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Paramètre | Description |
|---|---|
access_token |
Le jeton d’accès demandé. L’application peut utiliser ce jeton pour s’authentifier auprès de la ressource sécurisée, telle qu’une API web. |
token_type |
Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra ID est Bearer. |
expires_in |
Durée de validité (en secondes) du jeton d’accès. |
scope |
Étendues de validité du jeton access_token. facultatif. Ce paramètre n’est pas standard. S’il est omis, le jeton est destiné aux étendues demandées sur la branche initiale du flux. |
refresh_token |
Un jeton d’actualisation OAuth 2.0. L’application peut utiliser ce jeton pour acquérir des jetons d’accès supplémentaires après l’expiration du jeton d’accès actuel. Les jetons d’actualisation sont de longue durée. Ils peuvent conserver l’accès aux ressources pendant des périodes prolongées. Pour plus d’informations sur l’actualisation d’un jeton d’accès, consultez Actualiser le jeton d’accès plus loin dans cet article. Remarque : Fourni uniquement si l’étendue offline_access a été demandée. |
id_token |
Jeton JSON Web Token. L’application peut décoder les segments de ce jeton pour demander des informations sur l’utilisateur qui s’est connecté. L’application peut mettre en cache les valeurs et les afficher. Les clients confidentiels peuvent utiliser ce jeton pour obtenir une autorisation. Pour en savoir plus sur id_tokens, consultez id_token reference. Remarque : Fourni uniquement si l’étendue openid a été demandée. |
Réponse d’erreur
Cet exemple représente une réponse d’erreur :
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Paramètre | Description |
|---|---|
error |
Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre. |
error_description |
Un message d’erreur spécifique qui peut aider un développeur à identifier la cause d’une erreur d’authentification. |
error_codes |
Liste des codes d’erreur STS spécifiques pouvant être utiles dans les tests de diagnostic. |
timestamp |
Heure à laquelle l’erreur s’est produite. |
trace_id |
Identifiant unique de la demande pouvant être utile dans les tests de diagnostic. |
correlation_id |
Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants. |
Codes d’erreur pour les erreurs de point de terminaison de jeton
| Code d'erreur | Description | Action du client |
|---|---|---|
invalid_request |
Erreur de protocole, tel qu’un paramètre obligatoire manquant. | Corriger la requête ou l’inscription d’application et renvoyer la requête. |
invalid_grant |
Le code d’autorisation ou le vérificateur du code PCKE n’est pas valide ou a expiré. | Essayez une nouvelle requête au point de terminaison /authorize et vérifiez que le paramètre code_verifier est correct. |
unauthorized_client |
Le client authentifié n’est pas autorisé à utiliser ce type d’octroi d’autorisation. | Cette erreur se produit généralement lorsque l’application cliente n’est pas inscrite auprès de Microsoft Entra ID ou n’est pas ajoutée au locataire Microsoft Entra de l’utilisateur. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Microsoft Entra ID. |
invalid_client |
Échec d’authentification du client. | Les informations d’identification du client ne sont pas valides. Pour résoudre le problème, l’administrateur de l’application met à jour les informations d’identification. |
unsupported_grant_type |
Le serveur d’autorisation ne prend pas en charge le type d’octroi d’autorisation. | Modifiez le type d’octroi dans la demande. Ce type d’erreur doit se produire uniquement lors du développement et doit être détecté lors du test initial. |
invalid_resource |
La ressource cible n’est pas valide car elle n’existe pas, Microsoft Entra ID ne la trouve pas ou elle n’est pas configurée correctement. | Ce code indique que la ressource, le cas échéant, n’a pas été configurée dans le locataire. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Microsoft Entra ID. |
interaction_required |
Non standard, car la spécification OIDC appelle ce code uniquement sur le point de terminaison /authorize. La demande nécessite une interaction utilisateur. Par exemple, une autre étape d’authentification est nécessaire. |
Relancez la requête /authorize avec les mêmes étendues. |
temporarily_unavailable |
Le serveur est temporairement trop occupé pour traiter la demande. | Relancez la requête après un petit délai. L’application cliente peut expliquer à l’utilisateur que sa réponse est reportée en raison d’une condition temporaire. |
consent_required |
La requête nécessite le consentement de l’utilisateur. Cette erreur n’est pas standard. Elle est généralement retournée uniquement sur le point de terminaison /authorize par spécifications OIDC. Retournée quand un paramètre scope a été utilisé sur le flux d’acceptation du code et que l’application cliente n’a pas l’autorisation d’envoyer de requête. |
Le client doit renvoyer l’utilisateur au point de terminaison /authorize avec l’étendue correcte pour déclencher le consentement. |
invalid_scope |
L’étendue demandée par l’application n’est pas valide. | Mettez à jour la valeur du paramètre scope dans la requête d’authentification en la remplaçant par une valeur valide. |
Notes
Les applications monopages peuvent recevoir un message d’erreur invalid_request indiquant qu’un échange de jetons cross-origin n’est autorisé que pour le type de client « application monopage ». Cela indique que l’URI de redirection utilisé pour demander le jeton n’a pas été marqué comme URI de redirection de spa. Pour voir comment activer ce flux, examinez les étapes d’inscription d’application.
Utiliser le jeton d’accès
Maintenant que vous avez acquis un jeton access_token, vous pouvez l’utiliser dans des requêtes adressées à des API web en l’incluant dans l’en-tête Authorization :
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Actualiser le jeton d’accès
Les jetons d’accès ont une durée de vie courte. Actualisez-les après leur expiration pour continuer à accéder aux ressources. Pour ce faire, envoyez une nouvelle demande POST au point de terminaison /token. Fournissez refresh_token au lieu de code. Les jetons d’actualisation sont valides pour toutes les autorisations pour lesquelles votre client a déjà reçu le consentement. Par exemple, un jeton d’actualisation émis sur une requête pour scope=mail.read peut être utilisé pour demander un nouveau jeton d’accès pour scope=api://contoso.com/api/UseResource.
Les jetons d’actualisation pour les applications web et natives n’ont pas de durée de vie spécifiée. En règle générale, leur durée de vie est relativement longue. Toutefois, dans certains cas, les jetons d’actualisation expirent, sont révoqués ou ne disposent pas de privilèges suffisants pour l’action. Votre application doit s’attendre aux erreurs retournées par le point de terminaison d’émission de jeton et les traiter. Les applications monopages obtiennent un jeton d’une durée de vie de 24 heures, ce qui nécessite une nouvelle authentification quotidienne. Cette action peut être effectuée en mode silencieux dans un iframe quand les cookies tiers sont activés. Elle doit être effectuée dans un cadre de niveau supérieur, une navigation de page complète ou une fenêtre contextuelle, dans des navigateurs sans cookies tiers, comme Safari.
Les jetons d’actualisation ne sont pas révoqués quand ils sont utilisés pour acquérir de nouveaux jetons d’accès. Vous êtes censé abandonner l’ancien jeton d’actualisation. La spécification OAuth 2.0 indique ce qui suit : « Le serveur d’autorisation PEUT émettre un nouveau jeton d’actualisation, auquel cas, le client DOIT ignorer l’ancien jeton d’actualisation et le remplacer par le nouveau. Le serveur d’autorisation PEUT révoquer l’ancien jeton d’actualisation après en avoir émis un nouveau pour le client. »
Important
Pour les jetons d’actualisation envoyés à un URI de redirection inscrit en tant que spa, le jeton d’actualisation expire au bout de 24 heures. Les jetons d’actualisation supplémentaires acquis à l’aide du jeton d’actualisation initial répercutant ce délai d’expiration, les applications doivent être prêtes à réexécuter le flux de code d’autorisation en utilisant une authentification interactive pour obtenir un nouveau jeton d’actualisation toutes les 24 heures. Les utilisateurs n’ont pas besoin d’entrer leurs informations d’identification. En général, ils ne remarquent aucune expérience utilisateur, juste un rechargement de votre application. Le navigateur doit accéder à la page de connexion dans un frame de niveau supérieur pour voir la session de connexion. Cela est dû aux fonctionnalités de confidentialité dans les navigateurs qui bloquent les cookies tiers.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Paramètre | Type | Description |
|---|---|---|
tenant |
requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les utilisateurs qui peuvent se connecter à l’application. Les valeurs valides sont common, organizations, consumers et les identificateurs de locataire. Pour plus d’informations, consultez Point de terminaison. |
client_id |
requis | L’ID d’application (client) que l’expérience Inscriptions d’applications du centre d’administration Microsoft Entra a attribué à votre application. |
grant_type |
requis | Doit inclure refresh_token pour ce tronçon du flux de code d'autorisation. |
scope |
facultatif | Liste d’étendues séparées par des espaces. Les étendues requises dans ce tronçon doivent être équivalentes aux étendues requises dans le premier tronçon, ou correspondre au premier tronçon de requête d’origine authorization_code. Si les étendues spécifiées dans cette requête couvrent plusieurs serveurs de ressources, la Plateforme d’identités Microsoft retourne un jeton pour la ressource spécifiée dans la première étendue. Pour plus d’informations, consultez Autorisations et consentement dans la Plateforme d’identités Microsoft. |
refresh_token |
obligatoire | Jeton refresh_token que vous avez acquis dans le second tronçon du flux. |
client_secret |
requis pour les applications Web | Secret d’application que vous avez créé dans le portail d’inscription des applications pour votre application. Il ne doit pas être utilisé dans une application native, car une clé client_secret ne peut pas être stockée de manière fiable sur les appareils. Il est requis pour les applications web et les API web, qui peuvent stocker en toute sécurité l’élément client_secret côté serveur. Ce secret doit se présenter sous la forme d’un code URL. Pour plus d’informations, consultez la spécification de syntaxe générique URI. |
Réponse correcte
Cet exemple montre une réponse de jeton réussie :
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Paramètre | Description |
|---|---|
access_token |
Le jeton d’accès demandé. L’application peut utiliser ce jeton pour s’authentifier auprès de la ressource sécurisée, telle qu’une API web. |
token_type |
Indique la valeur du type de jeton. Le seul type pris en charge par Microsoft Entra ID est Porteur. |
expires_in |
Durée de validité (en secondes) du jeton d’accès. |
scope |
Étendues de validité du jeton access_token. |
refresh_token |
Un nouveau jeton d’actualisation OAuth 2.0. Remplacez l’ancien jeton d’actualisation par ce nouveau jeton d’actualisation nouvellement acquis, afin de vous assurer que vos jetons d’actualisation demeurent valides le plus longtemps possible. Remarque : Fourni uniquement si l’étendue offline_access a été demandée. |
id_token |
Jeton JSON Web Token non signé. L’application peut décoder les segments de ce jeton pour demander des informations sur l’utilisateur qui s’est connecté. L’application peut mettre en cache les valeurs et les afficher, mais elle ne doit pas se reposer sur elles pour les limites d’autorisation ou de sécurité. Pour plus d’informations sur id_token, consultez la section Jetons d’ID de la Plateforme d’identités Microsoft. Remarque : Fourni uniquement si l’étendue openid a été demandée. |
Avertissement
N’essayez pas de valider ou de lire des jetons pour des API dont vous n’êtes pas propriétaire, y compris les jetons de cet exemple, dans votre code. Les jetons associés aux services Microsoft peuvent utiliser un format spécial qui n’est pas validé comme jeton JWT, et peuvent également être chiffrés pour les utilisateurs consommateurs (de comptes Microsoft). Même si la lecture des jetons est un outil utile de débogage et d’apprentissage, n’y associez pas de dépendances dans votre code ou tenez compte des spécificités des jetons qui ne correspondent pas à une API que vous contrôlez.
Réponse d’erreur
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Paramètre | Description |
|---|---|
error |
Chaîne de code d’erreur qui peut être utilisée pour classifier les types d’erreurs et y répondre. |
error_description |
Un message d’erreur spécifique qui peut aider un développeur à identifier la cause principale d’une erreur d’authentification. |
error_codes |
Liste des codes d’erreur STS spécifiques pouvant être utiles dans les tests de diagnostic. |
timestamp |
Heure à laquelle l’erreur s’est produite. |
trace_id |
Identifiant unique de la demande pouvant être utile dans les tests de diagnostic. |
correlation_id |
Identifiant unique de la demande pouvant être utile dans les tests de diagnostic sur les divers composants. |
Pour obtenir une description des codes d’erreur et connaître l’action client recommandée, consultez Codes d’erreur pour les erreurs de point de terminaison de jeton.
Étapes suivantes
- Consultez les exemples JS MSAL pour commencer à coder.
- En savoir plus sur les scénarios d’échange de jetons.