本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 重新整理權杖
您可以使用重新整理權杖來擷取新的 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)。