跳转至

支持的作用域

Scope（作用域）是一种安全机制，用于控制客户端应用能够访问用户数据的程度。作用域是 OAuth 2.0 规范的一部分，作用域的值是一个包含一个或多个 scope 的参数，各个 scope 之间用一个空格分隔。

以下示例展示了带有 openid 和 offline_access 作用域的 Authany 授权端点的结构：

GET https://your-project.authanyid.com/oauth2/authorize?
    client_id=<CLIENT_ID>&
    scope=openid+offline_access&
    redirect_url=<REDIRECT_URI>

在这篇文章中，我们将介绍 Authany 支持的所有 OIDC 作用域，以及每个作用域授予客户端应用的访问级别。

1. openid

这是将 Authany 用作 OIDC 或 0Auth 2.0 提供方所需的最小作用域。通常，您会单独使用 openid 作用域，或者根据客户端应用需要代表用户从 Authany 访问的数据类型，搭配其他附加作用域一起使用。

openid 作用域会为您的客户端应用授予以下访问权限：

  • Open ID Connect： 访问 Authany 授权页面、获取授权码、以及用授权码换取访问令牌所必需。
  • UserInfo 端点： 您可以使用一个带有 openid 作用域的授权请求所获取的访问令牌，通过一次单独的 HTTP 请求访问 UserInfo 端点，从而获取用户的邮箱、电话号码、头像、性别等资料信息。

以下是仅带有 openid 作用域的授权请求，其 token 端点返回的 HTTP 响应示例：

{
  "access_token": "<ACCESS_TOKEN_VALUE>",
  "expires_in": 1800,
  "id_token": "<ID_TOKEN_VALUE>",
  "token_type": "Bearer"
}

2. offline_access

要从 Authany 的 token 端点获取刷新令牌，需要 offline_access 作用域。如果客户端应用在授权请求中不包含 offline_access 作用域，那么在用授权码换取访问令牌时，响应中将不会包含 refresh_token 字段。

刷新令牌是一个密钥，您的客户端应用可以在旧的访问令牌过期后，把它发送回 Authany 服务器以换取新的访问令牌。因此，它使您的应用无需让用户重新走一遍完整的 OAuth 2.0 授权流程，就能获取新的访问令牌。

以下示例展示了带有 offline_access 作用域的授权请求，其 token 端点的响应：

{
  "access_token": "<ACCESS_TOKEN_VALUE>",
  "expires_in": 1800,
  "id_token": "<ID_TOKEN_VALUE>",
  "refresh_token": "<REFRESH TOKEN_VALUE>",
  "token_type": "Bearer"
}

3. https://authany.com/scopes/full-userinfo

在授权请求中加入 https://authany.com/scopes/full-userinfo 作用域后，Authany 会把通常由 UserInfo 端点返回的部分信息，包含在当前会话的 ID 令牌中。这些信息包括邮箱地址、电话号码和账号验证状态等。

id_token 的值是一个编码后的字符串，您需要解码这个值才能查看实际的用户资料信息。

尽管在不包含 https://authany.com/scopes/full-userinfo 作用域的授权请求中，token 端点响应里也会有 id_token 字段，但解码这类响应中的 id_token 不会包含用户资料信息。

以下示例展示了在包含 https://authany.com/scopes/full-userinfo 作用域的授权请求中，id_token 解码后的内容：

{
  "aud": [
    "<CLIENT_ID>"
  ],
  "auth_time": 1714667006,
  "email": "johndoe@example.com",
  "email_verified": false,
  "exp": 1714667852,
  "https://authgear.com/claims/user/can_reauthenticate": true,
  "https://authgear.com/claims/user/is_anonymous": false,
  "https://authgear.com/claims/user/is_verified": false,
  "https://authgear.com/claims/user/roles": [],
  "iat": 1714667552,
  "iss": "https://mycompany.com",
  "sid": "<SID_VALUE>",
  "sub": "<SUB_VALUE>"
}

下面是一个不包含 https://authany.com/scopes/full-userinfo 作用域的身份验证请求，其 id_token 解码后的内容示例：

{
  "aud": [
    "<CLIENT_ID>"
  ],
  "auth_time": 1714667006,
  "exp": 1714668328,
  "https://authgear.com/claims/user/can_reauthenticate": true,
  "https://authgear.com/claims/user/is_anonymous": false,
  "https://authgear.com/claims/user/is_verified": false,
  "https://authgear.com/claims/user/roles": [],
  "iat": 1714668028,
  "iss": "https://mycompany.com",
  "sid": "<SID_VALUE>",
  "sub": "<SUB_VALUE>"
}

请注意，第二个示例中不包含 email 和 email_verified 字段。