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 du protocole de bas niveau généralement 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 :

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.

Conseil

Essayez d’exécuter cette requête dans Postman
Essayez d’exécuter cette requête et plus encore dans Postman -- n’oubliez pas de remplacer les jetons et les ID !

Ce diagramme montre une vue de haut niveau du flux d’authentification :

Diagramme montrant le flux de code d’autorisation OAuth. L’application native et l’API web interagissent en utilisant des jetons, comme cela est décrit dans cet article.

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.

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.

Si vous tentez d’utiliser le flux de code d’autorisation sans configurer CORS pour votre URI de redirection, cette erreur s’affiche 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 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Conseil

Sélectionnez le lien ci-dessous pour exécuter cette requête. Une fois que vous êtes connecté, votre navigateur doit être redirigé vers http://localhost/myapp/ avec une valeur code dans la barre d’adresse. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Paramètre Obligatoire ou facultatif Description
tenant Obligatoire 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 Obligatoire L’ID (client) d’application attribué à votre application par l’environnement Inscriptions d’applications du portail Azure.
response_type Obligatoire 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. Ce paramètre doit correspondre exactement à l’un des URI de redirection enregistrés dans le portail et doit être encodé 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 login_hintrevendication facultative 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 dans Azure AD ou n’est pas ajoutée au client Azure AD de l’utilisateur. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Azure AD.
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, Azure AD 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 à Azure AD.
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. S’il existe par exemple deux comptes Azure AD actifs et 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 l’octroi implicite au flux du code d’autorisation.

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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 uniquement pour un code d’autorisation, mais fragment si la demande comprend un id_tokenresponse_type comme indiqué dans les spécifications OpenID. Nous recommandons que les applications utilisent form_post, en particulier lors de l’utilisation de http://localhost en tant qu’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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
Paramètre Obligatoire ou facultatif Description
tenant Obligatoire 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 obligatoire ID (client) d’application attribué à votre application par la page Inscriptions d’applications du portail Azure.
scope facultatif 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 généralement 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

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 Obligatoire 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 obligatoire ID (client) d’application attribué à votre application par la page Inscriptions d’applications du portail Azure.
scope facultatif 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 de jeton pris en charge par Azure AD 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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 dans Azure AD ou n’est pas ajoutée au client Azure AD de l’utilisateur. L’application peut proposer à l’utilisateur des instructions pour installer l’application et l’ajouter à Azure AD.
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, Azure AD 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 à Azure AD.
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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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 Obligatoire 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 Obligatoire L’ID (client) d’application attribué à votre application par l’environnement Inscriptions d’applications du portail Azure.
grant_type Obligatoire 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 de jeton pris en charge par Azure AD est le jeton 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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