Point de terminaison UserInfo de la plateforme d’identités MicrosoftMicrosoft identity platform UserInfo endpoint

Le point de terminaison UserInfo fait partie de la norme OpenID Connect (OIDC), conçue pour retourner des revendications sur l’utilisateur qui s’est authentifié.The UserInfo endpoint is part of the OpenID Connect standard (OIDC), designed to return claims about the user that authenticated. Pour la plateforme d’identités Microsoft, le point de terminaison UserInfo est hébergé sur Microsoft Graph (https://graph.microsoft.com/oidc/userinfo).For the Microsoft identity platform, the UserInfo endpoint is hosted on Microsoft Graph (https://graph.microsoft.com/oidc/userinfo).

Rechercher le point de terminaison de configuration bien connuFind the .well-known configuration endpoint

Vous pouvez découvrir par programmation le point de terminaison UserInfo à l’aide du document de découverte OpenID Connect, à cet emplacement https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.You can programmatically discover the UserInfo endpoint using the OpenID Connect discovery document, at https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Il est indiqué dans le champ userinfo_endpoint ; ce modèle peut être utilisé dans les clouds pour aider à pointer vers le point de terminaison approprié.It’s listed in the userinfo_endpoint field, and this pattern can be used across clouds to help point to the right endpoint. Nous déconseillons de coder en dur le point de terminaison UserInfo dans votre application, utilisez plutôt le document de découverte OIDC pour rechercher ce point de terminaison au moment de l’exécution.We do not recommend hard-coding the UserInfo endpoint in your app – use the OIDC discovery document to find this endpoint at runtime instead.

Dans le cadre de la spécification OpenID Connect, le point de terminaison UserInfo est souvent appelé automatiquement par des bibliothèques conformes OIDC pour obtenir des informations sur l’utilisateur.As part of the OpenID Connect specification, the UserInfo endpoint is often automatically called by OIDC compliant libraries to get information about the user. Sans héberger un tel point de terminaison, la plateforme d’identités Microsoft ne serait pas conforme aux normes, et certaines bibliothèques échoueraient.Without hosting such an endpoint, Microsoft identity platform would not be standards compliant and some libraries would fail. À partir de la liste des revendications identifiées dans la norme OIDC, nous produisons les revendications de nom, la revendication de l’objet et l’adresse e-mail, lorsqu’elles sont disponibles et consenties.From the list of claims identified in the OIDC standard we produce the name claims, subject claim, and email when available and consented for.

Vous devez : Utiliser un jeton d’ID à la placeConsider: Use an ID Token instead

Les informations disponibles dans le jeton d’ID que votre application peut recevoir sont un sur-ensemble des informations qu’il peut obtenir du point de terminaison UserInfo.The information available in the ID token that your app can receive is a superset of the information it can get from the UserInfo endpoint. Dès lors que vous pouvez obtenir un jeton d’ID en même temps que vous obtenez un jeton permettant d’appeler le point de terminaison UserInfo, nous vous suggérons d’utiliser ce jeton d’ID pour obtenir des informations sur l’utilisateur au lieu d’appeler le point de terminaison UserInfo.Because you can get an ID token at the same time you get a token to call the UserInfo endpoint, we suggest that you use that ID token to get information about the user instead of calling the UserInfo endpoint. L’utilisation du jeton d’ID supprimera une à deux requêtes réseau du lancement de votre application, ce qui réduira la latence dans votre application.Using the ID token will eliminate one to two network requests from your application launch, reducing latency in your application.

Si vous avez besoin de détails supplémentaires sur l’utilisateur, appelez l’API Microsoft Graph /user pour obtenir des informations telles que le numéro de téléphone du bureau ou le poste.If you require more details about the user, you should call the Microsoft Graph /user API to get information like office number or job title. Vous pouvez également utiliser des revendications facultatives pour inclure des informations utilisateur supplémentaires dans vos jetons d’ID et d’accès.You can also use optional claims to include additional user information in your ID and access tokens.

Appel du point de terminaison UserInfoCalling the UserInfo endpoint

UserInfo est une API de jeton de porteur OAuth standard, appelée comme n’importe quelle autre API Microsoft Graph, à l’aide du jeton d’accès reçu lors de l’obtention d’un jeton pour Microsoft Graph.UserInfo is a standard OAuth Bearer token API, called like any other Microsoft Graph API using the access token received when getting a token for Microsoft Graph. Elle retourne une réponse JSON contenant les revendications relatives à l’utilisateur.It returns a JSON response containing claims about the user.

AutorisationsPermissions

Utilisez les autorisations OIDC suivantes pour appeler l’API UserInfo.Use the following OIDC permissions to call the UserInfo API. openid est obligatoire, et les étendues profile et email garantissent que des informations supplémentaires sont fournies dans la réponse.openid is required, and the profile and email scopes ensure that additional information is provided in the response.

Type d'autorisationPermission type AutorisationsPermissions
Déléguée (compte professionnel ou scolaire)Delegated (work or school account) openid (obligatoire), profil, e-mailopenid (required), profile, email
Déléguée (compte Microsoft personnel)Delegated (personal Microsoft account) openid (obligatoire), profil, e-mailopenid (required), profile, email
ApplicationApplication Non applicableNot applicable

Conseil

Copiez cette URL dans votre navigateur afin d’obtenir un jeton pour le point de terminaison UserInfo ainsi qu’un jeton d’ID, puis remplacez l’ID client et l’URI de redirection par les vôtres.Copy this URL in your browser to get a token for the UserInfo endpoint as well as an ID token and replace the client ID and redirect URI with your own. Notez qu’elle ne demande que des étendues pour les étendues OpenID ou Graph, et rien d’autre.Note that it only requests scopes for OpenID or Graph scopes, and nothing else. Cela est nécessaire, car vous ne pouvez pas demander d’autorisations pour deux ressources différentes dans la même demande de jeton.This is required, since you cannot request permissions for two different resources in the same token request.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=<yourClientID>&response_type=token+id_token&redirect_uri=<YourRedirectUri>&scope=user.read+openid+profile+email&response_mode=fragment&state=12345&nonce=678910

Vous pouvez utiliser ce jeton d’accès à la section suivante.You can use this access token in the next section.

Comme pour tout autre jeton Microsoft Graph, le jeton que vous recevez ici peut ne pas être un jeton JWT.As with any other Microsoft Graph token, the token you receive here may not be a JWT. Si vous avez connecté un utilisateur de compte Microsoft, il s’agira d’un format de jeton chiffré.If you signed in a Microsoft account user, it will be an encrypted token format. Cela est dû au fait que Microsoft Graph dispose d’un modèle d’émission de jeton spécial.This is because Microsoft Graph has a special token issuance pattern. Cela n’a aucune incidence sur votre capacité à utiliser le jeton d’accès pour appeler le point de terminaison UserInfo.This does not impact your ability to use the access token to call the UserInfo endpoint.

Appel de l’APICalling the API

L’API UserInfo prend en charge GET et POST, conformément à la spécification OIDC.The UserInfo API supports both GET and POST, per the OIDC spec.

GET or POST /oidc/userinfo HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…

Réponse UserInfoUserInfo response

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // names all require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "email": "mikoll@contoso.com" //requires the “email” scope.
}

Les revendications listées ici, y compris sub, sont les mêmes revendications que celles que l’application verrait dans le jeton d’ID délivré à l’application.The claims listed here, including sub, are the same claims that the app would see in the ID token issued to the app.

Remarques et avertissements sur le point de terminaison UserInfoNotes and caveats on the UserInfo endpoint

  • Si vous souhaitez appeler ce point de terminaison UserInfo, vous devez utiliser le point de terminaison v2.0.If you want to call this UserInfo endpoint you must use the v2.0 endpoint. Si vous utilisez le point de terminaison v1.0, vous obtiendrez un jeton pour le point de terminaison UserInfo v1.0, qui est hébergé sur login.microsoftonline.com.If you use the v1.0 endpoint you will get a token for the v1.0 UserInfo endpoint, hosted on login.microsoftonline.com. Nous recommandons que toutes les applications et bibliothèques conformes à OIDC utilisent le point de terminaison v2.0 pour garantir la compatibilité.We recommend that all OIDC compliant apps and libraries use the v2.0 endpoint to ensure compatibility.
  • La réponse du point de terminaison UserInfo ne peut pas être personnalisée.The response from the UserInfo endpoint cannot be customized. Si vous souhaitez personnaliser les revendications, utilisez le mappage de revendications pour modifier les informations retournées dans les jetons.If you’d like to customize claims, please use claims mapping to edit the information returned in the tokens.
  • Il est impossible d’ajouter quelque chose à la réponse du point de terminaison UserInfo.The response from the UserInfo endpoint cannot be added to. Si vous souhaitez obtenir des revendications supplémentaires sur l’utilisateur, utilisez les revendications facultatives pour ajouter de nouvelles revendications aux jetons.If you’d like to get additional claims about the user, please use optional claims to add new claims to the tokens.

Étapes suivantesNext Steps