概述

用户属性

Casdoor 管理用户账户。每个用户都具有以下属性：

• Owner：拥有用户的组织
• Name：用户的唯一用户名（在组织内必须唯一）
• 创建时间: 用户账户创建时的时间戳
• 更新时间: 用户账户上次更新时的时间戳
• Id：每个用户的唯一标识符（UUID）
• 类型：用户账户的类型（例如，普通用户、访客用户）
• 密码: 用户的加密密码
• 密码盐: 用于密码哈希的盐值
• PasswordOptions：密码复杂性选项
• DisplayName：用户界面中显示的用户显示名称
• FirstName：用户的名（名字）
• LastName: 用户的姓氏（家庭姓名）
• Avatar: 用户当前头像图片的URL或链接
• 永久头像：用户永久存储的头像的 URL（不受提供商变更影响）
• 电子邮件：用户的电子邮件地址（自动转换为小写）
• 电话: 用户的电话号码
• 位置: 用户的地理位置
• 地址：包含用户地址信息的字符串数组（例如，街道地址、城市、州/省、邮政编码）
• 所属单位: 用户的组织或机构隶属关系
• 职称: 用户的专业职称或工作岗位
• 身份证类型：用于身份验证的身份证类型（例如，护照、驾驶证）
• 身份证：身份证号码（验证后变为只读）
• 真实姓名：用户的已验证真实姓名（身份验证后变为只读）
• IsVerified：指示用户是否已通过身份验证提供商完成身份验证
• 主页：指向用户个人主页或网站的URL
• 简介: 用户的简短传记或描述
• 标签: 用于对用户进行分类的标签（可为多个标签，用逗号分隔）
• 区域：用户的地理区域或地区
• 语言：用户首选的界面语言
• 性别：用户的性别
• 生日: 用户的出生日期
• 教育: 用户的教育水平或背景
• 余额：用户的账户余额（适用于具有支付功能的应用程序）
• 分数：与用户关联的数值评分（由应用程序定义）
• 积分：用户的积分或声誉点数
• 排名：用户的排名位置（由应用程序定义）
• IsDefaultAvatar: 表示用户是否使用默认头像
• IsOnline: 表示用户当前是否在线
• IsAdmin：表示用户是否为其组织的管理员
• IsGlobalAdmin：表示用户是否拥有管理Casdoor的权限
• IsForbidden：表示用户账户是否已被禁止或受限
• IsDeleted：当用户被软删除时（IsDeleted = true），他们无法通过任何身份验证方法登录，包括 OAuth 提供商。这可防止已删除的用户通过第三方登录重新注册。
• SignupApplication：用户注册时所用的应用
• 哈希：用于内部身份验证机制的哈希值
• 预哈希：前一个哈希值（用于密码迁移期间）
• CreatedIp：创建用户账户时所用的IP地址
• 上次登录时间：用户上次登录的时间戳
• 上次登录IP：用户上次登录时的IP地址
• 权限：用户的权限数组（扩展字段，通过用户 API 只读）
• 权限：用户的权限数组（扩展字段，通过用户 API 只读）
• OriginalRefreshToken：最近一次社交登录的刷新令牌（旧版单提供商字段，为向后兼容而保留）。在 API 响应中显示为 ***。
• Properties["oauth_<ProviderType>_accessToken"] / Properties["oauth_<ProviderType>_refreshToken"]: 按提供程序存储的 OAuth 令牌，位于Properties映射中。当用户通过多个 OAuth 提供商登录时，每个提供商的令牌会各自存储在独立的密钥下（例如：oauth_GitHub_accessToken). 这两个字段在API响应中均被屏蔽为***。
• 地址：结构化地址条目的列表。每个地址都包含标签（家庭、工作、其他）、第一行, 第二行, 城市, 州, 邮政编码,以及地区. 用户可从账户个人资料页面管理他们的地址

社交平台登录的唯一ID：

• Github：用户通过 GitHub OAuth 登录得到的唯一标识
• Google：来自Google OAuth登录的用户唯一标识符
• QQ：来自QQ OAuth登录的用户唯一标识符
• 微信：用户通过微信OAuth登录获得的唯一标识符
• Facebook：用户通过FacebookOAuth登录获得的唯一标识符
• 钉钉：用户通过钉钉OAuth登录获得的唯一标识符
• 微博：用户通过微博OAuth登录获得的唯一标识符
• Gitee：来自Gitee OAuth登录的用户唯一标识符
• LinkedIn：来自LinkedIn OAuth登录的用户唯一标识符
• 企业微信：用户通过企业微信OAuth登录获得的唯一标识符
• 飞书：用户通过飞书OAuth登录获得的唯一标识符
• Gitlab：来自GitLab OAuth登录的用户唯一标识符
• Adfs：来自ADFS认证的用户唯一标识符
• 百度：用户从百度OAuth登录获取的唯一标识符
• Casdoor：用户从其他Casdoor实例OAuth登录获取的唯一标识符
• Infoflow：用户通过Infoflow OAuth登录获得的唯一标识符
• Apple：用户通过Apple OAuth登录获得的唯一标识符
• Azure AD：来自Azure Active Directory OAuth登录的用户唯一标识符
• Azure AD B2C：来自Azure AD B2C OAuth登录的用户唯一标识符
• Slack：来自Slack OAuth登录的用户唯一标识符
• Steam：来自Steam OAuth登录的用户唯一标识符
• Ldap：来自LDAP认证的用户唯一标识符
• Telegram：来自Telegram OAuth登录的用户唯一标识符

组织管理员权限

开启了 IsAdmin 的用户是所在组织的管理员：

• 可完全访问并管理其组织内的用户、应用程序和资源
• 访问发送给组织内用户的验证码记录
• 能够配置组织级设置和策略

组织管理员拥有提升的权限，但权限范围仅限于其所属组织。全局管理员（内置组织用户）在Casdoor实例的所有组织中拥有完全访问权限。

用户标签

Tag 字段用于给用户分类。使用单个标签或用逗号分隔的多个标签（例如："developer,qa,reviewer"). 应用程序访问检查会单独评估每个标签。

保留的标签值：

• normal-user: 具有完整身份验证功能的标准用户
• guest-user：通过访客身份验证创建的临时用户，无需初始凭据
  • 当用户设置正确的用户名或密码时，自动升级为普通用户
  • 在他们升级账户之前，无法直接登录

自定义标签可限制应用访问。查看应用标签.

身份验证

Casdoor支持通过身份验证提供商进行身份验证。用户可通过提交身份证信息和真实姓名来验证身份，这些信息将通过Jumio等第三方服务进行验证。

当用户完成身份验证时：

• IsVerified 字段被设为 true
• RealName、IdCardType、IdCard 等身份相关字段变为只读
• 验证状态包含在JWT令牌和OIDC userinfo响应中
• 用户个人资料上会显示验证徽章

此功能适用于需要遵守KYC（了解您的客户）合规要求或需确保用户身份真实性的应用。请参阅身份验证提供商以了解有关配置身份验证的更多信息。

电子邮件规范化

Casdoor会将所有电子邮件地址统一转换为小写，以确保唯一性并避免重复账户。也就是说，user@example.com、User@Example.com 和 USER@EXAMPLE.COM 会被当作同一个邮箱地址，符合 RFC 5321 标准。

此规范化操作会在以下过程中自动进行：

• 用户注册与账户创建
• 用户登录与身份验证
• 电子邮件重复性检查

用 columns 参数做部分更新

/api/update-user 接受一个可选的 columns 查询参数，用来做部分更新：只写入列出的字段，用户的其他字段保持不变。不传（或留空）则更新整个用户对象。

columns 中的字段名可以用 camelCase 或 snake_case，两种写法都接受，指向同一个底层字段。例如 columns=displayName,avatar 和 columns=display_name,avatar 是等价的。

角色与权限（扩展字段）

User 对象上的 Roles 和 Permissions 字段是扩展字段：它们在读取用户数据时填充，并不存储在用户表中。它们通过 ExtendUserWithRolesAndPermissions() 从角色和权限资源构建出来。

重要提示：您无法通过/api/update-user更改角色或权限（包括通过columns参数）。使用角色和权限API 及其管理页面（例如，侧栏中的角色和权限）来分配和管理它们。

使用属性字段

Properties 字段是一个键值映射（map[string]string），用来存放内置字段没有覆盖的自定义用户属性。 :用于：

• 存储组织特定的用户属性
• 添加不适合标准字段的自定义元数据
• 在不修改核心模式的情况下扩展用户简档

从XLSX导入用户

通过上传XLSX文件来添加或更新用户。

入门

在管理控制台的用户页面上，您将看到：

• 下载模板：生成包含所有可用用户字段及其本地化列标题的XLSX模板
• 上传 (.xlsx)：打开上传对话框，以从您的 XLSX 文件导入用户

模板文件的表头格式为 Display Name#field_name（例如 Organization#owner），其中显示名称会按你的语言本地化，# 后面的字段名用于导入映射。导入时会自动移除注释前缀（即#之前的所有内容）。

上传流程

选择XLSX文件后，Casdoor会显示数据的预览。请审阅并确认以开始导入。 A示例文件 (xlsx/user_test.xlsx) 包含5个测试用户，可供参考。

上传权限

谁可以上传取决于您的角色：

• 全局管理员（built-in 组织中 IsGlobalAdmin 为 true 的用户）可以把用户上传到任意组织。目标组织由 XLSX 文件中的 Owner 字段决定。
• 组织管理员（已将IsAdmin设置为 true 的用户）只能向其所属的组织上传用户。系统确保重复检查和用户创建的作用域限定在正确的组织内。

导入时绕过密码加密

在将用户从其他系统迁移时，您可能需要保留现有的密码哈希值，而不是使用组织的默认密码类型重新哈希。导入用户时，用 passwordType 字段告诉 Casdoor 存储的密码是什么格式。

:::注意 示例：bcrypt密码 示例 POST 正文用于/api/add-user:

{
  "owner": "组织",
    "signupApplication": "first-app",
    "email":"dev@dev.com",
    "name": "dev",
    "displayName": "开发者",
    "password": "$2a$10$.o/iVyDE9Xk8ioywHDnQRu72RviOi6FPa1ujhusbSCZeg7VOa6MY6",
    "passwordType":"bcrypt",
}

密码已经是 bcrypt 哈希，所以把 passwordType 设为 "bcrypt"，Casdoor 就不会再哈希一次。

:::