Flux OpenID Connect/OAuth avec AD FS et scénarios d’application
S’applique à AD FS 2019 et aux versions ultérieures
| Scénario | Procédure pas à pas de scénario utilisant des exemples | Canal/octroi OAuth 2.0 | Type de client |
|---|---|---|---|
| Application monopage | Exemple utilisant MSAL | Implicite | Public |
| Application web qui connecte des utilisateurs | Exemple utilisant OWIN | Code d’autorisation | Public, confidentiel |
| Une application native appelle une API web | Exemple utilisant MSAL | Code d’autorisation | Public |
| Une application web appelle une API web | Exemple utilisant MSAL | Code d’autorisation | Confidentiel |
| Une API web appelle une autre API web pour le compte de l’utilisateur | Exemple utilisant MSAL | On-behalf-of | L’application web agit en tant que confidentielle |
| L’application démon appelle une API web | Informations d’identification du client | Confidentiel | |
| Application web qui appelle l’API web à l’aide des informations d’identification d’utilisateur | Informations d’identification du mot de passe du propriétaire de la ressource | Public, confidentiel | |
| Une application sans navigateur appelle une API web | Code d’appareil | Public, confidentiel |
Octroi de flux implicite
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux d'octroi implicite dans Microsoft Entra ID, consultez Flux d'octroi implicite dans la plateforme d'identités Microsoft.
Pour les applications monopages (AngularJS, Ember.js, React.js, et ainsi de suite), AD FS prend en charge le flux d’octroi implicite OAuth 2.0. Le flux implicite est décrit dans la spécification OAuth 2.0. Son principal avantage est qu’il permet à l’application d’obtenir des jetons à partir d’AD FS sans effectuer d’échange d’informations d’identification de serveur back-end. Ce flux permet à l’application de connecter l’utilisateur, de maintenir la session et d’obtenir des jetons pour d’autres API web dans le code JavaScript du client. Il existe quelques considérations importantes en matière de sécurité à prendre en compte lors de l’utilisation du flux implicite, spécifiquement liées au client.
Si vous souhaitez utiliser le flux implicite et AD FS pour ajouter l’authentification à votre application JavaScript, suivez les étapes générales de la section suivante.
Diagramme de protocole
Le diagramme suivant montre à quoi ressemble le flux implicite de connexion complet. Les sections qui suivent décrivent chaque étape plus en détail.
Demander le jeton d’ID et le jeton d’accès
Pour connecter initialement l’utilisateur à votre application, vous pouvez envoyer une requête d’authentification OpenID Connect et obtenir id_token et un jeton d’accès à partir du point de terminaison AD FS.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| response_type | Obligatoire | Doit inclure id_token pour la connexion à OpenID Connect. Il peut également inclure l’élément response_type token. L’utilisation de token ici permet à votre application de recevoir immédiatement un jeton d’accès à partir du point de terminaison d’autorisation, sans avoir à effectuer de deuxième requête auprès du point de terminaison de jeton. |
| redirect_uri | obligatoire | redirect_uri de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Doit correspondre exactement à l’un des redirect_uris que vous avez configurés dans AD FS. |
| nonce | obligatoire | Valeur incluse dans la requête, générée par l’application, qui doit être incluse dans le id_token résultant en tant que 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. Obligatoire uniquement quand un id_token est demandé. |
| scope | facultatif | Une liste d’étendues séparées par des espaces. Pour OpenID Connect, elle doit inclure l’étendue openid. |
| resource | facultatif | URL de votre API web.Remarque : Si vous utilisez la bibliothèque de client MSAL, le paramètre de ressource n’est pas envoyé. À la place, l’URL de la ressource est envoyée dans le cadre du paramètre d’étendue : scope = [resource url]//[scope values e.g., openid]Si la ressource n’est pas passée ici ou dans l’étendue, AD FS utilise une ressource par défaut urn:microsoft:userinfo. Les stratégies de ressources userinfo telles que MFA, Émission ou stratégie d’autorisation ne peuvent pas être personnalisées. |
| response_mode | facultatif | Spécifie la méthode à utiliser pour renvoyer le jeton résultant à votre application. La valeur par défaut est fragment. |
| state | facultatif | Valeur incluse dans la requête, qui doit également être retournée dans la réponse du 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 d’état est également utilisée pour coder les informations sur l’état de l’utilisateur dans l’application avant la requête d’authentification, comme la page ou l’écran sur lequel ou laquelle il était positionné. |
| prompt | facultatif | Indique le type d’interaction utilisateur requis. Les seules valeurs valides pour le moment sont login et none.- prompt=login force l’utilisateur à entrer ses informations d’identification pour cette requête, ce qui entraîne l’annulation de l’authentification unique. - prompt=none représente l’inverse. Cela permet de garantir que l’utilisateur ne se voit pas proposer d’invite interactive. Si la requête ne peut pas être effectuée en mode silencieux via l’authentification unique, AD FS retourne une erreur interaction_required. |
| login_hint | facultatif | Peut être utilisé pour remplir au préalable le champ réservé au nom d’utilisateur/à l’adresse électronique de la page de connexion de l’utilisateur si vous connaissez déjà son nom d’utilisateur. Les applications utilisent souvent ce paramètre durant la réauthentification, car elles ont déjà extrait le nom d’utilisateur au cours d’une connexion précédente à l’aide de la revendication upn de id_token. |
| domain_hint | facultatif | Si ce paramètre est inclus, le processus de découverte basé sur le domaine appliqué à l’utilisateur dans la page de connexion est ignoré, ce qui se traduit par une expérience utilisateur légèrement plus fluide. |
À ce stade, l’utilisateur est invité à saisir ses informations d’identification et à exécuter l’authentification. Une fois l’utilisateur authentifié, le point de terminaison d’autorisation AD FS retourne une réponse à votre application au redirect_uri indiqué, à l’aide de la méthode spécifiée dans le paramètre response_mode.
Réponse correcte
Une réponse positive utilisant response_mode=fragment and response_type=id_token+token se présente comme ceci :
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| Paramètre | Description |
|---|---|
| access_token | Inclus si response_type inclut token. |
| token_type | Inclus si response_type inclut token. a toujours la valeur « Bearer ». |
| expires_in | Inclus si response_type inclut token. Indique le nombre de secondes pendant lesquelles le jeton est valide, à des fins de mise en cache. |
| scope | Indique la ou les étendues pour lesquelles access_token est valide. |
| id_token | Inclus si response_type inclut id_token. Un jeton Web JSON signé (JWT). 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é. |
| state | Si un paramètre d’état 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. |
Jetons d’actualisation
L’octroi implicite ne fournit pas de jetons d’actualisation. id_tokens et access_tokens expirent après un bref laps de temps ; votre application doit donc être prête à actualiser ces jetons régulièrement. Pour actualiser l’un ou l’autre des types de jeton, vous pouvez effectuer la même requête iframe masquée que celle de la section précédente à l’aide du paramètre prompt=none afin de contrôler le comportement de la plateforme d’identités. Si vous souhaitez recevoir un new id_token, veillez à utiliser response_type=id_token.
Flux d’octroi de code d’autorisation
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux d'octroi de code d'autorisation dans Microsoft Entra ID, consultez Flux d'octroi de code d'autorisation dans la plateforme d'identités Microsoft.
Vous pouvez utiliser l’octroi du code d’autorisation OAuth 2.0 dans les applications web pour accéder à des ressources protégées, telles que des API web. Le flux de code d’autorisation OAuth 2.0 est décrit dans la section 4.1 des spécifications OAuth 2.0. Il permet d’effectuer l’authentification et l’autorisation dans la plupart des types d’application, notamment les applications web et les applications installées de manière native. Le flux permet aux applications d’acquérir de manière sécurisée des access_tokens qui peuvent être utilisés pour accéder à des ressources qui approuvent AD FS.
Diagramme de protocole
À un niveau élevé, le flux d’authentification pour une application native ressemble un peu à ce qui suit :
Demander un code d’autorisation
Le flux de code d’autorisation commence par le client qui dirige l’utilisateur vers le point de terminaison /authorize. Dans cette requête, le client indique les autorisations qu’il doit obtenir de la part de l’utilisateur :
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| response_type | obligatoire | Doit inclure du code pour le flux de code d’autorisation. |
| redirect_uri | obligatoire | redirect_uri de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Doit correspondre exactement à l’un des redirect_uris que vous avez inscrits dans AD FS pour le client. |
| resource | facultatif | URL de votre API web.Remarque : Si vous utilisez la bibliothèque de client MSAL, le paramètre de ressource n’est pas envoyé. À la place, l’URL de la ressource est envoyée dans le cadre du paramètre d’étendue : scope = [resource url]//[scope values e.g., openid]Si la ressource n’est pas passée ici ou dans l’étendue, AD FS utilise une ressource par défaut urn:microsoft:userinfo. Les stratégies de ressources userinfo telles que MFA, Émission ou stratégie d’autorisation ne peuvent pas être personnalisées. |
| scope | facultatif | Liste d’étendues séparées par des espaces. |
| response_mode | facultatif | Spécifie la méthode à utiliser pour renvoyer le jeton résultant à votre application. Il peut s’agir de l’une des méthodes suivantes : - query - fragment - form_postquery fournit le code en tant que paramètre de chaîne de requête sur votre URI de redirection. Si vous demandez le code, vous pouvez utiliser query, fragment ou form_post. form_post exécute une requête POST contenant le code pour votre URI de redirection. |
| state | facultatif | Valeur incluse dans la requête, qui doit également être retournée dans la réponse du 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, comme la page ou la vue sur laquelle il se trouvait. |
| prompt | facultatif | Indique le type d’interaction utilisateur requis. Les seules valeurs valides pour le moment sont login et none.- prompt=login force l’utilisateur à entrer ses informations d’identification pour cette requête, ce qui entraîne l’annulation de l’authentification unique. - prompt=none représente l’inverse. Cela permet de garantir que l’utilisateur ne se voit pas proposer d’invite interactive. Si la requête ne peut pas être effectuée en mode silencieux via l’authentification unique, AD FS retourne une erreur interaction_required. |
| login_hint | facultatif | Peut être utilisé pour remplir au préalable le champ réservé au nom d’utilisateur/à l’adresse électronique de la page de connexion de l’utilisateur si vous connaissez déjà son nom d’utilisateur. Les applications utilisent souvent ce paramètre durant la réauthentification, car elles ont déjà extrait le nom d’utilisateur au cours d’une connexion précédente à l’aide de la revendication upn de id_token. |
| domain_hint | facultatif | Si ce paramètre est inclus, le processus de découverte basé sur le domaine appliqué à l’utilisateur dans la page de connexion est ignoré, ce qui se traduit par une expérience utilisateur légèrement plus fluide. |
| code_challenge_method | facultatif | Méthode utilisée pour encoder le code_verifier pour le paramètre code_challenge. Il peut s’agir de l’une des valeurs suivantes : - plain - S256 Si exclu, code_challenge est supposé être en texte clair si code_challenge est inclus. AD FS prend en charge les méthodes plain et S256. Pour plus d'informations, consultez le RFC PKCE. |
| code_challenge | facultatif | Utilisé pour sécuriser l’octroi du code d’autorisation via la clé de preuve pour le Code Exchange (PKCE) à partir d’un client natif. Obligatoire si code_challenge_method est inclus. Pour plus d'informations, consultez le RFC PKCE |
À ce stade, l’utilisateur est invité à saisir ses informations d’identification et à exécuter l’authentification. Une fois l’utilisateur authentifié, AD FS retourne une réponse à votre application au redirect_uri indiqué, à l’aide de la méthode spécifiée dans le paramètre response_mode.
Réponse correcte
Une réponse positive avec response_mode=query ressemble à ceci :
GET https://adfs.contoso.com/common/oauth2/nativeclient?
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 authorization_codes ont une courte durée de vie ; ils expirent en général après une dizaine de 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 state de la requête et de la réponse sont identiques. |
Demander un jeton d’accès
Maintenant que vous avez acquis un authorization_code et que l’utilisateur vous a octroyé une autorisation, vous pouvez échanger le code contre un access_token à la ressource souhaitée. Utilisez le code en envoyant une requête POST au point de terminaison /token :
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Paramètre | Obligatoire ou facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| grant_type | Obligatoire | Doit être authorization_code pour le flux de code d'autorisation. |
| 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. |
| client_secret | obligatoire pour les applications web | Il s’agit du secret d’application que vous avez créé lors de l’inscription de l’application dans AD FS. Vous ne devez pas utiliser le secret d’application dans une application native, car les client_secrets ne peuvent pas être stockés de manière fiable sur des appareils. Il est requis pour les applications web et les API web, qui présentent la capacité de stocker de manière sûre les clés secrètes client sur le côté serveur. La clé secrète client doit être encodée sous forme d’URL avant d’être envoyée. Ces applications peuvent également utiliser l’authentification basée sur des clés en signant un jeton JWT et en l’ajoutant en tant que paramètre client_assertion. |
| code_verifier | facultatif | 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. Cette option s’applique à AD FS 2019 et aux versions ultérieures |
Réponse correcte
Un jeton de réponse de réussite se présente ainsi :
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Paramètre | Description |
|---|---|
| access_token | Jeton d’accès demandé. L’application peut utiliser ce jeton pour s’authentifier auprès de la ressource sécurisée (API web). |
| token_type | Indique la valeur du type de jeton. Le seul type pris en charge par AD FS est Bearer. |
| expires_in | Durée de validité du jeton d’accès (en secondes). |
| 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 refresh_tokens ont une longue durée de vie, et peuvent être utilisés pour maintenir l’accès aux ressources pendant des périodes prolongées. |
| refresh_token_expires_in | Durée de validité du jeton d’actualisation (en secondes). |
| id_token | Jeton web JSON (JWT). 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é. |
Utiliser le jeton d’accès
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Flux d’octroi des jetons d’actualisation
Les access_tokens ont une courte durée de vie, et vous devez les actualiser une fois qu’ils ont expiré pour continuer à accéder aux ressources. Pour ce faire, vous devez envoyer une autre requête POST au point de terminaison /token, cette fois-ci en fournissant le refresh_token plutôt que le code. Les jetons d’actualisation sont valides pour toutes les autorisations pour lesquelles votre client a déjà reçu un jeton d’accès.
Les jetons d’actualisation n’ont pas de durée de vie spécifiques. 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 souhaitée. Votre application doit envisager et gérer correctement les erreurs retournées par le point de terminaison d’émission de jeton.
Bien que les jetons d’actualisation ne soient pas révoqués quand ils sont utilisés pour acquérir de nouveaux jetons d’accès, vous êtes censé supprimer l’ancien jeton d’actualisation. Conformément à la spécification OAuth 2.0 : « Le serveur d’autorisation PEUT émettre un nouveau jeton d’actualisation, auquel cas le client DOIT supprimer 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 avoir émis un nouveau jeton d’actualisation au client. » AD FS émet un jeton d’actualisation lorsque la durée de vie du nouveau jeton d’actualisation est plus longue que la durée de vie du jeton d’actualisation précédent. Pour plus d’informations sur les durées de vie des jetons d’actualisation AD FS, consultez Paramètres d’authentification unique AD FS.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| grant_type | Obligatoire | Doit inclure refresh_token pour ce tronçon du flux de code d'autorisation. |
| resource | facultatif | URL de votre API web.Remarque : Si vous utilisez la bibliothèque de client MSAL, le paramètre de ressource n’est pas envoyé. À la place, l’URL de la ressource est envoyée dans le cadre du paramètre d’étendue : scope = [resource url]//[scope values e.g., openid]Si la ressource n’est pas passée ici ou dans l’étendue, AD FS utilise une ressource par défaut urn:microsoft:userinfo. Les stratégies de ressources userinfo telles que MFA, Émission ou stratégie d’autorisation ne peuvent pas être personnalisées. |
| scope | facultatif | Liste d’étendues séparées par des espaces. |
| refresh_token | obligatoire | refresh_token que vous avez acquis lors de la deuxième phase du flux. |
| client_secret | obligatoire 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 les client_secrets ne peuvent pas être stockées de manière sûre sur les appareils. Il est obligatoire pour les applications web et les API web, qui ont la capacité à stocker le client_secret de façon sécurisée côté serveur. Ces applications peuvent également utiliser l’authentification basée sur des clés en signant un jeton JWT et en l’ajoutant en tant que paramètre client_assertion. |
Réponse positive
Un jeton de réponse de réussite se présente ainsi :
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"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 AD FS est Bearer. |
| expires_in | Durée de validité du jeton d’accès (en secondes). |
| scope | Étendues pour lesquelles l’access_token est valide. |
| 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 refresh_tokens ont une longue durée de vie, et peuvent être utilisés pour maintenir l’accès aux ressources pendant des périodes prolongées. |
| refresh_token_expires_in | Durée de validité du jeton d’actualisation (en secondes). |
| id_token | Jeton web JSON (JWT). 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é. |
Flux On-Behalf-Of
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux On-Behalf-Of dans Microsoft Entra ID, consultez Flux On-Behalf-Of dans la plateforme d'identités Microsoft.
Le flux OBO (On-Behalf-Of) OAuth 2.0 est utilisé dans le cas d’usage où une application appelle un service ou une API web, qui à son tour doit appeler un autre service/API web. L’idée est de propager l’identité de l’utilisateur déléguée et les autorisations dans la chaîne de requête. Pour que le service de niveau intermédiaire puisse effectuer des requêtes authentifiées auprès du service en aval, il doit sécuriser un jeton d’accès AD FS pour le compte de l’utilisateur.
Diagramme de protocole
Supposons que l’utilisateur ait été authentifié dans une application à l’aide du flux d’octroi de code d’autorisation OAuth 2.0 décrit dans la section précédente. À ce stade, l’application dispose d’un jeton d’accès pour l’API A (jeton A) avec les revendications et le consentement de l’utilisateur pour accéder à l’API web de niveau intermédiaire (API A). Assurez-vous que le client demande l’étendue user_impersonation dans le jeton. Désormais, l’API A doit effectuer une requête authentifiée auprès de l’API web en aval (API B).
Les étapes qui suivent constituent le flux OBO et sont expliquées avec l’aide du diagramme suivant.
- L’application cliente envoie une requête à l’API A avec le jeton A. Remarque : Durant la configuration du flux OBO (On-Behalf-Of) dans AD FS, vérifiez que l’étendue
user_impersonationest sélectionnée, et que le client demande bien l’étendueuser_impersonationdans la requête. - L’API A s’authentifie auprès du point de terminaison d’émission de jetons AD FS, et demande un jeton pour accéder à l’API B. Remarque : Durant la configuration de ce flux dans AD FS, vérifiez que l’API A est également inscrite en tant qu’application serveur avec clientID ayant la même valeur que l’ID de ressource dans l’API A.
- Le point de terminaison d’émission de jetons AD FS valide les informations d’identification de l’API A avec le jeton A, et émet le jeton d’accès pour l’API B (jeton B).
- Le jeton B est défini dans l’en-tête d’autorisation de la requête à l’API B.
- Les données de la ressource sécurisée sont retournées par l’API B.
Requête de jeton d’accès de service à service
Pour demander un jeton d’accès, exécutez une requête POST HTTP sur le point de terminaison de jeton AD FS avec les paramètres suivants.
Premier cas : requête de jeton d’accès avec un secret partagé
Pour un secret partagé, une demande de jeton d’accès de service à service contient les paramètres suivants :
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| grant_type | obligatoire | Type de requête de jeton. Pour une requête utilisant un jeton JWT, la valeur doit être urn:ietf:params:oauth:grant-type:jwt-bearer. |
| client_id | obligatoire | ID client que vous configurez lors de l’inscription de votre première API web en tant qu’application serveur (application de niveau intermédiaire). Il doit être identique à l’ID de ressource utilisé dans la première partie, c’est-à-dire l’URL de la première API web. |
| client_secret | obligatoire | Secret d’application que vous avez créé lors de l’inscription de l’application serveur dans AD FS. |
| assertion | obligatoire | Valeur du jeton utilisé dans la requête. |
| requested_token_use | obligatoire | Spécifie comment la requête doit être traitée. Dans le flux OBO, ce paramètre doit avoir la valeur on_behalf_of. |
| resource | obligatoire | ID de ressource fourni lors de l’inscription de la première API web en tant qu’application serveur (application de niveau intermédiaire). L’ID de ressource doit correspondre à l’URL de la deuxième API web que l’application de niveau intermédiaire appelle au nom du client. |
| scope | facultatif | Liste d’étendues séparées par des espaces pour la requête de jeton. |
Exemple
La requête HTTP POST suivante demande un jeton d’accès et un jeton d’actualisation.
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
Deuxième cas : requête de jeton d’accès avec un certificat
Une demande de jeton d’accès de service à service avec un certificat contient les paramètres suivants :
| Paramètre | Obligatoire ou facultatif | Description |
|---|---|---|
| grant_type | obligatoire | Type de requête de jeton. Pour une requête utilisant un jeton JWT, la valeur doit être urn:ietf:params:oauth:grant-type:jwt-bearer. |
| client_id | obligatoire | ID client que vous configurez lors de l’inscription de votre première API web en tant qu’application serveur (application de niveau intermédiaire). Il doit être identique à l’ID de ressource utilisé dans la première partie, c’est-à-dire l’URL de la première API web. |
| client_assertion_type | obligatoire | La valeur doit être urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| client_assertion | obligatoire | Assertion (jeton web JSON) que vous devez créer et signer avec le certificat que vous avez inscrit en tant qu’informations d’identification pour votre application. |
| assertion | obligatoire | Valeur du jeton utilisé dans la requête. |
| requested_token_use | obligatoire | Spécifie comment la requête doit être traitée. Dans le flux OBO, ce paramètre doit avoir la valeur on_behalf_of. |
| resource | obligatoire | ID de ressource fourni lors de l’inscription de la première API web en tant qu’application serveur (application de niveau intermédiaire). L’ID de ressource doit correspondre à l’URL de la deuxième API web que l’application de niveau intermédiaire appelle au nom du client. |
| scope | facultatif | Liste d’étendues séparées par des espaces pour la requête de jeton. |
Notez que les paramètres sont presque les mêmes. Cet exemple est similaire à celui de la demande par secret partagé, à ceci près que le paramètre client_secret est remplacé par deux paramètres : client_assertion_type et client_assertion.
Exemple
La requête POST HTTP suivante demande un jeton d’accès pour l’API web avec un certificat.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
Réponse de jeton d’accès de service à service
Une réponse correspondant à une réussite est une réponse JSON OAuth 2.0 avec les paramètres suivants.
| Paramètre | Description |
|---|---|
| token_type | Indique la valeur du type de jeton. Le seul type pris en charge par AD FS est Bearer. |
| scope | Étendue de l’accès accordé dans le jeton. |
| expires_in | Durée, en secondes, pendant laquelle le jeton d’accès est valide. |
| access_token | Le jeton d’accès demandé. Le service web appelant peut utiliser ce jeton pour s’authentifier auprès du service destinataire. |
| id_token | Jeton web JSON (JWT). 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é. |
| refresh_token | Jeton d’actualisation pour le jeton d’accès demandé. Le service appelant peut utiliser ce jeton pour demander un autre jeton d’accès après l’expiration du jeton d’accès actif. |
| refresh_token_expires_in | Durée, en secondes, pendant laquelle le jeton d’actualisation est valide. |
Exemple de réponse positive
L’exemple suivant montre une réponse positive à une requête de jeton d’accès pour l’API web.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
Utilisez le jeton d’accès pour accéder à la ressource sécurisée. Le service de niveau intermédiaire peut utiliser le jeton acquis dans l’exemple de réponse précédent pour envoyer des requêtes authentifiées à l’API web en aval, en définissant le jeton dans l’en-tête d’autorisation.
Exemple
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
Flux d’octroi des informations d’identification du client
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux d'octroi des informations d'identification client dans Microsoft Entra ID, consultez Flux d'octroi des informations d'identification client dans la plateforme d'identités Microsoft.
Vous pouvez utiliser l’octroi d’informations d’identification du client OAuth 2.0 spécifié dans le document RFC 6749 pour accéder à des ressources hébergées sur le web à l’aide de l’identité d’une application. Ce type d’octroi est couramment utilisé pour les interactions de serveur à serveur qui doivent s’exécuter en arrière-plan sans l’interaction immédiate d’un utilisateur. Ces types d’application sont souvent appelés démons (daemons) ou comptes de service.
Le flux d’octroi des informations d’identification du client OAuth 2.0 permet à un service web (client confidentiel) d’utiliser ses propres informations d’identification pour s’authentifier lorsqu’il appelle un autre service web, au lieu d’emprunter l’identité d’un utilisateur. Dans ce scénario, le client est généralement un service web de niveau intermédiaire, un service démon ou un site web. Pour un niveau d’assurance plus élevé, AD FS autorise également le service appelant à utiliser un certificat (plutôt qu’un secret partagé) comme informations d’identification.
Diagramme de protocole
Le diagramme suivant illustre le flux d’octroi des informations d’identification du client.
Demander un jeton
Pour obtenir un jeton à l’aide de l’octroi des informations d’identification du client, envoyez une requête POST au point de terminaison AD FS /token :
Premier cas : requête de jeton d’accès avec un secret partagé
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| scope | facultatif | Liste des étendues, séparées par des espaces, auxquelles l’utilisateur doit donner son consentement. |
| client_secret | obligatoire | Clé secrète client que vous avez générée pour votre application dans le portail d’inscription des applications. La clé secrète client doit être encodée sous forme d’URL avant d’être envoyée. |
| grant_type | obligatoire | Cette propriété doit être définie sur client_credentials. |
Deuxième cas : Requête de jeton d’accès avec un certificat
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_assertion_type | obligatoire | La valeur doit être urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| client_assertion | obligatoire | Assertion (jeton web JSON) que vous devez créer et signer avec le certificat que vous avez inscrit en tant qu’informations d’identification pour votre application. |
| grant_type | obligatoire | Cette propriété doit être définie sur client_credentials. |
| client_id | facultatif | ID d’application (client) qu’AD FS a affecté à votre application. Il fait partie de client_assertion. Il n’est donc pas nécessaire de le passer ici. |
| scope | facultatif | Liste des étendues, séparées par des espaces, auxquelles l’utilisateur doit donner son consentement. |
Utilisation d’un jeton
Maintenant que vous avez acquis un jeton, utilisez-le pour exécuter des requêtes sur la ressource. Quand le jeton expire, répétez la requête sur le point de terminaison /token pour obtenir un nouveau jeton d’accès.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Flux d’octroi des informations d’identification du mot de passe du propriétaire de la ressource (non recommandé)
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux d'octroi des informations d'identification de mot de passe de propriétaire de ressource dans Microsoft Entra ID, consultez Flux d'octroi des informations d'identification de mot de passe de propriétaire de ressource dans la plateforme d'identités Microsoft.
L’octroi des informations d’identification du mot de passe du propriétaire de la ressource (ROPC) permet à une application de connecter l’utilisateur en gérant directement son mot de passe. Le flux ROPC nécessite un degré élevé de confiance et d’exposition de l’utilisateur. Vous ne devez utiliser ce flux que quand d’autres flux, plus sécurisés, ne peuvent pas être utilisés.
Diagramme de protocole
Le diagramme qui suit montre le flux ROPC.
Requête d’autorisation
Le flux ROPC est constitué d’une requête unique : il envoie l’identification du client et les informations d’identification de l’utilisateur au fournisseur d’identité, puis reçoit les jetons en retour. Le client doit demander l’adresse e-mail de l’utilisateur (UPN) et le mot de passe avant de procéder. Immédiatement après une demande réussie, le client doit supprimer de la mémoire les informations d’identification de l’utilisateur de façon sécurisée. Il ne doit jamais les enregistrer.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| Paramètre | Obligatoires/facultatif | Description |
|---|---|---|
| client_id | obligatoire | ID de client |
| grant_type | obligatoire | Doit être défini sur password. |
| username | obligatoire | Adresse de messagerie de l’utilisateur. |
| password | obligatoire | Mot de passe de l’utilisateur. |
| scope | facultatif | Une liste d’étendues séparées par des espaces. |
Réponse d’authentification réussie
L’exemple suivant montre une réponse de jeton réussie :
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| Paramètre | Description |
|---|---|
| token_type | Toujours défini sur Bearer. |
| scope | Si un jeton d’accès a été retourné, ce paramètre liste les étendues pour lesquelles le jeton d’accès est valide. |
| expires_in | Nombre de secondes pendant lesquelles le jeton d’accès inclus est valide. |
| access_token | Émis pour les étendues qui ont été demandées. |
| id_token | Jeton web JSON (JWT). 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é. |
| refresh_token_expires_in | Nombre de secondes pendant lesquelles le jeton d’actualisation inclus est valide. |
| refresh_token | Émis si le paramètre d’étendue d’origine incluait offline_access. |
Vous pouvez utiliser le jeton d’actualisation pour acquérir de nouveaux jetons d’accès et jetons d’actualisation à l’aide du même flux que celui décrit dans la section relative au flux d’octroi de code d’authentification de cet article.
Flux de code d’appareil
Remarque
Microsoft recommande vivement de migrer vers Microsoft Entra ID au lieu d'effectuer une mise à niveau vers une version plus récente d'AD FS. Pour plus d'informations sur le flux de code d'appareil dans Microsoft Entra ID, consultez Flux de code d'appareil dans la plateforme d'identités Microsoft.
L’octroi de code d’appareil permet aux utilisateurs de se connecter à des appareils avec restriction d’entrée, tels qu’une imprimante, un appareil IoT ou un téléviseur intelligent. Pour activer ce flux, l’appareil fait en sorte que l’utilisateur accède à une page web dans son navigateur sur un autre appareil pour se connecter. Une fois que l’utilisateur s’est connecté, l’appareil peut recevoir des jetons d’accès et des jetons d’actualisation en fonction des besoins.
Diagramme de protocole
Le diagramme suivant illustre l’intégralité du flux de code d’appareil. Nous décrirons en détail chacune des étapes plus loin dans cet article.
Requête d’autorisation de l’appareil
Le client doit d’abord rechercher sur le serveur d’authentification un appareil et un code utilisateur, utilisés pour lancer l’authentification. Le client collecte cette requête à partir du point de terminaison /devicecode. Dans cette requête, le client doit également inclure les autorisations dont il a besoin d’obtenir auprès de l’utilisateur. À partir du moment où cette requête est envoyée, l’utilisateur ne dispose que de 15 minutes pour se connecter (la valeur habituelle du paramètre expires_in). Vous ne devez donc effectuer cette requête que quand l’utilisateur a indiqué qu’il est prêt à se connecter.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
scope=openid
| Paramètre | Condition | Description |
|---|---|---|
| client_id | obligatoire | ID d’application (client) qu’AD FS a affecté à votre application. |
| scope | facultatif | Une liste d’étendues séparées par des espaces. |
Réponse d’autorisation d’appareil
Une réponse positive est un objet JSON contenant les informations nécessaires pour permettre à l’utilisateur de se connecter.
| Paramètre | Description |
|---|---|
| device_code | Chaîne longue servant à vérifier la session entre le client et le serveur d’autorisation. Le client utilise ce paramètre pour demander le jeton d’accès au serveur d’autorisation. |
| user_code | Courte chaîne présentée à l’utilisateur, servant à identifier la session sur un appareil secondaire. |
| verification_uri | URI auquel l’utilisateur doit accéder avec le user_code afin de se connecter. |
| verification_uri_complete | URI auquel l’utilisateur doit accéder avec le user_code afin de se connecter. Il est prérempli avec user_code pour éviter à l’utilisateur d’avoir à entrer user_code |
| expires_in | Nombre de secondes avant l’expiration du device_code et du user_code. |
| interval | Nombre de secondes pendant lesquelles le client doit attendre entre les requêtes d’interrogation. |
| message | Chaîne explicite avec des instructions destinées à l’utilisateur. Vous pouvez la localiser en incluant un paramètre de requête dans la requête au format ?mkt=xx-XX, et en indiquant le code de culture de langue approprié. |
Authentification de l’utilisateur
Une fois que le client a reçu le user_code et le verification_uri, il présente ces détails à l’utilisateur, en lui demandant de se connecter à l’aide du navigateur de son téléphone mobile ou de son PC. De plus, le client peut utiliser un code QR ou tout autre mécanisme similaire afin d’afficher le verfication_uri_complete, ce qui permet l’entrée du user_code pour l’utilisateur. Pendant que l’utilisateur s’authentifie à verification_uri, le client doit interroger le point de terminaison /token pour obtenir le jeton demandé à l’aide du device_code.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 6731de76-14a6-49ae-97bc-6eba6914391e
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| Paramètre | obligatoire | Description |
|---|---|---|
| grant_type | obligatoire | Doit être urn:ietf:params:oauth:grant-type:device_code. |
| client_id | obligatoire | Doit correspondre au client_id utilisé dans la requête initiale. |
| code | obligatoire | device_code retourné dans la requête d’autorisation de l’appareil. |
Réponse d’authentification réussie
Un jeton de réponse de réussite se présente ainsi :
| Paramètre | Description |
|---|---|
| token_type | Toujours « Bearer ». |
| scope | Si un jeton d’accès a été retourné, il liste les étendues pour lesquelles il est valide. |
| expires_in | Nombre de secondes pendant lesquelles le jeton d’accès inclus est valide. |
| access_token | Émis pour les étendues qui ont été demandées. |
| id_token | Émis si le paramètre d’étendue d’origine incluait l’étendue openid. |
| refresh_token | Émis si le paramètre d’étendue d’origine incluait offline_access. |
| refresh_token_expires_in | Nombre de secondes pendant lesquelles le jeton d’actualisation inclus est valide. |
Contenu associé
Pour obtenir la liste complète des articles de procédure pas à pas, consultez la page Développement AD FS, qui fournit des instructions pas à pas sur l’utilisation des flux associés.