Microsoft标识平台 UserInfo 终结点

2025-06-29

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

查找 .known 配置终结点

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

UserInfo 终结点通常由符合 OIDC 的库自动调用，以获取有关用户的信息。从 OIDC 标准中标识的声明列表中，Microsoft标识平台在可用和同意时生成名称声明、使用者声明和电子邮件。

请考虑改用 ID 令牌

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

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

调用 UserInfo 终结点

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

权限

使用以下 OIDC 权限调用 UserInfo API。声明 openid 是必需的，并且 profile 范围 email 确保响应中提供了其他信息。

权限类型	权限
委派（工作或学校帐户）	`openid`（必需）， `profileemail`
委派（个人 Microsoft 帐户）	`openid`（必需）， `profileemail`
应用程序	不適用

小窍门

在浏览器中复制此 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 终结点返回的信息。

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