跳到主内容

概述

Casdoor基于OAuth构建，并使用令牌进行用户身份验证和授权。

访问令牌和ID令牌​

在Casdoor中，access_token与id_token是相同的。 两者都包含相同的JWT有效载荷（用户信息和声明）。 这种设计使令牌处理保持简单。

这种方法意味着：

  • 这两个令牌包含相同用户信息和自定义声明
  • 这两个令牌可互换用于身份验证和授权
  • 令牌格式和过期设置对这两个令牌同样适用
  • 您无法为access_token</code>和id_token配置单独的声明。

令牌字段​

Casdoor 令牌包含以下字段：

  • Owner
  • Name
  • CreatedTime
  • Application
  • Organization
  • User
  • Code
  • AccessToken
  • ExpireIn（令牌将在几小时后过期）
  • Scope (授权范围)
  • TokenType（例如，Bearer 类型）

令牌生命周期与失效​

当用户登录时，Casdoor 会颁发一个访问令牌和一个刷新令牌。 访问令牌用于 API 身份验证；刷新令牌用于在无需重新身份验证的情况下获取新的访问令牌。

On SSO logout, Casdoor invalidates tokens by setting ExpiresIn to 0 or a negative value. 令牌内省和刷新端点会检查此字段，并拒绝具有``ExpiresIn<= 0的令牌，因此注销后无法再使用刷新令牌。 这将导致所有标记类型会话完全终止。

Automatic cleanup of expired tokens​

Casdoor automatically deletes token records that have been expired for a while, so the token table does not grow without bound. A token is removed once it has been expired for longer than a retention interval of 30 days (counted from the token's own expiry time).

The cleanup job runs:

  • once at startup (in the background, so it does not delay server start), and
  • daily at midnight (server time).

The cleanup only affects already-expired tokens past the retention window; active tokens are never touched. This behavior is built in and requires no configuration.

令牌格式选项​

在颁发JWT时，可从四种格式中进行选择：

  • JWT
  • JWT-Empty
  • JWT-Custom
  • JWT-标准

令牌格式选项的行为如下：

  • JWT：在令牌有效载荷中包含所有用户字段
  • JWT-空：仅包含非空用户字段
  • JWT-自定义：包含您选择的自定义用户令牌字段（在令牌字段中选择属性）
  • JWT标准：以符合OIDC的格式包含标准OIDC声明（电子邮件、电话、性别、地址）
信息

仅JWT标准生成符合OIDC规范的地址声明。在JWT、JWT-Empty和JWT-Custom格式中，该字段以原始[]string数组形式（即用户的Address属性）包含其中，这并不符合OIDC规范。 如果您的应用程序将``地址声明解析为对象，请使用JWT-标准令牌格式。

Restricting fields with Token fields​

The Token fields setting on the application (used to pick custom user attributes for the JWT-Custom format) also acts as a whitelist for the /userinfo endpoint.

  • When Token fields is empty, no whitelist is applied: the token payload and the /userinfo response include their full default set of fields. This is the default behavior.
  • When Token fields lists one or more fields, only those fields are returned. Any user attribute not in the list is omitted from both the JWT-Custom token payload and the /userinfo response.

The whitelist is matched against the underlying user-property names. For example, to expose the display name, email, and avatar through /userinfo, add Name, Email, and Avatar to Token fields. Fields still respect the requested OAuth scopes — for instance Email is only returned when the email scope is granted, Location (the address claim) only with the address scope, and Phone only with the phone scope. The sub and aud claims are always returned regardless of the whitelist.

注意事项

Configuring Token fields restricts /userinfo, not only the token. If you previously relied on /userinfo returning every field, adding entries here will start filtering that response. Leave Token fields empty to keep the full response.

OIDC 地址声明​

OIDC 规范定义了address声明为一个 JSON 对象，包含以下字段：

字段描述
格式化完整邮寄地址，已格式化以便显示
街道地址街道地址组成部分（可能包含门牌号、街道名称、邮政信箱 信箱等）
所在地城市或所在地
地区州、省、地级市或地区
邮政编码邮编或邮政编码
国家国家名称

Casdoor如何将用户数据映射到地址声明​

Casdoor在两个独立的用户字段中存储地址信息：

  • 位置（字符串）：一个通用的位置字符串（例如，“纽约”). 此字段用作纯字符串地址值，当请求/api/userinfo端点时，由该端点返回。
  • 地址（字符串数组）：地址行字符串数组（例如，["123 Main St", "Anytown, NY 12345", "USA"]). 此字段是符合 OIDC 规范的``地址声明在JWT 标准令牌中的来源。

JWT-标准地址声明​

当请求``地址范围且使用JWT标准格式时，Casdoor会在令牌中返回以下对象：

{
  "address": {
    "street_address": "123 Main St\nAnytown, NY 12345\nUSA",
    "formatted": "",
    "locality": "",
    "region": "",
    "postal_code": "",
    "country": ""
  }
}

街道地址字段包含用户地址数组条目，各条目之间用换行符连接。 其余的OIDC地址子字段（格式化、 locality、region、postal_code、country) 目前为空，因为 Casdoor 将整个地址以自由格式的行存储在Address数组中，而非按各个组成部分分别存储。

非标准格式（JWT、JWT-Empty、JWT-自定义）​

在 JWT、JWT-Empty 和 JWT-Custom 令牌格式中，address字段是用户对象的原始Address属性——一个字符串 JSON 数组——而非 OIDC 地址对象：

{
  "address": ["123 Main St", "Anytown, NY 12345", "USA"]
}

期望``address声明为 JSON 对象的 OIDC 客户端（根据 OIDC 规范）将无法解析此内容。 如果您需要在令牌中使用符合规范的address声明，请切换到JWT标准。

JWT-自定义

标准OIDC声明​

所有JWT令牌格式均在有效负载中包含这些标准OpenID Connect声明：

  • ``sub- 主题标识符（唯一用户ID）
  • ``email- 用户的电子邮件地址
  • email_verified- 布尔值，表示电子邮件是否已由Casdoor验证
  • name或preferred_username- 用户的显示名称
  • picture或avatar- 用户头像URL

电子邮件验证声明使使用Casdoor作为身份提供商的外部应用程序能够直接从令牌中确定电子邮件验证状态，而无需额外的API调用。

自定义令牌属性​

使用JWT-自定义格式，定义自定义属性及其数据类型。 每个属性都包含一个类型字段，用于控制值如何包含在JWT中：

  • 数组：即使属性值仅包含一个元素，也始终以数组形式返回。 这可确保与期望角色、组或权限等字段采用数组类型的OIDC客户端兼容。
  • 字符串：属性值将作为单个字符串返回（如果存在多个值，则返回第一个元素）。

空属性会自动从标记中省略，以保持有效负载的简洁。 在为角色、组或权限配置属性时，建议使用数组类型，以更好地符合OIDC规范，并与Rancher和Keycloak等系统兼容。