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

# 了解存取權杖
<a name="amazon-cognito-user-pools-using-the-access-token"></a>

使用者集區存取權杖包含已驗證使用者的相關宣告、使用者的群組清單，以及範圍的清單。存取權杖的目的是授權 API 操作。您的使用者集區接受存取權杖以授權使用者自助服務操作。例如，您可使用存取權杖，授予能新增、變更或刪除使用者屬性的使用者存取權限。

使用存取權杖中的 [OAuth 2.0 範圍](https://www.rfc-editor.org/rfc/rfc6749#section-3.3) (衍生自您新增到使用者集區的自訂範圍)，您可以授權使用者從 API 擷取資訊。例如，Amazon API Gateway 支援使用 Amazon Cognito 存取權杖進行授權。您可以使用取自使用者集區的資訊填入 REST API 授權方，或使用 Amazon Cognito 做為 HTTP API 的 JSON Web 權杖 (JWT) 授權方。若要產生具有自訂範圍的存取權杖，您必須透過使用者集區[公有端點](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html)來請求。

透過 Essentials 或 Plus [功能計劃](cognito-sign-in-feature-plans.md)，您也可以實作權杖產生前 Lambda 觸發程序，在執行時間將範圍新增至您的存取權杖。如需詳細資訊，請參閱[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。

具有 `openid`範圍的使用者存取權杖是向 請求使用者屬性詳細資訊的許可[userInfo 端點](userinfo-endpoint.md)。來自`userInfo`端點的資訊量衍生自存取字符中的其他範圍：例如，`profile`針對所有使用者資料，`email`針對其電子郵件地址。

具有 `aws.cognito.signin.user.admin`範圍的使用者存取權杖是讀取和寫入使用者屬性、列出身分驗證因素、設定多重驗證 (MFA) 偏好設定和管理記住裝置的許可。存取字符授予此範圍之屬性的存取層級，符合您指派給應用程式用戶端的屬性讀取/寫入許可。

存取權杖是 [JSON Web 權杖 (JWT)](https://www.rfc-editor.org/rfc/rfc7519)。存取權杖標頭的結構與 ID 權杖相同。Amazon Cognito 使用與簽署 ID 權杖不同的金鑰簽署存取權杖。存取金鑰 ID (`kid`) 宣告的值不會符合來自同一使用者工作階段之 ID 權杖中 `kid` 宣告的值。在您的應用程式程式碼中，獨立驗證 ID 權杖和存取權杖。在驗證簽章之前，請勿信任存取權杖中的宣告。如需詳細資訊，請參閱[驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。您可以將存取權限有效期限設為 5 分鐘到 1 天之間的任何值。此值可根據應用程式用戶端設定。

**重要**  
對於存取和 ID 字符，如果您使用受管登入，請不要指定少於一小時。受管登入會設定一小時有效的瀏覽器 Cookie。如果您將存取權杖持續時間設定為不到一小時，這不會影響受管登入 Cookie 的有效性，而且使用者在初次登入後一小時無需額外登入資料即可重新驗證。

## 存取權杖標頭
<a name="user-pool-access-token-header"></a>

標頭包含兩項資訊：金鑰 ID (`kid`) 和演算法 (`alg`)。

```
{
"kid" : "1234example="
"alg" : "RS256",
}
```

**`kid`**  
金鑰 ID。它的值指出用於保護權杖之 JSON Web Signature (JWS) 的金鑰。您可以在 `jwks_uri` 端點檢視您的使用者集區簽署金鑰 ID。  
如需 `kid` 參數的詳細資訊，請參閱[金鑰識別符 (kid) 標頭參數](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.5)。

**`alg`**  
Amazon Cognito 用來保護存取權杖安全的加密演算法。使用者集區是使用 RS256 演算法，即採用 SHA-256 的 RSA 簽章。  
如需 `alg` 參數的詳細資訊，請參閱[演算法 (alg) 標頭參數](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-41#section-4.4)。

## 存取字符預設承載
<a name="user-pool-access-token-payload"></a>

這是一個存取權杖酬載範例。如需詳細資訊，請參閱 [JWT 宣告](https://tools.ietf.org/html/rfc7519#section-4)。您可以使用 新增自己的設計宣告[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。

```
{{<header>}}.
{
   "sub":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "device_key": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "cognito:groups":[
      "testgroup"
   ],
   "iss":"https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example",
   "version":2,
   "client_id":"xxxxxxxxxxxxexample",
   "aud": "https://api.example.com",
   "origin_jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "event_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "token_use":"access",
   "scope":"phone openid profile resourceserver.1/appclient2 email",
   "auth_time":1676313851,
   "exp":1676317451,
   "iat":1676313851,
   "jti":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
   "username":"my-test-user"
}
.{{<token signature>}}
```

**`sub`**  
已驗證使用者的唯一識別符 ([UUID](cognito-terms.md#terms-uuid)) 或主體。使用者名稱在您的使用者集區中可能不是唯一的。`sub` 宣告是識別特定使用者的最佳方法。

**`cognito:groups`**  
以您的使用者為成員的使用者集區群組名稱陣列。

**`iss`**  
發行權杖的身分提供者。宣告的格式如下。  
`https://cognito-idp.{{us-east-1}}.amazonaws.com/{{us-east-1_EXAMPLE}}`

**`client_id`**  
對您的使用者進行身分驗證的使用者集區應用程式用戶端。Amazon Cognito 會在 ID 權杖 `aud` 宣告中呈現相同的值。

**aud**  
存取權杖要授權的 API URL。只有當您的應用程式請求來自授權伺服器[的資源繫結](cognito-user-pools-define-resource-servers.md#cognito-user-pools-resource-binding)時，才會顯示。

**`origin_jti`**  
與使用者的重新整理權杖相關的權杖撤銷識別符。Amazon Cognito 在檢查您是否使用 [撤銷端點](revocation-endpoint.md) 或 [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API 作業撤銷使用者權杖時，會參考 `origin_jti` 宣告。當您撤銷權杖時，Amazon Cognito 不會再驗證具有相同`origin_jti`值的存取和 ID 權杖。

**`token_use`**  
權杖的用途。在存取權杖中，其值為 `access`。

**`scope`**  
發給登入使用者的 OAuth 2.0 範圍清單。範圍定義權杖提供給`userInfo`端點上外部 APIs、使用者自助式操作和使用者資料的存取權。來自 [權杖端點](token-endpoint.md) 的權杖可以包含您的應用程式用戶端支援的任何範圍。來自 Amazon Cognito API 登入的權杖僅包含 `aws.cognito.signin.user.admin` 範圍。

**`auth_time`**  
您的使用者完成身分驗證的身分驗證時間 (以 Unix 時間格式表示)。

**`exp`**  
使用者權杖到期的到期時間 (以 Unix 時間格式表示)。

**`iat`**  
Amazon Cognito 發行您使用者權杖的時間 (採用 Unix 時間格式)。

**`jti`**  
JWT 的唯一識別碼。

**`username`**  
使用者集區中的使用者名稱。

**其他資源**
+ [如何在 Amazon Cognito 使用者集區中自訂存取權杖](https://aws.amazon.com/blogs/security/how-to-customize-access-tokens-in-amazon-cognito-user-pools/)

## 存取權杖簽章
<a name="user-pool-access-token-signature"></a>

以`.well-known/jwks.json`端點公告的金鑰簽署的存取權杖簽章，會驗證權杖標頭和承載的完整性。當您使用存取權杖授權存取外部 APIs 時，請一律設定您的 API 授權方，以針對簽署它的金鑰驗證此簽章。如需詳細資訊，請參閱[驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。