Microsoft 标识平台的 UserInfo 终结点

项目
12/19/2023

作为 OpenID Connect (OIDC) 标准的一部分，UserInfo 终结点返回有关经过身份验证用户的信息。

查找 .well-known 配置终结点

可以通过读取 https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration 上的 OpenID 配置文档的 userinfo_endpoint 字段来以编程方式查找 UserInfo 终结点。不建议在应用程序中对 UserInfo 终结点进行硬编码。应该在运行时使用 OIDC 配置文档查找该终结点。

UserInfo 终结点通常由符合 OIDC 的库自动调用，以获取有关用户的信息。 Microsoft 标识平台根据 OIDC 标准中标识的声明列表生成名称声明、主题声明和电子邮件（如果这些项可用并已获得许可）。

考虑改用 ID 令牌

ID 令牌中的信息是 UserInfo 终结点上可用信息的超集。由于在获取令牌以调用 UserInfo 终结点的同时可获取 ID 令牌，我们建议获取令牌中的用户信息，而不是调用 UserInfo 终结点。使用 ID 令牌而不调用 UserInfo 终结点最多可消除两个网络请求，并降低应用程序的延迟。

如需有关用户的更多详细信息（例如经理或职务），请调用 Microsoft Graph /user API。你还可以使用可选声明在 ID 和访问令牌中包括其他用户信息。

调用 UserInfo 终结点

UserInfo 是由 Microsoft Graph 托管的标准 OAuth 持有者令牌 API。使用应用程序在请求访问 Microsoft Graph 时收到的访问令牌，像调用任何 Microsoft Graph API 一样调用 UserInfo 终结点。 UserInfo 终结点返回 JSON 响应，其中包含有关用户的声明。

权限

使用以下 OIDC 权限调用 UserInfo API。 openid 声明是必需的，profile 和 email 范围确保在响应中提供附加信息。

权限类型	权限
委托的（工作或学校帐户）	`openid`（必须）、`profile`、`email`
委托的（个人 Microsoft 帐户）	`openid`（必须）、`profile`、`email`
应用程序	不适用

提示

在浏览器中复制此 URL 以获取 UserInfo 终结点的访问令牌和 ID 令牌。将客户端 ID 和重定向 URI 替换为应用注册中的值。

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

可以使用在下一部分所述的查询中返回的访问令牌。

Microsoft Graph 使用特殊的令牌颁发模式，该模式可能会影响应用读取或验证该令牌的能力。与任何其他 Microsoft Graph 令牌一样，你在此处收到的令牌可能不是 JWT，应用应将其视为不透明。如果登录了一个 Microsoft 帐户用户，它将是加密令牌格式。但是，这些因素都不会影响应用在对 UserInfo 终结点的请求中使用访问令牌的能力。

调用 API

UserInfo API 支持 GET 和 POST 请求。

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

UserInfo 响应

{
    "sub": "OLu859SGc2Sr9ZsqbkG-QbeLgJlb41KcdiPoLYNpSFA",
    "name": "Mikah Ollenburg", // all names require the “profile” scope.
    "family_name": " Ollenburg",
    "given_name": "Mikah",
    "picture": "https://graph.microsoft.com/v1.0/me/photo/$value",
    "email": "mikoll@contoso.com" // requires the “email” scope.
}

响应中显示的声明都是 UserInfo 终结点可以返回的声明。这些值与 ID 令牌中包含的值相同。

有关 UserInfo 终结点的说明和注意事项

无法在 UserInfo 终结点返回的信息中添加内容或自定义这些信息。

若要自定义标识平台在身份验证和授权期间返回的信息，请使用声明映射和可选声明来修改安全令牌配置。

通过