Microsoft 标识平台的 UserInfo 终结点Microsoft identity platform UserInfo endpoint

UserInfo 终结点是 OpenID Connect 标准 (OIDC) 的一部分,用于返回有关已通过身份验证的用户的声明。The UserInfo endpoint is part of the OpenID Connect standard (OIDC), designed to return claims about the user that authenticated. 对于 Microsoft 标识平台,UserInfo 终结点承载在 Microsoft Graph (https://microsoftgraph.chinacloudapi.cn/oidc/userinfo) 上。For the Microsoft identity platform, the UserInfo endpoint is hosted on Microsoft Graph (https://microsoftgraph.chinacloudapi.cn/oidc/userinfo).

查找 .well-known 配置终结点Find the .well-known configuration endpoint

你可以使用 https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration 上的 OpenID Connect 发现文档以编程方式发现 UserInfo 终结点。You can programmatically discover the UserInfo endpoint using the OpenID Connect discovery document, at https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration. 它在 userinfo_endpoint 字段中列出,该模式可以在各个云中用来指向正确的终结点。It’s listed in the userinfo_endpoint field, and this pattern can be used across clouds to help point to the right endpoint. 不建议在应用中对 UserInfo 终结点进行硬编码,请改用 OIDC 发现文档在运行时查找此终结点。We do not recommend hard-coding the UserInfo endpoint in your app - use the OIDC discovery document to find this endpoint at runtime instead.

根据 OpenID Connect 规范,符合 OIDC 规范的库通常会自动调用 UserInfo 终结点以获取用户的信息。As part of the OpenID Connect specification, the UserInfo endpoint is often automatically called by OIDC compliant libraries to get information about the user. 如果不承载此类终结点,Microsoft 标识平台就不符合标准,某些库会失败。Without hosting such an endpoint, Microsoft identity platform would not be standards compliant and some libraries would fail. 我们根据 OIDC 标准中标识的声明的列表生成名称声明、主题声明和电子邮件(如果这些项可用并已获得许可)。From the list of claims identified in the OIDC standard we produce the name claims, subject claim, and email when available and consented for.

请考虑:改用 ID 令牌Consider: Use an ID Token instead

应用可以接收的 ID 令牌中提供的信息是它可以从 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. 由于你可以在获取用于调用 UserInfo 终结点的令牌的同时获取 ID 令牌,因此建议你使用该 ID 令牌获取用户的信息,而不必调用 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. 使用 ID 令牌可以在应用程序启动时消除一到两个网络请求,从而降低应用程序中的延迟。Using the ID token will eliminate one to two network requests from your application launch, reducing latency in your application.

如果需要有关用户的更多详细信息,则应调用 Microsoft Graph /user API 来获取该信息,例如办公电话或职务。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. 你还可以使用可选声明在 ID 和访问令牌中包括其他用户信息。You can also use optional claims to include additional user information in your ID and access tokens.

调用 UserInfo 终结点Calling the UserInfo endpoint

UserInfo 是一个标准的 OAuth 持有者令牌 API,与任何其他 Microsoft Graph API 一样,将使用为 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. 它返回一个 JSON 响应,其中包含有关用户的声明的。It returns a JSON response containing claims about the user.

权限Permissions

使用以下 OIDC 权限调用 UserInfo API。Use the following OIDC permissions to call the UserInfo API. openid 是必需的,而 profileemail 作用域则可确保在响应中提供其他信息。openid is required, and the profile and email scopes ensure that additional information is provided in the response.

权限类型Permission type 权限Permissions
委托的(工作或学校帐户)Delegated (work or school account) openid(必需)、profile、emailopenid (required), profile, email
应用程序Application 不适用Not applicable

提示

将以下 URL 复制到你的浏览器中以获取 UserInfo 终结点的令牌以及 ID 令牌,并将客户端 ID 和重定向 URI 替换为你自己的值。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. 请注意,它只请求 OpenID 作用域或 Graph 作用域,而不请求其他内容。Note that it only requests scopes for OpenID or Graph scopes, and nothing else. 这是必需的,因为无法在同一令牌请求中请求两个不同资源的权限。This is required, since you cannot request permissions for two different resources in the same token request.

https://login.partner.microsoftonline.cn/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

在下一部分中,你可以使用此访问令牌。You can use this access token in the next section.

与任何其他 Microsoft Graph 令牌一样,你在此处收到的令牌可能不是 JWT。As with any other Microsoft Graph token, the token you receive here may not be a JWT. 如果登录了一个 Microsoft 帐户用户,它将是加密令牌格式。If you signed in a Microsoft account user, it will be an encrypted token format. 这是因为 Microsoft Graph 具有特殊的令牌颁发模式。This is because Microsoft Graph has a special token issuance pattern. 这不会影响你使用访问令牌调用 UserInfo 终结点的能力。This does not impact your ability to use the access token to call the UserInfo endpoint.

调用 APICalling the API

根据 OIDC 规范,UserInfo API 同时支持 GET 和 POST。The UserInfo API supports both GET and POST, per the OIDC spec.

GET or POST /oidc/userinfo HTTP/1.1
Host: microsoftgraph.chinacloudapi.cn
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6Il…

UserInfo 响应UserInfo 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.
}

此处列出的声明(包括 sub)与应用在颁发给应用的 ID 令牌中看到的声明相同。The claims listed here, including sub, are the same claims that the app would see in the ID token issued to the app.

有关 UserInfo 终结点的说明和注意事项Notes and caveats on the UserInfo endpoint

  • 如果要调用此 UserInfo 终结点,则必须使用 v2.0 终结点。If you want to call this UserInfo endpoint you must use the v2.0 endpoint. 如果使用 v1.0 终结点,你将获得在 login.partner.microsoftonline.cn 上承载的 v1.0 UserInfo 终结点的令牌。If you use the v1.0 endpoint you will get a token for the v1.0 UserInfo endpoint, hosted on login.partner.microsoftonline.cn. 建议符合 OIDC 的所有应用和库都使用 v2.0 终结点,以确保兼容性。We recommend that all OIDC compliant apps and libraries use the v2.0 endpoint to ensure compatibility.
  • 无法自定义来自 UserInfo 终结点的响应。The response from the UserInfo endpoint cannot be customized. 如果要自定义声明,请使用声明映射编辑令牌中返回的信息。If you’d like to customize claims, please use claims mapping to edit the information returned in the tokens.
  • 无法添加来自 UserInfo 终结点的响应。The response from the UserInfo endpoint cannot be added to. 若要获取有关用户的其他声明,请使用可选声明将新声明添加到令牌中。If you’d like to get additional claims about the user, please use optional claims to add new claims to the tokens.

后续步骤Next Steps