本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 用户属性端点
<a name="userinfo-endpoint"></a>

在 OIDC 发布包含用户属性的 ID 令牌的地方， OAuth 2.0 实现端点。`/oauth2/userInfo`经过身份验证的用户或客户端会收到包含 `scopes` 声明的访问令牌。此声明决定了授权服务器应返回的属性。当应用程序向 `userInfo` 端点提供访问令牌时，授权服务器会返回一个响应正文，其中包含通过访问令牌范围设置的边界内的用户属性。只要您的应用程序持有至少具有 `openid` 范围声明的有效访问令牌，就可以从 `userInfo` 端点检索有关用户的信息。

`userInfo` 端点是 OpenID Connect（OIDC）[userInfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。当服务提供商出示您的[令牌端点](token-endpoint.md)发放的访问令牌时，响应中会包含用户属性。用户访问令牌中的范围定义了 userInfo 端点在其响应中返回的用户属性。`openid` 范围必须是访问令牌声明的范围之一。

Amazon Cognito 颁发访问令牌来响应用户池 API 请求，如 [https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)。由于它们不包含任何范围，因此 userInfo 端点不接受这些访问令牌。而是必须由您出示来自令牌端点的访问令牌。

您的 OAuth 2.0 第三方身份提供商 (IdP) 还托管一个userInfo终端节点。当您的用户使用该 IdP 进行身份验证时，Amazon Cognito 会以静默方式与 IdP `token` 端点交换授权代码。您的用户池传递 IdP 访问令牌以授权从 IdP `userInfo` 端点检索用户信息。

用户访问令牌中的范围由身份验证请求中的 `scopes` 请求参数或[令牌生成前 Lambda 触发器](user-pool-lambda-pre-token-generation.md)添加的范围确定。您可以解码访问令牌并检查 `scope` 声明，以查看其包含的访问控制范围。以下是一些影响从 `userInfo` 端点返回的数据的范围组合。保留的 Amazon Cognito 范围 `aws.cognito.signin.user.admin` 对从该端点返回的数据没有影响。访问令牌中的示例范围及其对 `userInfo` 响应的影响

**`openid`**  
返回包含应用程序客户端可以读取的所有用户属性的响应。

**`openid profile`**  
返回用户属性 `name`、`family_name`、`given_name`、`middle_name`、`nickname`、`preferred_username`、`profile`、`picture`、`website`、`gender`、`birthdate`、`zoneinfo`、`locale` 和 `updated_at`。还会返回[自定义属性](user-pool-settings-attributes.md#user-pool-settings-custom-attributes)。在对每个属性都没有读取权限的应用程序客户端中，对此范围的响应是您的应用程序客户端具有读取权限的规范中的所有属性。

**`openid email`**  
返回基本配置文件信息以及 `email` 和 `email_verified` 属性。

**`openid phone`**  
返回基本配置文件信息以及 `phone_number` 和 `phone_number_verified` 属性。

## GET /oauth2/userInfo
<a name="get-userinfo"></a>

您的应用程序直接生成对此端点的请求，而不是通过浏览器。

有关更多信息，请参阅 OpenID Connect（OIDC）规范中的 [UserInfo 端点](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。

**Topics**
+ [GET /oauth2/userInfo](#get-userinfo)
+ [标头中的请求参数](#get-userinfo-request-header-parameters)
+ [示例：请求](#get-userinfo-positive-exchanging-authorization-code-for-userinfo-sample-request)
+ [示例：正向响应](#get-userinfo-response-sample)
+ [示例：负向响应](#get-userinfo-negative)

## 标头中的请求参数
<a name="get-userinfo-request-header-parameters"></a>

**`Authorization: Bearer <access_token>`**  
传递授权标头字段中的访问令牌。  
必需。

## 示例：请求
<a name="get-userinfo-positive-exchanging-authorization-code-for-userinfo-sample-request"></a>

```
GET /oauth2/userInfo HTTP/1.1
Content-Type: application/x-amz-json-1.1
Authorization: Bearer eyJra12345EXAMPLE
User-Agent: [User agent]
Accept: */*
Host: auth.example.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
```

## 示例：正向响应
<a name="get-userinfo-response-sample"></a>

```
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: [Integer]
Date: [Timestamp]
x-amz-cognito-request-id: [UUID]
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Server: Server
Connection: keep-alive
{
    "sub": "[UUID]",
    "email_verified": "true",
    "custom:mycustom1": "CustomValue",
    "phone_number_verified": "true",
    "phone_number": "+12065551212",
    "email": "bob@example.com",
    "username": "bob"
}
```

有关 OIDC 声明的列表，请参阅[标准声明](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)。目前，Amazon Cognito 将 `email_verified` 和 `phone_number_verified` 的值返回为字符串。

## 示例：负向响应
<a name="get-userinfo-negative"></a>

### 示例：不正确的请求
<a name="get-userinfo-negative-400"></a>

```
HTTP/1.1 400 Bad Request
WWW-Authenticate: error="invalid_request",
error_description="Bad OAuth2 request at UserInfo Endpoint"
```

**`invalid_request`**  
请求缺少必需的参数、包括不支持的参数值或格式错误。

### 示例：不正确的令牌
<a name="get-userinfo-negative-401"></a>

```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="Access token is expired, disabled, or deleted, or the user has globally signed out."
```

**`invalid_token`**  
访问令牌已过期、已撤销、格式不正确或无效。