本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 刷新令牌
您可以使用刷新令牌来检索新的 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 令牌中会添加新的声明。`origin_jti` 和 `jti` 声明已添加到访问和 ID 令牌中。这些索赔增加了索赔的规模 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 请求中配置刷新令牌轮换。以下部分请求正文用于开启刷新令牌轮换并将宽限期设置为十秒。
```
"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 中设置的，有效期为 1 小时。`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 和访问令牌。
要让用户退出当前所有登录会话，请使用或 API 请求撤消其所有令牌。[GlobalSignOut[AdminUserGlobalSignOut](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUserGlobalSignOut.html)](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GlobalSignOut.html)注销用户后，会发生以下影响。
+ 用户的刷新令牌无法获取该用户的新令牌。
+ 用户的访问令牌无法发出经过令牌授权的 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` 接受用户的有效（即未更改、未过期、未撤销的）访问令牌。由于此 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)。