刷新访问令牌

概述
刷新令牌轮换
获取刷新令牌
使用Refresh Token
1. 响应示例

概述

访问和 ID令牌是 JWT令牌，有效期仅在特定的时间内有效。当用户第一次尝试访问资源时、或者上一个访问令牌过期后，用户都需要一个新的访问令牌。

为了改善用户的体验，避免重复性认证或跳转，刷新令牌是一种特殊的令牌，用于获取后续的访问令牌。这将允许您拥有短期的访问令牌，长期的刷新令牌，而不必在每次到期时进行重复的认证。

作为用户初始身份验证和授权流程的一部分，您在获取访问令牌和/或 ID 令牌的同时，可以请求刷新令牌。但是，应用程序必须安全地存储刷新令牌，因为它们实际上允许了用户保持身份验证通过的状态。

尤其是对于本机应用程序等客户端（移动APP），持久刷新令牌有助于改善用户的身份验证体验。例如，电商类的应用，持久刷新令牌允许用户在完成初始设备授权后无需登录即可访问其购物业务。

对于持久刷新令牌（相对于刷新令牌轮换），每次客户端发出请求以将刷新令牌交换为新访问令牌时，都会返回相同的刷新令牌，直到刷新令牌生命周期到期。

关于令牌有效期的信息，包含硬编码的系统令牌有效期和可配置的令牌有效期。

但是，当使用持久刷新令牌时，公共客户端（例如基于浏览器的应用程序）具有更高的刷新令牌被破坏的风险。对于单页应用程序 (SPA) 等客户端，长期刷新令牌不适合，因为没有办法在浏览器中安全地存储持久刷新令牌并确保仅由预期应用程序访问。

通过轮换刷新令牌大大减少了这些威胁，刷新令牌轮换帮助公共客户端在每次使用后安全地轮换刷新令牌。对于刷新令牌轮换行为，每次客户端发出请求以将刷新令牌交换为新的访问令牌时，都会返回一个新的刷新令牌。刷新令牌轮换适用于 XAuth 中的 SPA、本机应用程序和 Web 应用程序。

刷新令牌轮换

刷新令牌轮换帮助公共客户端在每次使用后安全地轮换刷新令牌。在 XAuth中启用刷新令牌轮换行为后，每次客户端发出请求以将刷新令牌交换为新的访问令牌时，都会返回一个新的刷新令牌。

刷新令牌重用监测

当客户端想要更新访问令牌时，它会将刷新令牌与访问令牌请求一起发送到 /token 端点。 XAuth验证传入的刷新令牌并发出一组新令牌。新令牌一发出，XAuth就会使与初始请求一起传递给 /token 端点的刷新令牌失效。

如果先前使用的刷新令牌再次请求，授权服务器会自动检测刷新令牌的尝试重用行为。因此，XAuth会立即使最近发布的刷新令牌和自用户通过身份验证后发布的所有访问令牌失效。这可以保护您的应用程序免受令牌泄露和重放攻击。

刷新令牌的宽限期

令牌重用检测有时会影响用户体验。

例如，当网络连接较差的用户访问应用程序时，XAuth发布的新令牌可能无法到达客户端应用程序。因此，客户端可能希望重用刷新令牌以从 XAuth 获取新令牌。因此，当您配置刷新令牌轮换时，XAuth会提供一个宽限期。刷新令牌轮换后，前一个令牌在配置的时间内保持有效。

开始刷新令牌轮换

刷新令牌轮换行为是 SPA 的默认配置。

当您创建新 SPA 或更新现有 SPA 并选择刷新令牌作为允许的授权类型时，刷新令牌轮换将设置为默认值。

应用> 需要配置的SPA应用>基本配置>令牌轮换

令牌轮换宽限期的默认秒数设置为 30 秒。您可以将该值更改为 0 到 60 秒之间的任何数字。刷新令牌轮换后，之前的令牌在这段时间内保持有效，以允许客户端获取新令牌。

刷新令牌生命周期

刷新令牌生命周期通过授权服务器访问策略进行管理。授权服务器访问策略的刷新令牌生命周期 (refreshTokenLifetimeMinutes) 的默认值为 Unlimited，但如果未使用，则每 7 天过期一次。在 SPA 中使用刷新令牌时，请确保保持较短的刷新令牌生命周期以提高安全性。

获取刷新令牌

要获取刷新令牌，您需要向 XAuth授权服务器发送请求。唯一支持刷新令牌的流程是授权码流程和资源所有者密码流程。

这意味着以下授予类型和范围的组合在发送到 /token 端点时，将返回刷新令牌：

注意：Scope参数值的最大长度为 1024 个字符。

Grant Type	Scope
`authorization_code`	`offline_access` (参考注意)
`refresh_token`	`offline_access`
`password`	`offline_access`

注意：授权码流的独特之处在于，必须将 ` offline_access `范围作为对 /authorize 端点的代码请求的一部分进行请求，而不是发送到 /token 端点的请求。

是否启用持久刷新令牌或刷新令牌轮换行为取决于您的应用程序类型。当您选择刷新令牌作为允许的授权类型时，SPA 使用刷新令牌轮换作为默认行为。本机应用程序和 Web 应用程序默认使用持久刷新令牌。

授权码模式获取Refresh Token

Step1，获取授权码

使用授权服务器的 /authorize 端点来获取授权代码，指定 offline_access 范围。

示例：授权码模式获取Code

GET https://${yourXAuthDomain}/oauth/v1/default/authorize?client_id=${clientId}
 &response_type=code
 &scope=openid%20offline_access
 &redirect_uri=yourApp%3A%2Fcallback
 &state=xxxxx

示例：授权码模式+PKCE 获取 Code

https://${yourXAuthDomain}/oauth/v1/default/authorize?client_id=${clientId}
&response_type=code
&scope=openid%20offline_access
&redirect_uri=yourApp%3A%2Fcallback
&state=xxxx
&code_challenge_method=S256
&code_challenge=xxxxxxx

Step2，获取Token

通过 /token 端点获取 Access Token， ID Token和 Refresh Token

示例：授权码模式请求 Token

POST https://${yourXAuthDomain}/oauth/v1/default/token?grant_type=authorization_code
&redirect_uri=yourApp%3A%2Fcallback
&code=xxxxxxxxx
&state=xxxxxxx
&scope=openid%20offline_access

示例：授权码+PKCE模式请求 Token

&redirect_uri=yourApp%3A%2Fcallback
&code=xxxxxxxx
&state=xxxxxxxxx
&scope=openid%20offline_access
&code_verifier=xxxxxx

响应示例

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "xxxx.....xxxxx",
    "scope": "offline_access openid",
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "id_token": "xxxxxxxxxxxxxxxxxx"
}

资源所有者密码模式获取Refresh Token

在该模式下，直接向/token接口请求Token。

Step 1 请求Token

POST https://${yourXAuthDomain}/oauth/v1/default/token?grant_type=password
 &redirect_uri=yourApp%3A%2Fcallback
 &username=example%40mail.com
 &password=a.gReAt.pasSword
 &scope=openid%20offline_access

响应示例

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "xxxx.....xxxxx",
    "scope": "offline_access openid",
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "id_token": "xxxxxxxxxxxxxxxxxx"
}

SPA与刷新令牌（Refresh token）

作为公共客户端实现的单页应用（SPA）程序，无法安全地在浏览器中存储和处理刷新令牌，因此必须使用不依赖刷新令牌的方法，除非其授权服务器对刷新令牌的泄漏风险采取了安全措施（如使用刷新令牌轮换或具有使用约束条件的刷新令牌）。在许多情况下，尤其是对于公共客户机的SPA应用，发行到期时间较短的访问令牌并在需要时更新令牌被认为是一种最佳做法，因此在用户会话存在的整个过程中都可能需要更新新令牌。

但是，将用户重定向到OpenID提供方并返回会带来用户体验的挑战，有可能会中断用户的体验，因此通常不希望在正常导航期间将用户重定向到登录页面。为了避免这种破坏性重定向，一个改进的措施是在应用程序中使用隐藏的iframe进行重定向，/authorize 端点允许使用名为 prompt 的请求参数，并将prompt参数设置为none，以避免中断用户体验。如果 prompt 参数的值为 none，这将保证不会提示用户登录，无论他们是否有活动会话。

如果用户具有有效会话，则应用程序将接收新令牌。如果没有，应用程序将收到错误响应，并且可以再次重定向用户，而无需使用prompt=none选项触发身份验证。XAuth在提供SDK中包含相关的设计，使应用程序更容易执行此操作。到目前为止，prompt参数是 SPA 维持用户会话而不提示用户多次登录的唯一最佳实践。

智能跟踪防护 (ITP) 和增强型跟踪防护 (ETP) 等浏览器隐私控制的引入会影响浏览器处理第三方 cookie 的方式。这些浏览器隐私控制防止使用 XAuth 会话 cookie 以静默方式更新用户会话，这会迫使用户重新进行身份验证，对无缝的用户体验产生影响。

刷新令牌轮换为 SPA 提供了一种在 ITP 浏览器中维护用户会话的解决方案。由于刷新令牌独立于任何 cookie，因此您不必依赖 XAuth会话 cookie 来更新访问和 ID 令牌。

如果应用程序和 XAuth 在同一个域中，并不会受到影响，您仍然可以使用 XAuth 会话 cookie 并静默更新令牌。

使用Refresh Token

要刷新您的访问令牌以及 ID 令牌，您可以发送带有 refresh_token 的 grant_type 的令牌请求。

当您要刷新 ID 令牌时，请确保包含 openid 范围。

http --form POST https://${yourXAuthDomain}/oauth/v1/default/token \
  accept:application/json \
  authorization:'Basic xxxxx...' \
  cache-control:no-cache \
  content-type:application/x-www-form-urlencoded \
  grant_type=refresh_token \
  redirect_uri=http://localhost:8080 \
  scope=offline_access%20openid \
  refresh_token=xxxxxxxxxxxxx

如果刷新令牌有效，那么您将获得新的访问权限和刷新令牌。

该刷新令牌与请求中发送的相同还是新的刷新令牌取决于：

是否开始刷新令牌轮换

响应示例

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "xxxx.....xxxxx",
    "scope": "offline_access openid",
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "id_token": "xxxxxxxxxxxxxxxxxx"
}