AgentbaseDocs
文档目录

认证概览

功能概述

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 的双层权限架构中,项目终端用户认证(Project Auth)与控制台组织管理认证(Console Organization Auth)严格物理隔离:


核心概念与架构

Agentbase Auth 围绕“用户身份生命周期 → 认证凭证签发 → 团队与标签映射 → 资源 ACL 鉴权评估”构建完整的身份安全闭环。下图展示了终端用户从发起认证到访问项目受保护资源的完整架构链路:

flowchart TB
    subgraph Client["终端应用与服务端调用方"]
        WebApp["Web / 移动端应用<br/>(agentbase-web-sdk@2.10.0)"]
        BackendSvc["企业后端服务 / Agent 工作流<br/>(agentbase-node-sdk@2.10.0)"]
    end

    subgraph AuthProviders["认证方式与身份源 (Project Auth)"]
        EmailPass["邮箱密码 / 手机短信验证码"]
        MagicOTP["无密码认证<br/>(Magic URL / Email OTP)"]
        OAuth2["OAuth2 / Custom OAuth2<br/>(Gitee / GitHub / 企业统一身份)"]
        MFA["多因素认证挑战 (MFA)<br/>(TOTP / Email / SMS / 恢复码)"]
    end

    subgraph Credentials["三类核心认证凭证"]
        SessionCookie["Session 会话凭证<br/>(HttpOnly Cookie / Session Secret)"]
        UserJWT["短期用户 JWT<br/>(X-Appwrite-JWT, 15分钟有效)"]
        ApiKey["服务端 API Key<br/>(X-Appwrite-Key, 按 Scope 授权)"]
    end

    subgraph IdentityEngine["身份解析与角色计算引擎"]
        UserDoc["用户主体 (User)<br/>user_zhangwei_001 / user_lina_002"]
        UserLabels["用户标签 (Labels)<br/>label:vip / label:architect"]
        TeamMember["团队与成员角色 (Team & Membership)<br/>team:team_support_ops/admin"]
        RoleSet["运行时等效角色集 (Effective Roles)<br/>any, users, user:{id}, team:{id}/{role}, label:{name}"]
    end

    subgraph ProtectedResources["受保护的项目资源 (ACL 强制鉴权)"]
        DB["结构化数据库 (Databases)<br/>enterprise_biz_db / customer_tickets"]
        Storage["文件存储桶 (Storage)<br/>kb_enterprise_docs / agent_multimedia_bucket"]
        Memory["长期记忆与画像 (Memory)<br/>按 user_id 隔离读写"]
    end

    WebApp --> EmailPass & MagicOTP & OAuth2
    EmailPass & MagicOTP & OAuth2 --> MFA
    MFA --> SessionCookie
    SessionCookie -->|换取短期令牌| UserJWT
    BackendSvc --> ApiKey

    SessionCookie & UserJWT --> UserDoc
    UserDoc --> UserLabels & TeamMember
    UserLabels & TeamMember --> RoleSet
    RoleSet --> DB & Storage & Memory
    ApiKey -->|按 Scopes 跨越或受控访问| DB & Storage & Memory

核心概念说明

核心概念标识与格式示例技术定义与生命周期说明
用户主体(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 登录成功后创建的持久态上下文。会话受项目级 Session length(有效期)与 Sessions limit(单用户最大并发会话数)控制,支持单点踢出或全量注销。
用户 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.10.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. 认证方式对比: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.10.0)前端调用企业自建后端服务、或访问 SQL Proxy 用户态接口企业后端微服务、定时任务、Agent 编排后端(agentbase-node-sdk@2.10.0)
签发方式调用 createEmailPasswordSession、createOAuth2Session 等登录接口生成已登录客户端调用 account.createJWT() 动态生成组织管理员在 Console Overview → API Keys 中创建
生命周期由项目 Security → Session length 决定(默认 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 配置指南

在项目 Auth → Settings 页签中,管理员可按业务场景开启或关闭基础登录方式,并配置第三方 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 提供方)操作步骤

配置项是否必填填写规范与示例值
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。

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

安全与隔离机制说明:

  • state 参数一次性消费,并与项目 ID、浏览器会话、Callback 地址、Client ID 及服务端 state revision 强绑定;一旦管理员修改了 OAuth2 配置,历史未完成的旧 state 立即失效。
  • 测试会话隔离:在 Auth → Test 页签登录产生的终端用户测试会话与管理员当前的 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)提交一条客户工单时,可使用 @alipay/agentbase-sdk@2.10.0(或 agentbase-web-sdk@2.10.0)为该工单行绑定“本人可读可改 + VIP 技术支持团队可读可处理”的复合权限:

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

const client = new Client()
    .setEndpoint('https://appbuild.oceanbase.com/v1')
    .setProject('enterprise-ai-hub-210');

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?

原因分析:

解决步骤:

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

原因分析:

解决步骤:

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

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

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

回答:


相关文档