Docs
文档目录

认证概览

功能概述

Agentbase 身份认证(Auth)服务为项目(Project)内的终端用户(End Users)提供企业级、全生命周期的账号体系、多样化身份认证提供方(Identity Providers)、多租户团队与角色(Teams & RBAC Roles)、细粒度资源权限表达式(Permission Strings)以及安全的会话管理能力。在构建企业级 AI 智能体、知识中台与业务应用(如示例项目 企业智能客服与知识中台,Project ID:enterprise-ai-hub-210)时,Auth 服务不仅承担前端 Web 与移动端用户的注册、登录与多因素认证(MFA),还作为底层数据安全(Databases 行级 ACL、Storage 文件级 ACL、Memory 用户记忆隔离、Messaging 目标投递)的核心身份基座。

Agentbase 区分项目终端用户认证和控制台组织成员认证;两者的使用场景与权限范围不同:


核心概念与架构

Agentbase Auth 围绕“用户身份生命周期 → 认证凭证签发 → 团队与标签映射 → 资源 ACL 鉴权评估”构建完整的身份安全闭环。

核心概念说明

核心概念标识与格式示例技术定义与生命周期说明
用户主体(User)user_zhangwei_001、user_lina_002项目内的唯一自然人或业务账号实体。包含姓名(name)、唯一邮箱(email)、E.164 格式手机号(phone)、验证状态(emailVerification / phoneVerification)、账户启停状态(status)、偏好键值(prefs)及自定义标签(labels)。
会话(Session)Session ID + HTTP Cookie用户通过账号密码、OTP、Magic URL 或 OAuth2 登录成功后创建的持久态上下文。会话受项目级 会话时长(有效期)与 会话数量限制(单用户最大并发会话数)控制,支持单点踢出或全量注销。
用户 JWT(JSON Web Token)X-Appwrite-JWT: eyJhbG...由已登录客户端调用 account.createJWT() 签发的短期无状态令牌(固定有效期 15 分钟),专用于前端将当前终端用户身份安全透传给企业自建后端服务或 SQL Proxy 用户态接口,使后端以该终端用户权限执行操作。
服务端 API KeyX-Appwrite-Key: <APPBASE_API_KEY>项目级服务端管理密钥,绑定精细的功能权限域(Scopes,如 users.read、users.write、teams.write、databases.write)。仅限可信后端(如 agentbase-node-sdk@2.12.0)使用,严禁暴露在浏览器前端。
第三方身份(Identity)Identity ID + Provider UID当用户通过公共 OAuth2(如 GitHub、Google)或自定义 OAuth2(Custom OAuth2,如 Gitee、企业 SSO)登录时,系统将外部身份源的 Subject UID、访问令牌(Access Token)与项目内 User 绑定的关联记录。
用户标签(Labels)vip、architect、internal由管理员通过 Console 或 Server SDK 为用户打上的纯字母数字属性标签。标签会自动映射为运行时权限角色 label:<name>(如 Role.label('vip')),适合跨团队的扁平化等级授权。
团队与成员关系(Teams & Memberships)team_support_ops、team_kb_governance项目内面向终端用户的多租户组织单元。用户加入团队后成为成员(Membership),并可被赋予完全自定义的团队内角色(如 owner、admin、support_lead、auditor),用于实现部门级或客户租户级的数据共享。
消息目标(Targets)Email / SMS / Push Target用户关联的通知触达终点。创建用户并提供邮箱或手机号时会自动生成对应的 Email / SMS Target,供 Messaging 消息服务投递通知、告警与工单状态变更。

角色、入口与关联关系

控制台入口与路由

组织角色与 API Key Scope 权限矩阵

在 Console 或通过 Server API 操作 Auth 资源时,不同组织成员角色与 API Key Scopes 的权限边界如下:

操作域涉及资源与操作所需 API Key Scope允许执行的组织角色只读或无权角色
用户读取查询用户列表、读取用户详情、偏好、标签、会话与成员列表users.readowner, admin, developer, editor, analystbilling
用户变更创建用户、修改邮箱/手机/密码/标签/偏好、封禁解封、注销会话、删除用户users.writeowner, admin, developer, editorbilling, analyst
团队读取查询团队列表、团队详情与成员关系列表teams.readowner, admin, developer, editor, analystbilling
团队变更创建/重命名/删除团队、邀请或添加团队成员、修改成员角色teams.writeowner, admin, developer, editorbilling, analyst
通知目标管理为用户创建、更新或删除 Email / SMS / Push 消息目标targets.read / targets.writeowner, admin, developer, editorbilling, analyst
Auth 安全策略与 OAuth2 配置修改 Security 安全策略、开启/关闭登录方式、配置 Custom OAuth2项目级管理权限(Console 态)owner, admin, developereditor, billing, analyst

与其他产品模块的关联关系

  1. 结构化数据库(Databases):数据库表(如 enterprise_biz_db 下的 customer_tickets)的表级权限与行级安全(Row Security)直接使用 Auth 生成的角色字符串(如 user:user_zhangwei_001、team:team_support_ops/admin、label:vip)进行访问控制。

  2. 文件存储(Storage):存储桶 kb_enterprise_docs 和 agent_multimedia_bucket 通过 Bucket Permissions 与 File Security 识别当前登录的 Auth 用户身份,决定是否允许上传、列出或预览文件。

  3. 长期记忆(Memory):智能体记忆模块以 Auth 用户的 User ID(如 user_zhangwei_001 与 user_lina_002)作为记忆归属主键,提取个性化画像(Profile)与长期事实记忆。

  4. 消息推送(Messaging):用户在 Auth 中自动或手动登记的 Targets(邮箱、手机号、设备推送 Token)直接作为 Messaging 主题(Topics)订阅与消息下发的目标载体。


功能详解与操作指南

1. 认证方式对比:Session vs JWT vs API Key

在企业架构设计中,正确区分并选用三种认证凭据是保障数据安全与租户隔离的前提:

对比维度Session 会话认证(Cookie / Session Header)用户 JWT 认证(X-Appwrite-JWT)服务端 API Key(X-Appwrite-Key)
适用端侧浏览器 Web 应用、移动端 App(agentbase-web-sdk@2.12.0)前端调用企业自建后端服务、或访问 SQL Proxy 用户态接口企业后端微服务、定时任务、Agent 编排后端(agentbase-node-sdk@2.12.0)
签发方式调用 createEmailPasswordSession、createOAuth2Session 等登录接口生成已登录客户端调用 account.createJWT() 动态生成组织管理员在 Console 概览 → API 密钥 中创建
生命周期由项目 安全 → 会话时长 决定(默认 365 天,可按秒/分/时/天配置)固定 15 分钟有效,过期前需由客户端利用有效 Session 重新签发可配置永不过期或指定到期日,支持随时在 Console 吊销
权限评估模型严格遵循当前用户的 Effective Roles(user:{id}、team:{id}/{role}、label:{name})及资源 ACL与签发该 JWT 的用户 Session 权限完全一致,严格受表级/行级/文件级 ACL 约束按 Key 勾选的 Scopes 鉴权;在常规数据接口中默认具备服务端管理视角(不受客户端行级 ACL 限制)
浏览器暴露风险安全(优先使用 HttpOnly Cookie 并绑定域名平台)短期令牌,仅在前端向受信后端发起请求时放入请求头绝对禁止放入前端代码或公开仓库,否则将导致全库读写权限泄露

2. 登录提供方与 Custom OAuth2 配置指南

在项目 认证 → 设置 页签中,管理员可按业务场景开启或关闭基础登录方式,并配置第三方 OAuth2 提供方:

登录方式类别支持的具体方式关键行为与适用场景
基础凭证登录Email and Password(邮箱密码)、Phone(手机短信)最常用的企业客户与内部员工登录方式;邮箱创建时自动转小写并校验项目内唯一性;手机号强制 E.164 格式(如 +8613800138001)。
无密码快捷登录Magic URL(魔法链接)、Email OTP(邮箱一次性验证码)用户无需记忆密码,点击邮件中的含签名跳转链接或输入 6 位数字验证码即可创建会话,适合轻量级客户门户。
匿名会话登录Anonymous(匿名访客)为未注册访客临时生成匿名 User ID 与会话(角色归入 guests 直到转正),用户后续可绑定邮箱密码平滑升级为正式注册账号,保留已有会话关联数据。
标准与自定义 OAuth2GitHub、Google、Apple、Microsoft、Custom OAuth2 等支持接入标准 OAuth 2.0 Authorization Code 流程的身份源。Custom OAuth2 支持零代码配置接入企业自建统一身份认证(IdP)或 Gitee 等平台。

配置 Custom OAuth2(自定义 OAuth2 提供方)操作步骤

  1. 在外部身份源注册应用:前往企业统一身份平台(或 Gitee 等 OAuth2 提供方)创建 OAuth2 应用,记录签发的 Client ID 与 Client Secret。

  2. 进入控制台 OAuth2 设置:在项目 enterprise-ai-hub-210 中,依次点击左侧栏 认证 → 设置,向下滚动至 OAuth2 Providers 区域,点击 Custom OAuth2。

  3. 开启开关并填写端点与映射参数:

配置项是否必填填写规范与示例值
Enabled是切换为开启状态以激活 Custom OAuth2 提供方。
Client ID是填入身份提供方分配的应用客户端 ID,如 enterprise_sso_client_210。
Client Secret是填入客户端密钥(仅加密保存在服务端,保存后界面不回显明文)。
Well-Known Endpoint否若身份源支持 OIDC 自动发现(如 https://idp.example.com/.well-known/openid-configuration),填入后可自动填充授权与令牌端点。
Authorization Endpoint是OAuth2 授权跳转地址(必须为公网可达的 https:// 地址),如 https://gitee.com/oauth/authorize。
Token Endpoint是授权码换取 Access Token 的接口地址,如 https://gitee.com/oauth/token。
User Info Endpoint是获取用户资料 JSON 的接口地址,如 https://gitee.com/api/v5/user。
Email Endpoint(邮箱端点)否当主 User Info 接口未直接返回邮箱时,可配置独立的邮箱查询接口(如 https://gitee.com/api/v5/emails)。
Client Authentication Method是选择 Token 端点的客户端认证方式,支持 client_secret_post(表单提交密钥)或 client_secret_basic(Basic Auth 头)。
Subject / Email / Name / Email Verified 字段路径是从 User Info(或 Email Endpoint)返回 JSON 中提取字段的点分隔路径或十进制数组下标(不支持复杂表达式)。当域名识别为 gitee.com 时,控制台会自动提示示例:Subject 填 id、Name 填 name、Email 填 0.email。注意:仅当 Email Verified 路径明确返回布尔值 true 时,系统才将用户邮箱标记为 Verified。
  1. 登记 Callback URI:复制弹窗底部自动生成的完整回调地址(形如 https://appbuild.oceanbase.com/v1/account/sessions/oauth2/callback/custom/<PROJECT_ID>),原样填入外部身份提供方的允许回调地址白名单中。

  2. 在 Test 页签执行 OAuth2 验收测试:

    • 切换到 认证 → 测试 页签。

    • 确认当前访问主机的域名已登记在项目 概览 → 平台 的 Web 平台列表中。

    • 选择已启用的 OAuth2 提供方,按需填写自定义授权范围(Scope),点击 Test OAuth2 login 按钮发起真实跳转验证。

OAuth2 测试页的未配置状态

界面参考:测试项目尚未注册当前 Web 平台,也没有启用公开的 OAuth2 提供商。配置完成后才能测试登录。

安全与隔离机制说明:

  • state 参数一次性消费,并与项目 ID、浏览器会话、Callback 地址、Client ID 及服务端 state revision 强绑定;一旦管理员修改了 OAuth2 配置,历史未完成的旧 state 立即失效。

  • 测试会话隔离:在 认证 → 测试 页签登录产生的终端用户测试会话与管理员当前的 Console 登录态完全隔离;点击测试页的登出按钮仅销毁被测终端用户会话,不会导致管理员退出 Console。

3. 权限表达式(Permission Strings)与角色体系详解

Agentbase 采用统一的 Permission(操作动作)+ Role(授权主体角色)声明式模型控制 Databases、Storage 与 Messaging 的资源访问。四大基础权限动作为:

下表列出了所有受支持的 Role 角色表达式及其在 SDK 与底层存储中的映射规则:

角色类型SDK 构造表达式底层角色字符串鉴权匹配逻辑与典型业务场景
所有访问者(含未登录)Role.any()any匹配任何请求(无论是已登录用户还是未登录匿名请求)。适用于公开知识库附件下载或公开公告表读取。
所有未登录/匿名访客Role.guests()guests仅匹配未携带有效注册用户会话的访客或 Anonymous 会话。适用于公开表单投递入口。
所有已登录用户Role.users([status])users 或 users/verified、users/unverified匹配项目内任意已登录终端用户。传入 'verified' 时(即 Role.users('verified')),强制要求用户的邮箱或手机号已完成验证。
指定单一用户Role.user(userId, [status])user:<USER_ID>(如 user:user_zhangwei_001)仅匹配指定 User ID 的终端用户。常用于 customer_tickets 行级安全(Row Security),确保客户张伟只能查看自己提交的工单。
指定团队全体成员Role.team(teamId)team:<TEAM_ID>(如 team:team_support_ops)匹配已加入指定团队的任意成员(不论其在团队内担任何种角色)。适用于部门共享文档库或团队公共看板。
指定团队特定角色成员Role.team(teamId, role)team:<TEAM_ID>/<ROLE>(如 team:team_support_ops/admin)仅匹配在指定团队中拥有特定自定义角色(如 admin、support_lead)的成员。适用于工单审批、知识库发布等越权敏感操作。
指定成员关系 IDRole.member(membershipId)member:<MEMBERSHIP_ID>精确匹配某一条特定团队成员关系记录(当用户退出重进团队产生新 Membership ID 时旧授权自动失效)。
持有特定标签的用户Role.label(name)label:<LABEL_NAME>(如 label:vip、label:architect)匹配用户 labels 数组中包含该标签的任意终端用户。适用于向全体 vip 客户开放高优先级工单通道或专属存储桶访问。

服务端与客户端 SDK 权限配置代码示例

在 enterprise-ai-hub-210 项目中,当客户张伟(user_zhangwei_001)提交一条客户工单时,可使用 agentbase-web-sdk@2.12.0为该工单行绑定“本人可读可改 + VIP 技术支持团队可读可处理”的复合权限:

运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。

import { Client, Databases, Permission, Role } from 'agentbase-web-sdk'; // 版本固定 @2.12.0

const client = new Client()
    .setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
    .setProject('<APPBASE_PROJECT_ID>');

const databases = new Databases(client);

// 创建工单行并声明精细化行级权限(需表已开启 Row security)
const ticket = await databases.createDocument(
    'enterprise_biz_db',
    'customer_tickets',
    'TK-20261022-001',
    {
        title: 'OceanBase 向量索引在高并发混合检索下的 HNSW 参数调优咨询',
        status: 'open',
        priority: 'high',
        creatorUserId: 'user_zhangwei_001'
    },
    [
        // 提单人张伟本人拥有读取与更新权限
        Permission.read(Role.user('user_zhangwei_001')),
        Permission.update(Role.user('user_zhangwei_001')),
        // VIP 客户技术支持组全体成员可读取工单
        Permission.read(Role.team('team_support_ops')),
        // 仅 VIP 客户技术支持组的 admin 角色可更新或删除工单
        Permission.update(Role.team('team_support_ops', 'admin')),
        Permission.delete(Role.team('team_support_ops', 'admin'))
    ]
);

常见问题与排障

Q1:为什么在客户端调用数据库或存储接口时返回 401 User (role: guests) missing scope (account) 或 401 user_unauthorized?

原因分析:

  1. 请求未成功携带终端用户的登录 Session Cookie 或 X-Appwrite-JWT 请求头,导致服务端将该请求识别为未登录访客(role: guests)。

  2. 在跨域 Web 应用中,当前前端访问的域名(Hostname)未在项目 概览 → 平台 中登记为受信任的 Web Platform,导致浏览器拦截了跨域 Cookie 或回退令牌。

  3. 目标数据库表或存储桶未向 Role.any() 或当前用户所属的 Role.user(...) / Role.team(...) 授予对应的 read / write 权限。

解决步骤:

Q2:配置了 Custom OAuth2 后,在 Auth → Test 页面点击测试登录报错 Invalid state 或邮箱未标记为已验证(Unverified)怎么办?

原因分析:

  1. Invalid state:在发起 OAuth2 跳转后,管理员中途修改并重新保存了 Custom OAuth2 配置(触发服务端 state revision 递增),或者回调地址的主机名与发起请求时的主机名不一致。

  2. 邮箱未标记为 Verified:Custom OAuth2 要求身份提供方返回的用户 JSON 中,配置的 Email Verified 字段路径必须严格返回布尔类型 true(字符串 "true"、数字 1 或字段缺失均不会被视为已验证)。

解决步骤:

Q3:如何实现后台客服人员(如李娜 user_lina_002)在排查问题时安全冒充(Impersonate)客户视角,且不索要客户密码?

原因分析与解决方案: Agentbase 提供了受审计管控的 User Impersonation(用户冒充) 能力:

  1. 管理员进入 认证 → 用户,点开受信任的高级坐席工程师账号(如 user_lina_002 李娜),在 概览 页签底部找到 User impersonation 卡片并开启开关。

  2. 开启后,李娜在使用客户端 SDK 登录自己的账号后,可在请求中指定冒充目标用户 ID(如 user_zhangwei_001),以张伟的权限视角重现前端工单或知识检索结果。

  3. 安全审计保障:所有通过冒充发起的请求,其底层操作审计日志(Activity)均会记录在发起冒充的操作人账号下,严禁向普通外部终端用户开启该开关。

Q4:修改了用户的团队角色(team:team_support_ops/admin)或用户标签(label:vip)后,需要用户重新登录才会生效吗?

回答:


相关文档