diff --git a/docs/advanced/oauth2/device-authorization-grant.md b/docs/advanced/oauth2/device-authorization-grant.md index 4248ba8..639850e 100644 --- a/docs/advanced/oauth2/device-authorization-grant.md +++ b/docs/advanced/oauth2/device-authorization-grant.md @@ -141,14 +141,11 @@ Content-Type: application/json | `token_type` | string | 访问令牌类型,固定值 Bearer | | `expires_in` | number | 访问令牌的有效期,单位为秒 | | `access_token` | string | 访问令牌 | +| `refresh_token` | string | 刷新令牌,仅在申请了 `offline_access` 权限的情况下包含 | | `id_token` | string | OpenID Connect 的 ID 令牌,仅在申请了 `openid` 权限的情况下包含 | 至此即完成了设备代码流的所有流程,成功获取到了访问令牌。 -> [!WARNING] 不支持刷新令牌 -> -> 设备代码流目前不支持刷新令牌。如需延长授权的有效期,请重新请求用户授权。 - ### 关于 ID 令牌 ID 令牌(ID Token)是 OpenID Connect 规范的内容。OpenID Connect 是由 OpenID Foundation 提出的一种基于 OAuth 2.0 的用户身份验证协议。若要了解更多关于 OpenID Connect 的信息,请访问 [OpenID 官网](https://openid.net)。 @@ -179,6 +176,54 @@ LittleSkin 部分实现了 OpenID Connect Discovery。ID 令牌中的 `iss` 声 > [!WARNING] ID 令牌的签名算法 > 除 RS256 外,LittleSkin 还可能会使用 PS256、ES256 和 EdDSA 算法对 ID 令牌进行签名。在验证 ID 令牌之前,请确定你使用的 JWT 库支持这些算法。 +## 刷新访问令牌 + +为了延长单次授权的有效期,可在访问令牌有效期及过期后一段时间内使用刷新令牌请求刷新访问令牌,以获取一个新的访问令牌。 + +> [!TIP] 需要单独申请权限 +> 若要获取刷新令牌,则必须在 [请求设备代码对](#请求设备代码对) 时申请 `offline_access` 权限。 + +```http +POST https://open.littleskin.cn/oauth/token HTTP/1.1 +Accept: application/json +Content-Type: application/x-www-form-urlencoded + +grant_type=refresh_token& +refresh_token={{refresh_token}}& +client_id={{client_id}}& +client_secret={{client_secret}}& +``` + +| 参数 | 值 | +| --------------- | ---------------------- | +| `grant_type` | 固定值 `refresh_token` | +| `refresh_token` | 先前获取到的刷新令牌 | +| `client_id` | ... | + +如果请求成功,将返回如下响应: + +```http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "token_type": "Bearer", + "expires_in": 259200, + "access_token": "******", + "refresh_token": "******" +} +``` + +| 参数 | 类型 | 值 | +| --------------- | ------ | ------------------------- | +| `token_type` | string | 访问令牌类型,固定值 Bearer | +| `expires_in` | number | 访问令牌的有效期,单位为秒 | +| `access_token` | string | 访问令牌 | +| `refresh_token` | string | 刷新令牌,仅在申请了 `offline_access` 权限的情况下包含 | +| `id_token` | string | OpenID Connect 的 ID 令牌,仅在申请了 `openid` 权限的情况下包含 | + +访问令牌刷新后,原先的访问令牌和刷新令牌将立即失效,之后所有的 API 请求都必须使用新的访问令牌。 + ## 错误响应 除 [授权代码流 - 错误响应 - 错误类型](./authorization-code-grant.md#错误类型) 中提到的错误类型外,设备代码流还可能返回以下错误: