Plateforme d’identités Microsoft et flux On-Behalf-Of OAuth 2.0

Le flux OBO (On-Behalf-Of) décrit le scénario d’une API web qui utilise une autre identité que la sienne pour appeler une autre API web. Connu sous le nom de délégation dans le cadre d’OAuth, le but est ici de transmettre l’identité et les autorisations d’un utilisateur via la chaîne de demande.

Pour que le service de niveau intermédiaire puisse faire des demandes authentifiées au service en aval, il doit sécuriser un jeton d’accès de la plateforme d’identités Microsoft. Il utilise uniquement des étendues déléguées et non des rôles d’application. Les rôles restent attachés au principal (l’utilisateur), jamais à l’application s’exécutant au nom de l’utilisateur. Cela vise à empêcher l’utilisateur d’obtenir indûment une autorisation d’accès à des ressources.

Cet article explique comment programmer directement par rapport au protocole dans votre application. Dans la mesure du possible, nous vous recommandons d’utiliser les bibliothèques d’authentification Microsoft (MSAL) prises en charge au lieu d’acquérir des jetons et d’appeler des API web sécurisées. Nous vous invitons également à consulter des exemples d’applications utilisant MSAL.

Limitations du client

Si un principal de service demande un jeton d’application uniquement et l’envoie à une API, cette API échangera un jeton qui ne représente pas le principal de service d’origine. En fait, le flux OBO vaut uniquement pour les principaux d’utilisateurs. Pour obtenir un jeton d’application uniquement, il doit utiliser le flux d’informations d’identification client. Dans le cas des applications monopages (SPA), un jeton d’accès doit être transmis à un client confidentiel de niveau intermédiaire pour exécuter des flux OBO.

Si un client utilise le flux implicite pour obtenir un id_token et qu’une URL de réponse contient aussi des caractères génériques, l’id_token ne peut pas être utilisé pour un flux OBO. Un caractère générique est une URL qui se termine par un caractère *. Par exemple, si https://myapp.com/* est l’URL de réponse, l’id_token ne peut pas être utilisé, car elle n’identifie pas le client de façon assez précise. Cela empêche l’émission du jeton. Toutefois, les jetons d'accès acquis par le biais du flux d'octroi implicite sont échangés par un client confidentiel, même si le client à l'origine de la demande a enregistré une URL de réponse générique. Cela s’explique par le fait que le client confidentiel peut identifier le client qui a acquis le jeton d’accès. Le client confidentiel peut alors utiliser le jeton d’accès pour obtenir un nouveau jeton d’accès pour l’API en aval.

Par ailleurs, les applications dotées de clés de signature personnalisées ne peuvent pas être utilisées comme API de niveau intermédiaire dans le flux OBO. Cela est notamment le cas des applications d’entreprise configurées pour l’authentification unique. Si l'API de niveau intermédiaire utilise une clé de signature personnalisée, l'API en aval ne validera pas la signature du jeton d'accès qui lui est transmis. Il en résulte une erreur car les jetons signés avec une clé contrôlée par le client ne peuvent pas être acceptés en toute sécurité.

Diagramme de protocole

Supposons que l'utilisateur s'est authentifié auprès d'une application à l'aide du flux d'octroi de code d'autorisation OAuth 2.0 ou d'un autre flux d'ouverture de session. À 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). L’API A doit maintenant faire une demande authentifiée à 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.

1. L’application cliente adresse une demande à l’API A avec le jeton A (avec une revendication d’API A aud).
2. L’API A s’authentifie auprès du point de terminaison d’émission de jeton de la plateforme d’identités Microsoft et demande un jeton pour accéder à l’API B.
3. Le point de terminaison d’émission de jeton de la plateforme d’identités Microsoft valide les informations d’identification de l’API A avec le jeton A et envoie le jeton d’accès pour l’API B (jeton B) à l’API A.
4. Le jeton B est défini par l’API A dans l’en-tête d’autorisation de la requête adressée à l’API B.
5. Les données de la ressource sécurisée sont retournées par l’API B à l’API A, puis au client.

Dans ce scénario, le service de niveau intermédiaire n’a aucune interaction avec l’utilisateur afin d’obtenir son consentement pour accéder à l’API en aval. Par conséquent, l’option d’accorder l’accès à l’API en aval est présentée en amont à l’étape de consentement durant l’authentification. Pour savoir comment implémenter cela dans votre application, consultez Obtention du consentement pour l’application de niveau intermédiaire.

Demande de jeton d’accès de niveau intermédiaire

Pour demander un jeton d’accès, adressez une requête HTTP POST au point de terminaison du jeton de la plateforme d’identités Microsoft spécifique au locataire, avec les paramètres suivants.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Deux cas de figure se présentent, selon que l’application cliente choisit d’être sécurisée par un secret partagé ou un certificat.

Premier cas : Requête de jeton d’accès avec un secret partagé

Lorsque l’application utilise un secret partagé, la demande de jeton d’accès de service à service contient les paramètres suivants :

Exemple

La requête HTTP POST suivante demande un jeton d’accès et un jeton d’actualisation avec l’étendue user.read pour l’API web https://graph.microsoft.com. La demande est signée avec la clé secrète client et est formulée par un client confidentiel.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

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, en plus des paramètres de l’exemple précédent :

Notez que les paramètres sont presque les mêmes que dans le cas de la demande par secret partagé, sauf que le paramètre client_secret est remplacé par deux paramètres : client_assertion_type et client_assertion. Le paramètre client_assertion_type est défini sur urn:ietf:params:oauth:client-assertion-type:jwt-bearer et le paramètre client_assertion est défini sur le jeton JWT signé avec la clé privée du certificat.

Exemple

La requête HTTP POST suivante demande un jeton d’accès avec l’étendue user.read pour l’API web https://graph.microsoft.com avec un certificat. La demande est signée avec la clé secrète client et est formulée par un client confidentiel.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Réponse à une demande de jeton d’accès de niveau intermédiaire

Une réponse correspondant à une réussite est une réponse JSON OAuth 2.0 avec les paramètres suivants.

Exemple de réponse correspondant à une réussite

L’exemple suivant illustre une réponse affirmative à une demande de jeton d’accès pour l’API web https://graph.microsoft.com. La réponse contient un jeton d’accès et un jeton d’actualisation et est signée avec la clé privée du certificat.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Ce jeton d’accès est un jeton au format v1.0 pour Microsoft Graph. En effet, le format dépend de la ressource consultée et n’est pas lié aux points de terminaison utilisés pour le demander. Comme Microsoft Graph est configuré pour accepter des jetons v1.0, la plateforme d’identités Microsoft produit des jetons d’accès v1.0 quand un client demande des jetons pour Microsoft Graph. D'autres applications peuvent indiquer qu'elles veulent des jetons au format v2.0, des jetons au format v1.0, voire des formats de jetons protégés ou cryptés. Les points de terminaison v1.0 et v2.0 peuvent tous deux émettre chaque format de jeton. Ainsi, la ressource peut toujours obtenir le bon format de jeton, indépendamment de la façon dont le client a demandé le jeton.

Exemple de réponse d’erreur

Une réponse d’erreur est retournée par le point de terminaison du jeton quand il tente d’acquérir un jeton d’accès pour l’API en aval, si celle-ci dispose d’une stratégie d’accès conditionnel (par exemple l’authentification multifacteur). Le service de niveau intermédiaire doit faire apparaître cette erreur à l’application cliente afin que celle-ci puisse fournir une interaction utilisateur pour satisfaire la stratégie d’accès conditionnel.

Pour renvoyer cette erreur au client, le service de niveau intermédiaire répond avec HTTP 401 Non autorisé et avec un en-tête HTTP WWW-Authenticate contenant l’erreur et la contestation de revendication. Le client doit analyser cet en-tête et acquérir un nouveau jeton auprès de l’émetteur du jeton en présentant la contestation des revendications, le cas échéant. Les clients ne doivent pas réessayer d’accéder au service de niveau intermédiaire en utilisant un jeton d’accès mis en cache.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Utiliser le jeton d’accès pour accéder à la ressource sécurisée

Le service de niveau intermédiaire peut maintenant utiliser le jeton acquis précédemment pour effectuer des requêtes authentifiées auprès de l'API web en aval, en définissant le jeton dans l'en-tête Authorization.

Exemple

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

Assertions SAML obtenues avec un flux OBO OAuth 2.0

Certains services web basés sur OAuth doivent accéder à d’autres API de service web qui acceptent les instructions d’assertion SAML dans des flux non interactifs. Microsoft Entra ID peut fournir une assertion SAML en réponse à un flux On-Behalf-Of qui utilise un service web basé sur SAML comme ressource cible.

Il s'agit d'une extension non standard du flux On-Behalf-Of OAuth 2.0 qui permet à une application basée sur OAuth2 d'accéder à des points d'extrémité d'API de services web qui consomment des jetons SAML.

Obtenir un jeton SAML en utilisant une demande OBO avec un secret partagé

Une demande de service à service pour obtenir une assertion SAML contient les paramètres suivants :

La réponse contient un jeton SAML encodé en UTF8 et Base 64url.

• SubjectConfirmationData pour une assertion SAML en provenance d’un appel OBO : si l’application cible nécessite une valeur Recipient dans SubjectConfirmationData, la valeur doit être configurée en tant que première URL de réponse sans caractère générique dans la configuration de la ressource d'application. Comme l'URL de réponse par défaut n'est pas utilisée pour déterminer la valeur Recipient, il se peut que vous deviez réorganiser les URL de réponse dans la configuration de l'application pour vous assurer que la première URL de réponse sans caractères génériques est utilisée. Pour plus d’informations, consultez URL de réponse.
• Le nœud SubjectConfirmationData : le nœud ne peut pas contenir d’attribut InResponseTo, dans la mesure où il ne fait pas partie d’une réponse SAML. L’application qui reçoit le jeton SAML doit pouvoir accepter l’assertion SAML sans attribut InResponseTo.
• Autorisations d’API : vous devez ajouter les autorisations d’API nécessaires sur l’application de couche intermédiaire pour autoriser l’accès à l’application SAML, afin qu’elle puisse demander un jeton pour l'étendue /.default de l’application SAML.
• Consentement : un consentement doit avoir été accordé pour recevoir un jeton SAML contenant des données utilisateur sur un flux OAuth. Pour plus d’informations, consultez Obtenir le consentement pour l’application de niveau intermédiaire.

Réponse avec instruction d’assertion SAML

• token_type : Support
• expires_in : 3296
• ext_expires_in : 0
• expires_on : 1529627844
• resource : https://api.contoso.com
• access_token : <assertion SAML>
• issued_token_type : urn:ietf:params:oauth:token-type:saml2
• refresh_token : <jeton d’actualisation>

Obtention du consentement pour l’application de niveau intermédiaire

L’objectif du flux OBO est de garantir qu’un consentement en bonne et due forme a été donné pour que l’application cliente puisse appeler l’application de niveau intermédiaire et que l’application de niveau intermédiaire soit autorisée à appeler la ressource back-end. En fonction de l'architecture ou de l'utilisation de votre application, vous devez tenir compte des éléments suivants pour garantir la réussite du flux OBO :

Étendue .default et consentement combiné

L’application de niveau intermédiaire ajoute le client à la liste des applications clientes connues (knownClientApplications) dans son manifeste. Si une invite de consentement est déclenchée par le client, le flux de consentement est à la fois pour lui-même et pour l'application de niveau intermédiaire. Sur la plateforme d’identités Microsoft, l’étendue .default est utilisée. L’étendue .default est une étendue spéciale utilisée pour demander le consentement afin d’accéder à toutes les étendues pour lesquelles l’application dispose d’autorisations. Cela est utile lorsque l’application a besoin d’accéder à plusieurs ressources, mais que l’utilisateur ne doit être invité qu’une seule fois à donner son consentement.

Lors du déclenchement d'un écran de consentement à l'aide d'applications clientes connues et .default, l'écran de consentement affiche les autorisations du client pour l'API de niveau intermédiaire et demande également toutes les autorisations requises par l'API de niveau intermédiaire. L’utilisateur fournit le consentement pour les deux applications et le flux OBO fonctionne ensuite.

Le service de ressource (API) identifié dans la requête doit être l’API pour laquelle l’application cliente demande un jeton d’accès suite à la connexion de l’utilisateur. Par exemple, scope=openid https://middle-tier-api.example.com/.default (pour demander un jeton d’accès pour l’API de niveau intermédiaire) ou scope=openid offline_access .default (quand une ressource n’est pas identifiée, il s’agit par défaut de Microsoft Graph).

Quelle que soit l'API identifiée dans la demande d'autorisation, l’invite de consentement est combinée avec toutes les autorisations requises configurées pour l'application client. Toutes les autorisations requises configurées pour chaque API de niveau intermédiaire figurant dans la liste des autorisations requises du client, qui a identifié le client en tant qu'application cliente connue, sont également incluses.

Applications pré-autorisées

Une ressource peut indiquer qu’une application donnée a toujours l’autorisation de recevoir certaines étendues. Cela est utile pour améliorer la fluidité des connexions entre un client front-end et une ressource back-end. Une ressource peut déclarer plusieurs applications préautorisées (preAuthorizedApplications) dans son manifeste. Une application de ce type peut demander ces autorisations dans un flux OBO et les recevoir sans que l’utilisateur ne fournisse de consentement.

Consentement de l’administrateur

Un administrateur de locataire peut garantir que les applications ont l’autorisation d’appeler leurs API requises en fournissant le consentement de l’administrateur pour l’application de niveau intermédiaire. Pour ce faire, l’administrateur peut trouver l’application de niveau intermédiaire dans son locataire, ouvrir la page des autorisations nécessaires et choisir d’accorder l’autorisation pour l’application. Pour en savoir plus sur le consentement de l’administrateur, consultez la documentation sur le consentement et les autorisations.

Utilisation d’une application unique

Dans certains scénarios, vous pouvez avoir uniquement une seule association d’un client de niveau intermédiaire et d’un client front-end. Dans ce scénario, il peut être plus facile d'en faire une application unique, ce qui rend inutile l'utilisation d'une application de niveau intermédiaire. Pour l’authentification entre le front-end et l’API web, vous pouvez utiliser des cookies, un jeton id_token ou un jeton d’accès demandé pour l’application elle-même. Demandez ensuite le consentement dans cette application unique à la ressource back-end.

Voir aussi

Découvrez plus d’informations sur le protocole OAuth 2.0 et une autre méthode pour effectuer l’authentification de service à service à l’aide des informations d’identification du client.

• Octroi d’informations d’identification du client OAuth 2.0 sur la plateforme d’identités Microsoft
• Flux de code OAuth 2.0 sur la plateforme d’identité Microsoft
• Utilisation de l’étendue /.default