刷新令牌 - Amazon Cognito
刷新令牌刷新令牌轮换API 和 SDK 令牌刷新OAuth 令牌刷新撤销刷新令牌
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

刷新令牌

您可以使用刷新令牌来检索新的 ID 令牌和访问令牌。默认情况下，刷新令牌会在您的应用程序用户登录用户池的 30 天后过期。当您为用户池创建应用程序时，您可以将应用程序的刷新令牌到期时间设置为介于 60 分钟和 10 年之间的任何值。

使用刷新令牌获取新的访问权限和身份令牌

Amazon Cognito 会在通过托管登录的授权代码流程以及 API 操作或 SDK 方法成功完成身份验证后，颁发刷新令牌。刷新令牌会返回新的 ID 和访问令牌，以及可选的新刷新令牌。可以通过以下方式使用刷新令牌。

GetTokensFromRefreshToken

GetTokensFromRefreshToken API 操作从有效的刷新令牌中颁发新的 ID 令牌和访问令牌。如果您启用了刷新令牌轮换，则还会获得新的刷新令牌。

InitiateAuth 和 AdminitiateAuth

AdminInitiateAuth 或 InitiateAuth API 操作包括 REFRESH_TOKEN_AUTH 身份验证流程。在此流程中，您可以传递刷新令牌，并获得新的 ID 令牌和访问令牌。在启用刷新令牌轮换的应用程序客户端中，您无法使用 REFRESH_TOKEN_AUTH 进行身份验证。

OAuth 令牌端点

在具有域的用户池中，令牌端点支持 refresh_token 授予类型，可通过一个有效的刷新令牌颁发新的 ID 令牌、访问令牌，并（通过刷新令牌轮换）选择性地颁发刷新令牌。

刷新令牌轮换

您可以选择在应用程序客户端中配置刷新令牌轮换。通过刷新令牌轮换，您的客户端在每次刷新令牌时都会使原始刷新令牌失效，并颁发一个新的刷新令牌。启用此设置后，所有形式的令牌刷新请求成功后，都会返回一个新的 ID 令牌、访问令牌和刷新令牌。禁用此设置后，令牌刷新请求仅返回新的访问令牌和 ID 令牌，并且原始刷新令牌仍然有效。新的刷新令牌的有效期为原始刷新令牌的剩余有效时间。可以将应用程序客户端配置为轮换刷新令牌或保留使用原始刷新令牌。为了支持短暂时间内的重试操作，还可以为原始刷新令牌配置最长 60 秒的宽限期。

有关刷新令牌轮换的需知信息

  • 启用刷新令牌轮换后，您的用户池的 JSON Web 令牌中会添加新的声明。origin_jti 和 jti 声明已添加到访问和 ID 令牌中。这些声明会增加 JWT 的大小。

  • 刷新令牌轮换与 REFRESH_TOKEN_AUTH 身份验证流程不兼容。要实现刷新令牌轮换，您必须在应用程序客户端中禁用此身份验证流程，并将您的应用程序设计为通过 GetTokensFromRefreshToken API 操作或等效的 SDK 方法来提交令牌刷新请求。

  • 当刷新令牌轮换未启用时，您可以使用 GetTokensFromRefreshToken 或 REFRESH_TOKEN_AUTH 来完成令牌刷新请求。

  • 当您的用户池中启用了设备记忆功能时，您必须在 GetTokensFromRefreshToken 请求中提供设备密钥。如果您的用户没有您的应用程序在初始身份验证请求中提交的已确认设备密钥，Amazon Cognito 会颁发一个新的密钥。在此置下进行令牌刷新时，无论您是在 AuthParameters 中指定了设备密钥，还是在身份验证响应中收到了新的设备密钥，都必须提供该设备密钥。

  • 可以在 GetTokensFromRefreshToken 请求中将 ClientMetadata 传递给令牌生成前 Lambda 触发器。这些数据将传递至触发器的输入事件，并提供额外上下文信息，可用于您的 Lambda 函数的自定义逻辑。

作为一项安全最佳实践，请在应用程序客户端启用刷新令牌轮换。

Enable refresh token rotation (console)

以下过程可用于为您的应用程序客户端打开或关闭刷新令牌轮换。此过程需要一个现有的应用程序客户端。要了解有关创建应用程序客户端的更多信息，请参阅特定于应用程序的应用程序客户端设置。

启用刷新令牌轮换

  1. 转到 Amazon Cognito 控制台。如果出现提示，请输入 Amazon 凭证。

  2. 选择用户池。

  3. 从列表中选择现有用户池。

  4. 导航到应用程序客户端菜单，然后选择一个现有的应用程序客户端。

  5. 从页面的应用程序客户端信息部分选择编辑。

  6. 在高级安全配置下，找到启用刷新令牌轮换选项。

  7. 要启用轮换，请选中该复选框。要禁用轮换，请取消选中该复选框。

  8. 在刷新令牌轮换宽限期下，输入要设置为撤销轮换刷新令牌之前的延迟时间（最多 60 秒）。

Enable refresh token rotation (API)

通过 CreateUserPoolClient 或 UpdateUserPoolClient API 请求来配置刷新令牌轮换。以下部分请求正文用于开启刷新令牌轮换并将宽限期设置为十秒。

"RefreshTokenRotation" : {
   "Feature" : "ENABLED,
   "RetryGracePeriodSeconds" : 10
}

API 和 SDK 令牌刷新

可通过两种方法使用刷新令牌通过用户池 API 获取新 ID 令牌和访问令牌，具体取决于刷新令牌轮换是否已启用。在启用刷新令牌轮换的应用程序客户端中，请使用 GetTokensFromRefreshToken API 操作。在未启用刷新令牌轮换的应用程序客户端中，请使用 AdminInitiateAuth 或 InitiateAuth API 操作的 REFRESH_TOKEN_AUTH 流程。

注意

用户可以通过托管登录，或通过您使用 Amazon SDK 和 Amazon Cognito API 操作构建的自定义应用程序，使用用户池进行身份验证。REFRESH_TOKEN_AUTH 流程和 GetTokensFromRefreshToken 都可以为托管登录用户完成令牌刷新。自定义应用程序中的令牌刷新不会影响托管登录会话。这些会话是在浏览器 Cookie 中设置的，有效期为 1 小时。GetTokensFromRefreshToken 响应会发出新的 ID 令牌、访问令牌、可选刷新令牌，但不会续订托管登录会话 Cookie。

REFRESH_TOKEN_AUTH 在启用刷新令牌轮换的应用程序客户端中不可用。

GetTokensFromRefreshToken

GetTokensFromRefreshToken 会根据您使用刷新令牌授权的请求，返回新的 ID 令牌、访问令牌和刷新令牌。以下是 GetTokensFromRefreshToken 的一个请求正文示例。您可以通过此操作发起的请求，向 Lambda 触发器提交客户端元数据。

{
    "RefreshToken": "eyJjd123abcEXAMPLE",
    "ClientId": "1example23456789",
    "ClientSecret": "myappclientsecret123abc",
    "ClientMetadata": { 
      "MyMetadataKey" : "MyMetadataValue" 
   },
}
AdminInitiateAuth/InitiateAuth

要在刷新令牌轮换未启用时使用刷新令牌，请使用 AdminInitiateAuth 或 InitiateAuth 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 令牌刷新

您也可以将刷新令牌提交给用户池中您在其中配置了域的令牌端点。在请求正文中，加入 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

撤销刷新令牌

您可以撤销属于用户的刷新令牌。有关撤销令牌的更多信息，请参阅通过令牌撤销来结束用户会话。

注意

撤销刷新令牌将撤销 Amazon Cognito 从具有该令牌的刷新请求中发出的所有 ID 和访问令牌。

要将用户从当前的所有登录会话中注销，请使用 GlobalSignOut 或 AdminUserGlobalSignOut API 请求撤销其所有令牌。注销用户后，会发生以下影响。

  • 用户的刷新令牌无法获取该用户的新令牌。

  • 用户的访问令牌无法发出经过令牌授权的 API 请求。

  • 用户必须重新进行身份验证以获取新的令牌。由于托管登录会话 Cookie 不会自动过期，因此，用户可以使用会话 Cookie 重新进行身份验证，而无需额外提示输入凭证。注销托管登录用户后，会将这些用户重定向到注销端点，Amazon Cognito 将在其中清除用户的会话 Cookie。

使用刷新令牌，您可以将用户的会话长时间保留在您的应用程序中。随着时间推移，您的用户可能希望取消对他们使用刷新令牌保持登录状态的某些应用程序的授权。要将您的用户从单个会话注销，请撤销其刷新令牌。当您的用户想要从所有经过身份验证的会话中注销时，请生成 GlobalSignOut API 请求。应用程序可以为用户提供一个选择，如从所有设备注销。GlobalSignOut 接受用户的有效（即未更改、未过期、未撤销的）访问令牌。由于此 API 经过令牌授权，因此一个用户无法使用它来发起另一个用户的注销。

但是，您可以生成 AdminUserGlobalSignOut API 请求，而您将使用您的 Amazon 凭证授权该请求将任何用户从其所有设备注销。管理员应用程序必须通过 Amazon 开发人员凭证调用此 API 操作，并传递用户池 ID 和用户的用户名作为参数。AdminUserGlobalSignOut API 可以在用户池中注销任何用户。

有关可以使用 Amazon 凭证或用户的访问令牌进行授权的请求的更多信息，请参阅按授权模型分组的 API 操作列表。