本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用者屬性端點
<a name="userinfo-endpoint"></a>

當 OIDC 發出包含使用者屬性的 ID 字符時，OAuth 2.0 會實作`/oauth2/userInfo`端點。已驗證的使用者或用戶端會收到具有`scopes`宣告的存取字符。此宣告會決定授權伺服器應傳回的屬性。當應用程式向`userInfo`端點顯示存取字符時，授權伺服器會傳回回應內文，其中包含位於存取字符範圍所設定邊界內的使用者屬性。您的應用程式可以從`userInfo`端點擷取有關使用者的資訊，只要它擁有至少具有`openid`範圍宣告的有效存取字符。

`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.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/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`**  
存取權杖已過期、已撤銷、格式錯誤或無效。