本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 了解使用者集區 JSON Web 字符 JWTs) 權杖是身分驗證的成品，您的應用程式可用來證明 OIDC 身分驗證並請求存取 資源。權杖中的*宣告*是有關您的使用者的資訊。ID 權杖包含有關其身分的宣告，例如其使用者名稱、姓氏和電子郵件地址。存取權杖包含 `scope` 之類的宣告，經過驗證的使用者可用來存取第三方 API、Amazon Cognito 使用者自助服務 API 操作，以及 [userInfo 端點](userinfo-endpoint.md)。存取和 ID 權杖都包含一個 `cognito:groups` 宣告，其中包含使用者集區中的使用者群組成員資格。如欲了解使用者集區群組的詳細資訊，請參閱[新增群組至使用者集區](cognito-user-pools-user-groups.md)。 Amazon Cognito 也重新整理權杖，您可以用來取得新權杖或撤銷現有權杖。[重新整理權杖](amazon-cognito-user-pools-using-the-refresh-token.md)來擷取新的 ID 和存取權杖。[撤銷權杖](amazon-cognito-user-pools-using-the-refresh-token.md#amazon-cognito-identity-user-pools-revoking-all-tokens-for-user)以撤銷重新整理權杖允許的使用者存取權限。 Amazon Cognito 會以 [base64url](https://datatracker.ietf.org/doc/html/rfc4648#section-5) 編碼字串的形式發出權杖。您可以將任何 Amazon Cognito ID 或存取權杖從 解碼`base64url`為純文字 JSON。Amazon Cognito 重新整理權杖已加密，對使用者集區使用者和管理員不透明，並只能由使用者集區讀取。 **權杖驗證** 使用者登入您的應用程式時，Amazon Cognito 會驗證登入資訊。如果登入成功，Amazon Cognito 就會為已驗證使用者建立工作階段，並傳回 ID 權杖、存取權杖和重新整理權杖。您可以使用這些權杖，授予使用者對下游資源和 Amazon API Gateway 等 API 的存取權。或者，您可以將其用於交換臨時 AWS 憑證，以便存取其他 AWS 服務。 ![\[身分驗證概觀\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/images/scenario-authentication-cup2.png) **存放權杖** 您的應用程式必須能夠存放不同大小的權杖。權杖大小可能會因各種原因而變更，包括但不限於額外宣告、編碼演算法變更和加密演算法變更。當您在使用者集區中啟用權杖撤銷時，Amazon Cognito 會向 JSON Web 權杖新增額外宣告，從而增加其大小。存取權杖和 ID 權杖中會新增 `origin_jti` 和 `jti` 宣告。如需有關權杖撤銷的詳細資訊，請參閱[撤銷權杖](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html)。 **重要** 最佳實務是在應用程式環境中傳輸及儲存所有權杖時，都要確保安全無虞。權杖可以包含有關使用者的個人識別資訊，以及用於使用者集區的安全模型相關資訊。 **自訂權杖** 您可以自訂 Amazon Cognito 傳遞給您應用程式的存取權和 ID 權杖。在[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)中，您可以新增、修改和抑制權杖宣告。產生權杖前觸發程序是 Amazon Cognito 向其傳送一組預設宣告的 Lambda 函數。這些宣告包括 OAuth 2.0 範圍，使用者集區群組成員資格、使用者屬性和其他。然後，函數可以藉此機會在執行階段進行變更，並將更新的權杖宣告傳回 Amazon Cognito。 使用第 2 版事件進行存取權杖自訂需要支付額外費用。如需詳細資訊，請參閱 [Amazon Cognito 定價](https://aws.amazon.com/cognito/pricing/)。 **Topics** + [了解身分 (ID) 字符](amazon-cognito-user-pools-using-the-id-token.md) + [了解存取權杖](amazon-cognito-user-pools-using-the-access-token.md) + [重新整理權杖](amazon-cognito-user-pools-using-the-refresh-token.md) + [使用字符撤銷結束使用者工作階段](token-revocation.md) + [驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md) + [管理使用者集區字符過期和快取](amazon-cognito-user-pools-using-tokens-caching-tokens.md) # 了解身分 (ID) 字符 ID 權杖是 [JSON Web 權杖 (JWT)](https://tools.ietf.org/html/rfc7519)，它包含已驗證使用者身分的相關宣告，例如 `name`、`email` 和 `phone_number`。您可以在應用程式內部使用此身分資訊。ID 權杖也可以用來向資源伺服器或伺服器應用程式驗證使用者的身分。您還可以透過 Web API 操作，在應用程式外使用 ID 權杖。在那些情況下，您必須先驗證 ID 權杖的簽章，才能信任 ID 權杖中的任何宣告。請參閱 [驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。 您可以將 ID 權杖過期設為 5 分鐘到 1 天的值。此值可根據應用程式用戶端設定。 **重要** 當您的使用者使用受管登入登入時，Amazon Cognito 會設定 1 小時內有效的工作階段 Cookie。如果您在應用程式中使用受管登入進行身分驗證，並為您的存取和 ID 字符指定少於 1 小時的最短持續時間，您的使用者仍會擁有有效的工作階段，直到 Cookie 過期為止。如果使用者的權杖會在一小時的工作階段內過期，則使用者可以重新整理其權杖，無需重新驗證身分。 ## ID 權杖標頭 標頭包含兩項資訊：金鑰 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)。 ## ID 字符預設承載 這是來自 ID 字符的範例承載。它包含有關已驗證使用者的宣告。如需 OpenID Connect (OIDC) 標準宣告的詳細資訊，請參閱 [OIDC 標準宣告](http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)清單。您可以使用 新增自己的設計宣告[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。 ```
.{ "sub": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:groups": [ "test-group-a", "test-group-b", "test-group-c" ], "email_verified": true, "cognito:preferred_role": "arn:aws:iam::111122223333:role/my-test-role", "iss": "https://cognito-idp.us-west-2.amazonaws.com/us-west-2_example", "cognito:username": "my-test-user", "middle_name": "Jane", "nonce": "abcdefg", "origin_jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "cognito:roles": [ "arn:aws:iam::111122223333:role/my-test-role" ], "aud": "xxxxxxxxxxxxexample", "identities": [ { "userId": "amzn1.account.EXAMPLE", "providerName": "LoginWithAmazon", "providerType": "LoginWithAmazon", "issuer": null, "primary": "true", "dateCreated": "1642699117273" } ], "event_id": "64f513be-32db-42b0-b78e-b02127b4f463", "token_use": "id", "auth_time": 1676312777, "exp": 1676316377, "iat": 1676312777, "jti": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "email": "my-test-user@example.com" } . ``` **`sub`** 已驗證使用者的唯一識別符 ([UUID](cognito-terms.md#terms-uuid)) 或主體。使用者名稱在您的使用者集區中可能不是唯一的。`sub` 宣告是識別特定使用者的最佳方法。 **`cognito:groups`** 以您的使用者為成員的使用者集區群組名稱陣列。群組可以是您呈現給應用程式的識別碼，也可以從身分池產生偏好 IAM 角色的請求。 **`cognito:preferred_role`** 您與使用者最高優先順序之使用者集區群組相關聯的 IAM 角色 ARN。如需使用者集區如何選取此角色宣告的詳細資訊，請參閱[指定優先順序值給群組](cognito-user-pools-user-groups.md#assigning-precedence-values-to-groups)。 **`iss`** 發行權杖的身分提供者。宣告的格式如下。 `https://cognito-idp..amazonaws.com/` **`cognito:username`** 您的使用者在您的使用者集區中的使用者名稱。 **`nonce`** `nonce` 宣告來自同名的參數，您可以在對 OAuth 2.0 `authorize` 端點的請求中新增此參數。新增參數時，`nonce` 宣告會包含在 Amazon Cognito 發出的 ID 權杖中，您可以使用它來防止重新執行攻擊。如果您未提供 `nonce` 值，Amazon Cognito 會在您透過第三方身分提供者進行身分驗證時自動產生並驗證 Nonce，然後將其新增為 ID 權杖中的 `nonce` 宣告。Amazon Cognito 中的 `nonce` 宣告實作符合 [OIDC 標準](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation)。 **`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 權杖無效。 **`cognito:roles`** 與使用者群組相關聯之 IAM 角色的名稱陣列。每個使用者集區群組都可以有一個與其關聯的 IAM 角色。此陣列代表使用者群組的所有 IAM 角色，無論優先順序為何。如需詳細資訊，請參閱[新增群組至使用者集區](cognito-user-pools-user-groups.md)。 **`aud`** 對您的使用者進行身分驗證的使用者集區應用程式用戶端。Amazon Cognito 會在存取權杖 `client_id` 宣告中呈現相同的值。 **`identities`** 使用者的 `identities` 屬性內容。此屬性包含您藉由聯合登入或[將聯合身分使用者連結至本機設定檔](cognito-user-pools-identity-federation-consolidate-users.md)，連結至使用者的每一個第三方身分提供者設定檔的相關資訊。此資訊包含其提供者名稱、提供者唯一 ID 和其他中繼資料。 **`token_use`** 權杖的用途。在 ID 權杖中，其值為 `id`。 **`auth_time`** 您的使用者完成身分驗證的身分驗證時間 (以 Unix 時間格式表示)。 **`exp`** 使用者權杖到期的到期時間 (以 Unix 時間格式表示)。 **`iat`** Amazon Cognito 發行您使用者權杖的時間 (採用 Unix 時間格式)。 **`jti`** JWT 的唯一識別碼。 ID 權杖可包含 [OIDC 標準宣告](https://openid.net/specs/openid-connect-core-1_0.html#Claims)所定義的 OIDC 標準宣告。這個 ID 權杖也可以包含您在使用者集區中所定義的自訂屬性。Amazon Cognito 將自訂屬性值做為字串寫入 ID 權杖，無論屬性類型為何。 **注意** 使用者集區自訂屬性一律以 為字首`custom:`。 ## ID 權杖簽章 ID 權杖的簽章是根據 JWT 權杖的標頭和酬載計算出來的。在您接受應用程式收到的任何 ID 權杖中的宣告之前，請先驗證權杖的簽章。如需詳細資訊，請參閱「驗證 JSON Web 權杖」。[驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。 # 了解存取權杖 使用者集區存取權杖包含已驗證使用者的相關宣告、使用者的群組清單，以及範圍的清單。存取權杖的目的是授權 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 的有效性，而且使用者在初次登入後一小時無需額外登入資料即可重新驗證。 ## 存取權杖標頭 標頭包含兩項資訊：金鑰 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)。 ## 存取字符預設承載 這是一個存取權杖酬載範例。如需詳細資訊，請參閱 [JWT 宣告](https://tools.ietf.org/html/rfc7519#section-4)。您可以使用 新增自己的設計宣告[產生權杖前 Lambda 觸發程序](user-pool-lambda-pre-token-generation.md)。 ```
. { "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" } . ``` **`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/) ## 存取權杖簽章 以`.well-known/jwks.json`端點公告的金鑰簽署的存取權杖簽章，會驗證權杖標頭和承載的完整性。當您使用存取權杖授權存取外部 APIs 時，請一律設定您的 API 授權方，以針對簽署它的金鑰驗證此簽章。如需詳細資訊，請參閱[驗證 JSON Web 字符](amazon-cognito-user-pools-using-tokens-verifying-a-jwt.md)。 # 重新整理權杖 您可以使用重新整理權杖來擷取新的 ID 權杖和存取權杖。在預設情況下，重新整理權杖會在您的應用程式使用者登入您的使用者集區起 30 天後過期。當建立使用者集區的應用程式時，您可以將應用程式的重新整理權杖過期設為 60 分鐘到 10 年之間的任何值。 ## 使用重新整理權杖取得新的存取和身分權杖 Amazon Cognito 會發出重新整理權杖，以使用受管登入授權碼流程和 API 操作或 SDK 方法成功進行身分驗證。重新整理權杖會傳回新的 ID 和存取權杖，以及選擇性的新重新整理權杖。您可以透過下列方式使用重新整理權杖。 **GetTokensFromRefreshToken** [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API 操作會從有效的重新整理權杖發出新的 ID 和存取權杖。如果您已啟用重新整理權杖輪換，也會收到新的重新整理權杖。 **InitiateAuth 和 AdminitiateAuth** [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 或 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 操作包含`REFRESH_TOKEN_AUTH`身分驗證流程。在此流程中，您會傳遞重新整理權杖，並取得新的 ID 和存取權杖。您無法在啟用[重新整理權杖輪換](#using-the-refresh-token-rotation)的應用程式用戶端`REFRESH_TOKEN_AUTH`中使用 進行身分驗證。 **OAuth 字符端點** 具有[網域](cognito-user-pools-assign-domain.md)之使用者集區的權[杖端點](token-endpoint.md)具有`refresh_token`授予類型，可從有效的重新整理權杖發出新的 ID、存取和選擇性 （使用[重新整理權杖輪換](#using-the-refresh-token-rotation)) 重新整理權杖。 ## 重新整理權杖輪換 您可以選擇性地在應用程式用戶端中設定重新整理字符輪換。透過重新整理字符輪換，您的用戶端可以使原始重新整理字符失效，並在每次字符重新整理時發出新的重新整理字符。啟用此設定時，所有形式的字符重新整理中的每個成功請求都會傳回新的 ID、存取*和*重新整理字符。停用此設定時，權杖重新整理請求只會傳回新的存取權和 ID 權杖，而原始重新整理權杖仍然有效。新的重新整理權杖在原始重新整理權杖的剩餘持續時間內有效。您可以設定[應用程式用戶端](user-pool-settings-client-apps.md)來輪換重新整理權杖或轉移原始重新整理權杖。若要允許短暫重試，您也可以為原始重新整理字符設定最長 60 秒的寬限期。 **重新整理字符輪換的須知事項** + 啟用重新整理權杖輪換之後，新的宣告會從使用者集區新增至 JSON Web 權杖。存取權杖和 ID 權杖中會新增 `origin_jti` 和 `jti` 宣告。這些宣告會增加 JWTs的大小。 + 重新整理字符輪換與身分驗證流程不相容`REFRESH_TOKEN_AUTH`。若要實作重新整理字符輪換，您必須在應用程式用戶端中停用此身分驗證流程，並設計應用程式以使用 [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API 操作或同等 SDK 方法提交字符重新整理請求。 + 重新整理字符輪換非作用中時，您可以使用 `GetTokensFromRefreshToken`或 完成字符重新整理請求`REFRESH_TOKEN_AUTH`。 + 當使用者集區中的[裝置記住](amazon-cognito-user-pools-device-tracking.md)處於作用中狀態時，您必須在`GetTokensFromRefreshToken`請求中提供裝置金鑰。如果您的使用者在初始身分驗證請求中沒有應用程式提交的已確認裝置金鑰，Amazon Cognito 會發出新的金鑰。若要重新整理此組態中的權杖，無論您在 中指定權杖，`AuthParameters`或在身分驗證回應中收到新的權杖，都必須提供裝置金鑰。 + 您可以在`GetTokensFromRefreshToken`請求中傳遞`ClientMetadata`至權杖產生前的 Lambda 觸發程序。此資料會傳遞至觸發條件的輸入事件，提供您可以在 Lambda 函數的自訂邏輯中使用的其他內容。 作為安全最佳實務，請在應用程式用戶端上啟用重新整理字符輪換。 ------ #### [ Enable refresh token rotation (console) ] 下列程序會為您的應用程式用戶端開啟或關閉重新整理字符輪換。此程序需要現有的應用程式用戶端。若要進一步了解如何建立應用程式用戶端，請參閱 [使用應用程式用戶端的應用程式特定設定](user-pool-settings-client-apps.md)。 **啟用重新整理字符輪換** 1. 前往 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。如果出現提示，請輸入您的 AWS 登入資料。 1. 選擇 **User Pools** (使用者集區)。 1. 從清單中選擇現有的使用者集區。 1. 導覽至**應用程式用戶端**選單，然後選取現有的應用程式用戶端。 1. 從頁面**的應用程式用戶端資訊**區段中選取**編輯**。 1. 在**進階安全組態**下，找到**啟用重新整理字符輪換**選項。 1. 若要啟用輪換，請選取核取方塊。若要停用輪換，請取消選取核取方塊。 1. 在**重新整理權杖輪換寬限期**下，輸入您要設定為延遲的秒數，最多 60 秒，之後才會撤銷輪換的重新整理權杖。 ------ #### [ Enable refresh token rotation (API) ] 在 [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) 或 [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API 請求中設定重新整理權杖輪換。下列部分請求內文會開啟重新整理字符輪換，並將寬限期設定為 10 秒。 ``` "RefreshTokenRotation" : { "Feature" : "ENABLED, "RetryGracePeriodSeconds" : 10 } ``` ------ ## API 和 SDK 字符重新整理 有兩種方式可以使用重新整理權杖，透過使用者集區 API 取得新的 ID 和存取權杖，取決於重新整理權杖輪換是否作用中。在重新整理字符輪換作用中的應用程式用戶端中，使用 [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) API 操作。在未重新整理字符輪換的應用程式用戶端中，使用 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 或 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 操作`REFRESH_TOKEN_AUTH`的流程。 **注意** 使用者可以在[受管登入](cognito-user-pools-managed-login.md)或您使用 AWS SDKs 和 Amazon Cognito API 操作建置的自訂應用程式中，使用使用者集區進行身分驗證。`REFRESH_TOKEN_AUTH` 流程 和 `GetTokensFromRefreshToken`可以為受管登入使用者完成權杖重新整理。自訂應用程式中的字符重新整理不會影響受管登入工作階段。這些工作階段是在瀏覽器 Cookie 中設定，有效期為一小時。`GetTokensFromRefreshToken` 回應會發出新的 ID、存取權和選擇性重新整理權杖，但不會續約受管登入工作階段 Cookie。 `REFRESH_TOKEN_AUTH` 在啟用重新整理字符輪換的應用程式用戶端中無法使用 。 ------ #### [ GetTokensFromRefreshToken ] [GetTokensFromRefreshToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetTokensFromRefreshToken.html) 會從您使用重新整理權杖授權的請求傳回新的 ID、存取和重新整理權杖。以下是 的範例請求內文`GetTokensFromRefreshToken`。您可以在請求此操作時，將用戶端中繼資料提交至 Lambda 觸發程序。 ``` { "RefreshToken": "eyJjd123abcEXAMPLE", "ClientId": "1example23456789", "ClientSecret": "myappclientsecret123abc", "ClientMetadata": { "MyMetadataKey" : "MyMetadataValue" }, } ``` ------ #### [ AdminInitiateAuth/InitiateAuth ] 若要在重新整理權杖輪換非作用中時使用重新整理權杖，請使用 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 或 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 操作。為 `AuthFlow` 參數傳遞 `REFRESH_TOKEN_AUTH`。在 `AuthFlow` 的 `AuthParameters` 屬性中，將使用者的重新整理權杖作為 `"REFRESH_TOKEN"` 的值傳遞。在您的 API 請求通過所有挑戰後，Amazon Cognito 會傳回新的 ID 權杖和存取權杖。 以下是使用 `InitiateAuth`或 `AdminInitiateAuth` API 進行權杖重新整理的範例請求內文。 ``` { "AuthFlow": "REFRESH_TOKEN_AUTH", "ClientId": "1example23456789", "UserPoolId": "us-west-2_EXAMPLE", "AuthParameters": { "REFRESH_TOKEN": "eyJjd123abcEXAMPLE", "SECRET_HASH": "kT5acwCVrbD6JexhW3EQwnRSe6fLuPTRkEQ50athqv8=" } } ``` ------ ## OAuth 權杖重新整理 您也可以將重新整理權杖提交至已設定網域的使用者集區中的 [權杖端點](token-endpoint.md)。在請求內文中，包含 `refresh_token` 作為 `grant_type` 的值以及您的使用者重新整理權杖作為 `refresh_token` 的值。 對字符端點的請求可在重新整理字符輪換作用中以及處於非作用中狀態的應用程式用戶端中使用。當重新整理字符輪換作用中時，字符端點會傳回新的重新整理字符。 以下是具有重新整理字符的範例請求。 ``` POST /oauth2/token HTTP/1.1 Host: auth.example.com Content-Type: application/x-www-form-urlencoded Authorization: Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw Content-Length: ** client_id=1example23456789&grant_type=refresh_token&refresh_token=eyJjd123abcEXAMPLE ``` ## 撤銷重新整理權杖 您可以撤銷屬於使用者的重新整理權杖。如需撤銷權杖的詳細資訊，請參閱[使用字符撤銷結束使用者工作階段](token-revocation.md)。 **注意** 若撤銷重新整理權杖，將會一併撤銷 Amazon Cognito 從具有該權杖的重新整理請求中發出的所有 ID 和存取權杖。 若要將使用者登出所有目前的登入工作階段，請使用 [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) 或 [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API 請求撤銷其所有字符。使用者登出後，會產生下列影響。 + 使用者的重新整理權杖無法為使用者取得新權杖。 + 使用者的存取權杖無法提出權杖授權 API 請求。 + 使用者必須重新驗證才能取得新權杖。由於受管登入工作階段 Cookie 不會自動過期，因此您的使用者可以使用工作階段 Cookie 重新驗證，而不需要額外的登入資料提示。登出受管登入使用者後，將其重新導向至 [登出端點](logout-endpoint.md)，Amazon Cognito 會在其中清除其工作階段 Cookie。 使用重新整理權杖就可以在應用程式中長時間保留使用者的工作階段。隨著時間的推移，您的使用者可能會想要取消授權一些已使用重新整理字符保持登入的應用程式。若要從單一工作階段登出您的使用者，請撤銷其重新整理權杖。當您的使用者想要將自己登出所有已驗證的工作階段時，請產生 [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) API 請求。您的應用程式可向您的使用者顯示**從所有裝置登出**這類選項。`GlobalSignOut` 可接受使用者的 valid–unaltered、unexpired、not-revoked–access 權杖。由於此 API 是權杖授權，因此使用者無法用它來啟動另一位使用者的登出。 不過，您可以產生 [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) API 請求，授權 使用您的 AWS 登入資料從其所有裝置登出任何使用者。管理員應用程式必須使用 AWS 開發人員登入資料呼叫此 API 操作，並傳遞使用者集區 ID 和使用者的使用者名稱做為參數。`AdminUserGlobalSignOut`API 可以將使用者集區中的任何使用者登出。 如需您可以使用 AWS 登入資料或使用者的存取字符授權之請求的詳細資訊，請參閱 [依授權模型分組的 API 操作清單](authentication-flows-public-server-side.md#user-pool-apis-auth-unauth)。 # 使用字符撤銷結束使用者工作階段 您可以使用下列方法撤銷重新整理字符和最終使用者工作階段。撤銷重新整理權杖時，先前該重新整理權杖發行的所有存取權杖都會無效。發行給使用者的其他重新整理權杖不受影響。 **RevokeToken 操作** [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) 會撤銷指定重新整理字符的所有存取字符，包括互動式登入的初始存取字符。此操作不會影響任何使用者的其他重新整理字符，或那些其他重新整理字符的 ID 和存取字符子系。 **撤銷端點** [撤銷端點](revocation-endpoint.md)會撤銷指定的重新整理權杖，以及重新整理權杖產生的所有 ID 和存取權杖。此端點也會從互動式登入撤銷初始存取權杖。此端點的請求不會影響任何使用者的其他重新整理字符，或那些其他重新整理字符的 ID 和存取字符子系。 **GlobalSignOut 操作** [GlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html) 是使用者使用存取權杖授權的自助式操作。此操作會撤銷所有請求使用者的重新整理、ID 和存取權杖。 **AdminUserGlobalSignOut 操作** [AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html) 是管理員使用 IAM 登入資料授權的伺服器端操作。此操作會撤銷所有目標使用者的重新整理、ID 和存取權杖。 **撤銷權杖的須知事項** + 撤銷重新整理權杖的請求中必須包含用來取得該權杖的用戶端 ID。 + 使用者集區 JWTs會與建立字符時指派的簽章和過期時間獨立。撤銷的權杖不能與任何需要權杖的 Amazon Cognito API 呼叫搭配使用。但如果使用驗證權杖簽章和過期時間的任何 JWT 程式庫進行驗證，則已撤銷的權杖仍有效。 + 建立新使用者集區用戶端時，撤銷權杖功能會預設為啟用。 + 您只能在啟用字符撤銷的應用程式用戶端中撤銷重新整理字符。 + 啟用撤銷權杖功能後，新宣告會新增到 Amazon Cognito JSON Web 權杖。存取權杖和 ID 權杖中會新增 `origin_jti` 和 `jti` 宣告。這些宣告會增加應用程式用戶端存取和 ID 權杖的大小。 + 當您在先前啟用的應用程式用戶端中停用字符撤銷時，撤銷的字符不會再次變為作用中。 + 當您[停用使用者帳戶 ](how-to-manage-user-accounts.md#manage-user-accounts-enable-disable)（撤銷重新整理和存取權杖） 時，如果您再次啟用使用者帳戶，則撤銷的權杖不會變成作用中。 + 當您使用 AWS CLI、 AWS 管理主控台或 API 建立新的使用者集區用戶端時 AWS ，預設會啟用字符撤銷。 ## 啟用撤銷權杖功能 您必須先啟用撤銷權杖功能，才能為現有使用者集區用戶端撤銷權杖。您可以使用 或 AWS API 為現有的使用者集區用戶端 AWS CLI 啟用字符撤銷。若要執行此操作，請呼叫 `aws cognito-idp describe-user-pool-client` CLI 命令或 `DescribeUserPoolClient` API 操作，以從您的應用程式用戶端檢索當前設置。然後呼叫 `aws cognito-idp update-user-pool-client` CLI 命令或 `UpdateUserPoolClient` API 操作。包含來自您應用程式用戶端中的當前設定，並將 `EnableTokenRevocation` 參數設為 `true`。 若要建立或修改已啟用 Amazon Cognito API 或 AWS SDK 的字符撤銷的應用程式用戶端，請在 [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) 或 [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API 請求中包含下列參數。 ``` "EnableTokenRevocation": true ``` 若要在 Amazon Cognito 主控台中設定權杖撤銷，請從使用者集區中的應用程式用戶端功能表中選取**應用程式用戶端**。選取**應用程式用戶端資訊**中的**編輯**按鈕，並在**進階組態**下啟用或停用字符撤銷。 ## 撤銷權杖 您可以使用 [RevokeToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RevokeToken.html) API 請求撤銷重新整理權杖，例如使用 `[aws cognito-idp revoke-token](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/revoke-token.html)` CLI 命令。您也可以使用 [撤銷端點](revocation-endpoint.md) 撤銷權杖。此端點在您將網域新增至使用者集區之後才能使用。您可以在 Amazon Cognito 託管網域或您自己的自訂網域上，使用撤銷端點功能。 以下是 `RevokeToken` API 請求範例的內文： ``` { "ClientId": "1example23456789", "ClientSecret": "abcdef123456789ghijklexample", "Token": "eyJjdHkiOiJKV1QiEXAMPLE" } ``` 以下是對具有自訂網域的使用者集區的 `/oauth2/revoke` 端點提出的範例 cURL 請求。 ``` curl --location 'auth.mydomain.com/oauth2/revoke' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic Base64Encode(client_id:client_secret)' \ --data-urlencode 'token=abcdef123456789ghijklexample' \ --data-urlencode 'client_id=1example23456789' ``` `RevokeToken` 操作和 `/oauth2/revoke` 端點都不需要額外授權，除非您的應用程式用戶端有用戶端密碼。 # 驗證 JSON Web 字符 JSON Web 字符 JWTs) 可以輕鬆解碼、讀取和修改。修改後的存取權杖會產生權限提升的風險。修改後的 ID 字符會產生模擬的風險。您的應用程式信任您的使用者集區做為權杖發行者，但如果使用者在傳輸中攔截權杖該怎麼辦？ 您必須確保您的應用程式收到與 Amazon Cognito 發行相同的字符。 Amazon Cognito 會發出權杖，這些權杖使用 OpenID Connect (OIDC) 規格的一些完整性和機密性功能。使用者集區字符指出過期時間、發行者和數位簽章等物件的有效性。簽章是 `.`分隔 JWT 的第三個和最後一個區段，是權杖驗證的關鍵元件。惡意使用者可以修改權杖，但如果您的應用程式擷取公有金鑰並比較簽章，則不相符。從 OIDC 身分驗證處理 JWTs 的任何應用程式，都必須在每次登入時執行此驗證操作。 在此頁面上，我們會針對 JWTs 的驗證提出一些一般和特定建議。應用程式開發涵蓋各種程式設計語言和平台。由於 Amazon Cognito 實作的 OIDC 足以接近公有規格，因此您選擇的開發人員環境中任何信譽良好的 JWT 程式庫都可以處理您的驗證需求。 這些步驟描述有關驗證使用者集區 JSON web 權杖 (JWT)。 **Topics** + [先決條件](#amazon-cognito-user-pools-using-tokens-prerequisites) + [使用 aws-jwt-verify 驗證權杖](#amazon-cognito-user-pools-using-tokens-aws-jwt-verify) + [了解和檢查權杖](#amazon-cognito-user-pools-using-tokens-manually-inspect) ## 先決條件 您的程式庫、軟體開發套件或軟體架構可能已處理本節的任務。 AWS SDKs為應用程式中的 Amazon Cognito 使用者集區字符處理和管理提供工具。 AWS Amplify 包含擷取和重新整理 Amazon Cognito 字符的 函數。 如需詳細資訊，請參閱下列頁面。 + [將 Amazon Cognito 身分驗證和授權與 Web 和行動應用程式整合](cognito-integrate-apps.md) + [使用 AWS SDKs的 Amazon Cognito 身分提供者程式碼範例](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html) + *Amplify 開發人員中心*中的[進階工作流程](https://docs.amplify.aws/lib/auth/advanced/q/platform/js/#retrieve-jwt-tokens) 許多程式庫可用於解碼和驗證 JSON Web 權杖 (JWT)。如果您想手動處理伺服器端 API 處理的權杖，又或者您使用的是其他程式設計語言，那麼這些程式庫就很實用。請參閱[可搭配 JWT 權杖使用的 OpenID Foundation 程式庫清單](http://openid.net/developers/jwt/)。 ## 使用 aws-jwt-verify 驗證權杖 在 Node.js 應用程式中， AWS 建議程式[aws-jwt-verify庫](https://github.com/awslabs/aws-jwt-verify)驗證使用者傳遞至應用程式的字符中的參數。使用 `aws-jwt-verify` 時，您可以使用您要驗證一或多個使用者集區的宣告值填入 `CognitoJwtVerifier`。它可以檢查的一些值包括以下內容。 + 該存取或 ID 權杖的格式正確或未過期，並具有有效的簽章。 + 該存取權杖來自[正確的使用者集區和應用程式用戶端](https://github.com/awslabs/aws-jwt-verify#verifying-jwts-from-amazon-cognito)。 + 該存取權杖宣告包含[正確的 OAuth 2.0 範圍](https://github.com/awslabs/aws-jwt-verify#checking-scope)。 + 簽署您的存取和 ID 權杖的金鑰[符合來自使用者集區 *JWKS URI* 中的簽署金鑰 `kid`](https://github.com/awslabs/aws-jwt-verify#the-jwks-cache)。 JWKS URI 包含有關簽署使用者權杖之私有金鑰的公開資訊。您可以在以下位置找到使用者集區的 JWKS URI：`https://cognito-idp..amazonaws.com//.well-known/jwks.json`。 如需可在 Node.js 應用程式或 AWS Lambda 授權方中使用的詳細資訊和範例程式碼，請參閱 GitHub 上的 [https://github.com/awslabs/aws-jwt-verify](https://github.com/awslabs/aws-jwt-verify)。 ## 了解和檢查權杖 在將權杖檢查與應用程式整合之前，請考慮 Amazon Cognito 如何組合 JWT。從使用者集區擷取範例權杖。對它們進行詳細解碼和檢查以了解它們的特徵，並確定您要驗證的內容和時間。例如，您可能想在一種情況下檢查群組成員資格，而在另一種情況下檢查範圍。 以下區段說明在準備應用程式時，手動檢查 Amazon Cognito JWT 的程序。 ### 確認 JWT 的結構。 JSON Web 權杖 (JWT) 包含三個區段，它們之間有一個 `.` (點號) 分隔符號。 **標頭** Amazon Cognito 用來簽署權杖的金鑰 ID (`kid`) 和 RSA 演算法 (`alg`)。Amazon Cognito 使用 `RS256` 的 `alg` 簽署權杖。`kid` 是使用者集區所持有之 2048 位元 RSA 私有簽署金鑰的截斷參考。 **酬載** 權杖宣告。在 ID 權杖中，宣告包括使用者屬性和有關使用者集區 (`iss`) 和應用程式用戶端 (`aud`) 的資訊。在存取權杖中，承載包括範圍、群組成員資格、您的使用者集區為 `iss`，以及您的應用程式用戶端為 `client_id`。 **簽章** 簽章無法像標頭和承載一樣分解 base64url。它是從您可在 JWKS URI 中觀察到的簽署金鑰和參數衍生出來的 RSA256 識別符。 標頭和承載是 base64url 編碼的 JSON。您可以透過解碼為起始字元 `{` 的開頭字元 `eyJ` 以識別它們。如果您的使用者向您的應用程式提供 base64url 編碼的 JWT，且其格式不是 `[JSON Header].[JSON Payload].[Signature]`，則它不是有效的 Amazon Cognito 字符，您可以將其捨棄。 下列範例應用程式會使用 驗證使用者集區字符`aws-jwt-verify`。 ``` // cognito-verify.js // Usage example: node cognito-verify.js eyJra789ghiEXAMPLE const { CognitoJwtVerifier } = require('aws-jwt-verify'); // Replace with your Amazon Cognito user pool ID const userPoolId = 'us-west-2_EXAMPLE'; async function verifyJWT(token) { try { const verifier = CognitoJwtVerifier.create({ userPoolId, tokenUse: 'access', // or 'id' for ID tokens clientId: '1example23456789', // Optional, only if you need to verify the token audience }); const payload = await verifier.verify(token); console.log('Decoded JWT:', payload); } catch (err) { console.error('Error verifying JWT:', err); } } // Example usage if (process.argv.length < 3) { console.error('Please provide a JWT token as an argument.'); process.exit(1); } const MyToken = process.argv[2]; verifyJWT(MyToken); ``` ### 驗證 JWT JWT 簽章是標頭和酬載的雜湊組合。Amazon Cognito 會為每個使用者集區產生兩組 RSA 加密金鑰對。一個私有金鑰簽署存取權杖，另一個簽署 ID 權杖。 **驗證 JWT 權杖的簽章** 1. 解碼 ID 權杖。 OpenID Foundation 也會[提供可搭配 JWT 權杖使用的程式庫清單](http://openid.net/developers/jwt/)。 您也可以使用 AWS Lambda 解碼使用者集區 JWTs。如需詳細資訊，請參閱[使用 解碼和驗證 Amazon Cognito JWT 權杖 AWS Lambda](https://github.com/awslabs/aws-support-tools/tree/master/Cognito/decode-verify-jwt)。 1. 比較本機金鑰 ID (`kid`) 與公有 `kid`。 1. 下載並存放對應至您的使用者集區的公開 JSON Web Key (JWK)。JSON Web Key Set (JWKS) 中會提供這個金鑰。針對您的環境建構以下 `jwks_uri` URI 即可找到它： ``` https://cognito-idp..amazonaws.com//.well-known/jwks.json ``` 如需 JWK 和 JWK Set 的詳細資訊，請參閱 [JSON Web Key (JWK)](https://tools.ietf.org/html/rfc7517)。 **注意** Amazon Cognito 可能會輪換使用者集區中的簽署金鑰。最佳做法是在應用程式中快取公有金鑰，使用 `kid` 做為快取金鑰，並定期重新整理快取。將應用程式所收到權杖中的 `kid` 與您的快取進行比較。 如果您收到的權杖具有正確的發行者但 `kid` 不同，則 Amazon Cognito 可能已輪換簽署金鑰。從您的使用者集區 `jwks_uri` 端點重新整理快取。 這是範本 `jwks.json` 檔案： ``` { "keys": [{ "kid": "1234example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "1234567890", "use": "sig" }, { "kid": "5678example=", "alg": "RS256", "kty": "RSA", "e": "AQAB", "n": "987654321", "use": "sig" }] } ``` **金鑰 ID (`kid`)** `kid` 是指出在保護權杖之 JSON Web Signature (JWS) 安全時所使用金鑰的提示。 **演算法 (`alg`)** `alg` 標頭參數代表用來保護 ID 權杖安全的加密演算法。使用者集區是使用 RS256 演算法，即採用 SHA-256 的 RSA 簽章。如需 RSA 的詳細資訊，請參閱 [RSA 加密法](https://tools.ietf.org/html/rfc3447)。 **金鑰類型 (`kty`)** `kty` 參數會識別搭配金鑰 (本範例中的金鑰為 "RSA") 的加密演算法系列。 **RSA 指數 (`e`)** 這個 `e` 參數包含 RSA 公開金鑰的指數值。它以 Base64urlUInt 編碼值表示。 **RSA 模數 (`n`)** 這個 `n` 參數包含 RSA 公開金鑰的模數值。它以 Base64urlUInt 編碼值表示。 **用途 (`use`)** 這個 `use` 參數描述公開金鑰的用途。在這個範例中，`use` 值 `sig` 代表簽章。 1. 搜尋符合您的 JWT 中 `kid` 之 `kid` 的公有 JSON Web 金鑰。 ### 驗證宣告 **驗證 JWT 宣告** 1. 利用下列其中一種方法確認權杖尚未過期。 1. 解碼權杖，並將 `exp` 宣告與目前時間進行比較。 1. 如果您的存取權杖包含 `aws.cognito.signin.user.admin` 宣告，請傳送請求至 API (如 [getUser](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html))。如果您的權杖已過期，那麼您[使用存取權杖進行授權](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html#user-pool-apis-auth-unauth)的 API 請求將會傳回錯誤。 1. 在對 [userInfo 端點](userinfo-endpoint.md) 提出的請求中顯示存取權杖。如果您的權杖已過期，您的請求將會傳回錯誤。 1. 在 ID 權杖中的 `aud` 宣告和在存取權杖中的 `client_id` 宣告應符合在 Amazon Cognito 使用者集區建立的應用程式用戶端 ID。 1. 發行者 (`iss`) 宣告應該符合您的使用者集區。例如，在 `us-east-1` 區域中建立的使用者集區會有以下 `iss` 值： `https://cognito-idp.us-east-1.amazonaws.com/`. 1. 檢查 `token_use`宣告。 + 如果您在 Web API 操作中只接受存取權杖，其值必須是 `access`。 + 如果您只使用 ID 權杖，其值必須是 `id`。 + 如果是同時使用 ID 權杖和存取權杖，`token_use` 宣告必須是 `id` 或 `access`。 您現在可以信任權杖內部的宣告。 # 管理使用者集區字符過期和快取 每次您想要獲取新的 JSON Web 權杖 (JWT) 時，您的應用程式都必須成功完成以下請求之一。 + 從[權杖端點](token-endpoint.md)請求用戶端憑證或授權碼[授與](https://www.rfc-editor.org/rfc/rfc6749#section-1.3)。 + 從受管登入頁面請求隱含授予。 + 在 Amazon Cognito API 請求 (例如 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)) 中驗證本機使用者。 您可以設定使用者集區，將權杖設定為在幾分鐘、幾小時或幾天後過期。為了確保應用程式的效能和可用性，請在字符生命週期的大約 75% 內使用 Amazon Cognito 字符，然後才擷取新的字符。您為應用程式建立的快取解決方案可讓權杖保持可用，並在請求率過高時防止 Amazon Cognito 拒絕請求。用戶端應用程式必須將權杖儲存在記憶體快取中。伺服器端應用程式可以新增加密的快取機制來儲存權杖。 當您的使用者集區產生大量的使用者或機器對機器活動時，您可能會遇到 Amazon Cognito 針對您可發出的權杖請求數量設定的限制。為了減少對 Amazon Cognito 端點發出的請求數量，您可以安全地存放和重複使用驗證資料，或實施指數退避和重試。 驗證資料來自兩種端點類別。Amazon Cognito [OAuth 2.0 端點](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-userpools-server-contract-reference.html)包含權杖端點，該端點服務用戶端憑證和受管登入授權碼請求。[服務端點](https://docs.aws.amazon.com/general/latest/gr/cognito_identity.html#cognito_identity_your_user_pools_region)會回答使用者集區 API 請求，如 `InitiateAuth` 和 `RespondToAuthChallenge`。每種類型的請求都有自己的限制。如需限制的詳細資訊，請參閱 [Amazon Cognito 的配額](quotas.md)。 ## 使用 Amazon API Gateway 快取機器對機器存取權杖 透過 API Gateway 權杖快取，您的應用程式可以擴展以回應大於 Amazon Cognito OAuth 端點預設請求率配額的事件。 ![\[維護 M2M 存取字符快取的 API Gateway 圖表。API 代理會處理字符請求，如果快取字符已經有效，則傳回快取字符。\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/images/user-pools-m2m-caching.png) 您可以快取存取權杖，以便您的應用僅在快取權杖過期時請求新的存取權杖。否則，您的快取端點會從快取傳回權杖。如此可防止額外呼叫 Amazon Cognito API 端點。當您使用 Amazon API Gateway 作為 [權杖端點](token-endpoint.md) 的代理時，您的 API 會回應大部分請求，否則請求會佔用配額，以避免因為速率限制導致請求失敗。 以下 API Gateway 解決方案提供低延遲、低程式碼/無程式碼的權杖快取實作。API Gateway API 在傳輸過程中進行加密，並可選擇是否在靜態時加密。API Gateway 快取是 OAuth 2.0 的[用戶端憑證授與](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)的理想選擇，一種頻繁的大容量授與類型，可產生存取權杖以授權機器對機器和微服務工作階段。如果流量激增導致您的微服務水平擴展，您可以在超過使用者集區或應用程式用戶端 AWS 請求速率限制的磁碟區中使用相同的用戶端登入資料，最終會有許多系統。為了保持應用程式可用性和低延遲，快取解決方案是在這種情況下的最佳做法。 在此解決方案中，您可以在 API 中定義快取，以為要在應用程式中請求的每個 OAuth 範圍和應用程式用戶端組合儲存單獨的存取權杖。當您的應用程式發出符合快取金鑰的請求時，您的 API 會以 Amazon Cognito 對符合快取金鑰的第一個請求發出的存取權杖進行回應。當您的快取金鑰持續時間過期時，您的 API 將請求轉發到權杖端點並快取新的存取權杖。 **注意** 您的快取金鑰持續時間必須短於應用程式用戶端的存取權杖持續時間。 快取金鑰是您在請求內文的 `scope` 參數中請求的 OAuth 範圍和請求中的 `Authorization`標頭的組合。`Authorization` 標題包含您的應用程式用戶端 ID 和用戶端密碼。您無需在應用程式中實作其他邏輯即可實現此解決方案。您只能更新組態以變更使用者集區權杖端點的路徑。 您也可以使用 [ElastiCache (Redis OSS)](https://docs.aws.amazon.com/elasticache/index.html) 實作權杖快取。如需使用 AWS Identity and Access Management (IAM) 政策進行精細控制，請考慮 [Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/authentication-and-access-control.html#authentication) 快取。 **注意** API Gateway 中的快取需支付額外費用。[如需詳細資訊，請參閱定價。](https://aws.amazon.com/api-gateway/pricing) **使用 API Gateway 設定快取代理** 1. 開啟 [API Gateway 主控台](https://console.aws.amazon.com/apigateway/main/apis)並建立 REST API。 1. 在 **Resources** (資源) 中，建立 POST 方法。 1. 選擇 HTTP **Integration type** (整合類型)。 1. 選擇 **Use HTTP proxy integration** (使用 HTTP 代理整合)。 1. 輸入 `https:///oauth2/token` 的 **Endpoint URL** (端點 URL)。 1. 在 **Resources** (資源) 中，設定快取金鑰。 1. 編輯您 POST 方法的 **Method request** (方法請求)。 **注意** 此方法請求驗證用於字符請求中的`client_secret_basic`授權，其中用戶端秘密在`Authorization`請求標頭中編碼。為了驗證`client_secret_post`授權中的 JSON 請求內文，請改為建立需要 [client\$1secret](token-endpoint.md#post-token-request-parameters-in-body) 存在[的資料模型](https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings-models.html)。在此模型中，您的**請求驗證程式**應該**驗證內文、查詢字串參數和標頭**。 1. 設定 方法 **請求驗證器**以**驗證查詢字串參數和標頭**。如需請求驗證的詳細資訊，請參閱《*Amazon API Gateway 開發人員指南*》中的[請求驗證](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-method-request-validation.html)。 1. 設定您的 `scope` 參數和 `Authorization` 標題作為您的快取金鑰。 1. 將查詢字串新增至 **URL 查詢字串參數**。輸入查詢字串**名稱** `scope`，然後選取**必要**和**快取**。 1. 將標頭新增至 **HTTP 請求標頭**。輸入 的請求標頭**名稱**`Authorization`，然後選取**必要**和**快取**。 1. 在 **Stages** (階段) 中，設定快取。 1. 選擇您要修改的階段，然後選擇從**階段詳細資訊****中編輯**。 1. **在其他設定**、**快取設定**下，開啟**佈建 API 快取**選項。 1. 選擇 **Cache capacity** (快取容量)。更高的快取容量可改善效能，但需額外付費。 1. 清除 **需要授權** 核取方塊。選取**繼續**。 1. API Gateway 只會將快取政策套用至階段層級的 GET 方法。您必須將快取政策覆寫套用至 POST 方法。 展開您設定的階段，然後選取 `POST`方法。若要為 方法建立快取設定，請選擇**建立覆寫**。 1. 啟用**啟用方法快取**選項。 1. 輸入 3600 秒的****快取time-to-live (TTL)****。選擇**儲存**。 1. 在 **Stages** (階段) 中，記下 **Invoke URL** (叫用 URL)。 1. 更新您的應用程式以將權杖請求 POST 到 API 的 **Invoke URL** (叫用網址)，而不是使用者集區的 `/oauth2/token` 端點。