Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Le code d’autorisation OAuth 2.0 accorde des connexions à un utilisateur et obtient des jetons avec des autorisations déléguées. L’utilisateur se connecte via un navigateur, Microsoft Entra ID retourne un code d’autorisation de courte durée et le client échange le code au niveau du point de terminaison du jeton.
Une solution d’ID d’agent peut utiliser l’octroi de deux façons :
| Type de client | Rôle typique | Informations d’identification du client | PKCE |
|---|---|---|---|
| Client public | Un agent local connecte directement l’utilisateur. | No | Required |
| Client confidentiel | Un client web côté serveur se connecte à l’utilisateur avant d’appeler un agent hébergé. | Yes | Recommended |
Utilisez Microsoft Authentication Library (MSAL) ou Microsoft. Identity.Web au lieu de créer ces requêtes directement. Les demandes de cet article affichent les champs de protocole pour référence.
Warning
Microsoft recommande d’utiliser les SDK approuvés, tels que Microsoft.Identity.Web et les bibliothèques Microsoft Entra ID Auth SDK (sidecar), pour mettre en œuvre ces protocoles. L’implémentation manuelle de ces protocoles est complexe et sujette aux erreurs, et l’utilisation des kits SDK permet de garantir la sécurité et la conformité avec les meilleures pratiques.
Important
La prise en charge de l’ID de l’agent client public est en préversion. Cette version préliminaire est fournie sans contrat de niveau de service et n’est pas recommandée pour les environnements de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités limitées. Pour plus d’informations, consultez Conditions du contrat de licence universel pour les services en ligne.
Requête d’autorisation
Les deux types de clients envoient l’utilisateur au point de terminaison d’autorisation du locataire :
GET https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize?
client_id={client-id}
&response_type=code
&redirect_uri={encoded-redirect-uri}
&response_mode=query
&scope=openid%20profile%20offline_access%20api://{resource-client-id}/{scope}
&state={random-state}
&nonce={random-nonce}
&code_challenge={pkce-challenge}
&code_challenge_method=S256
-
client_ididentifie le client public ou confidentiel. Un client public CIMD utilise son URL de document de métadonnées HTTPS comme ID client. -
redirect_uridoit correspondre exactement à un URI de redirection configuré pour le client. -
scopecontient les autorisations déléguées que le client demande. Omettez l’étendue de la ressource lorsque le client doit uniquement se connecter à l’utilisateur. -
statelie la réponse à la session de lancement et permet d’empêcher la falsification de requête intersite. -
noncelie un jeton d’ID OpenID Connect à la session de lancement. -
code_challengeest dérivé d’un vérificateur PKCE haute entropie à l’aide de SHA-256.
Après la connexion et le consentement, Microsoft Entra ID redirige le navigateur vers l’URI de redirection inscrit :
GET {redirect-uri}?code={authorization-code}&state={state}
Avant d’utiliser le code, validez state et gérez toute erreur OAuth retournée à l’URI de redirection.
Demande de jeton client public
Un client public ne peut pas protéger les informations d’identification d’un client. Il échange le code à l’aide du vérificateur PKCE :
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={agent-id-client-id-or-cimd-url}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{resource-client-id}/{scope}
&code_verifier={pkce-verifier}
N’envoyez pas de clé secrète client, d’assertion de certificat ou d’informations d’identification fédérées dans cette requête.
Un ID d’agent public-client inscrit doit utiliser le mode à instance unique. Un client qui utilise un document de métadonnées d’ID client peut utiliser l’URL HTTPS du document comme ID client. Pour obtenir des conseils d’implémentation, consultez Connecter des utilisateurs à partir d’un agent local.
Demande de jeton client confidentiel
Un client confidentiel s’exécute sur un serveur qui peut protéger les informations d’identification. Le serveur, et non le code du navigateur, échange le code d’autorisation. La demande inclut des informations d’identification client et le vérificateur PKCE lorsque la demande d’autorisation a utilisé PKCE :
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={confidential-client-id}
&grant_type=authorization_code
&code={authorization-code}
&redirect_uri={redirect-uri}
&scope=openid profile offline_access api://{agent-blueprint-client-id}/{scope}
&code_verifier={pkce-verifier}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={signed-client-assertion}
L’exemple utilise une assertion de client basée sur un certificat. Une clé secrète client est également prise en charge, mais utilise une fédération d’identité de certificat ou de charge de travail si possible.
Dans une solution d’ID d’agent hébergé, le client confidentiel est normalement l’application web en amont, et non l’ID d’agent enfant. Demandez un jeton d’accès dont l’audience est le blueprint de l’agent hébergé, envoyez ce jeton d’accès à l’API de l’agent et utilisez le flux on-Behalf-Of pour appeler des API en aval.
Pour une identité d’agent à instance unique (préversion), <agent-blueprint-client-id> indique l’ID client partagé par le blueprint et l’identité de l’agent. Pour une flotte, elle désigne l’ID client du blueprint, et non l’ID de l’agent enfant individuel. Pour le mode à instance unique, configurez l’octroi du client en amont via Accorder l’accès client en amont avant la connexion ; le consentement du navigateur ne prend pas en charge l’identité de l’agent en tant que ressource.
N’envoyez pas de code d’autorisation ou de jeton d’ID à l’API de l’agent hébergé. Les ID d’agent enfant dans le modèle confidentiel-client ne lancent pas de requête interactive /authorize .
Réponse du jeton
Si la requête réussit, Microsoft Entra ID retourne des jetons tels que :
{
"token_type": "Bearer",
"scope": "api://<resource-client-id>/<scope>",
"expires_in": 3599,
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"id_token": "<id-token>"
}
La réponse exacte dépend des étendues demandées :
- Utilisez le jeton d’accès uniquement avec la ressource identifiée par sa
audrevendication. - Utilisez le jeton d’ID pour établir la session de connexion de l’utilisateur, et non pour appeler une API.
- Un jeton d’actualisation est retourné lorsque la demande et la stratégie autorisent l’accès hors connexion.
Besoins de sécurité
- Utilisez PKCE avec la méthode de
S256défi pour les clients publics. Utilisez également PKCE pour les clients confidentiels lorsque la bibliothèque la prend en charge. - Correspond à l’URI de redirection exactement dans les demandes d’autorisation et de jeton.
- Générez un nouveau
statevérificateur ,nonceet PKCE pour chaque demande d’autorisation. - Échangez un code d’autorisation une seule fois et uniquement à partir du client qui a démarré la demande.
- Ne journalisez pas les codes d’autorisation, les informations d’identification du client, les jetons d’accès, les jetons d’actualisation ou les jetons d’ID.
- Valider les jetons d’accès dans l’API. Ne traitez pas la possession d’un code d’autorisation ou d’un jeton d’ID comme une autorisation d’API.
Contenu connexe
- Plateforme d'identités Microsoft et flux de code d’autorisation OAuth 2.0
- Applications clientes publiques et confidentielles
- Restrictions et limitations de l’URI de redirection
- Informations d’identification de certificat pour l’authentification d’application
- Choisir un protocole d’authentification pour un agent