Docs
文档目录

认证(登录方式全谱)

这是什么 / 何时用

应用项目的用户认证面:Email/Password、OAuth 2.0(含 2.6.0 新增的配置型 Custom OAuth2)、Magic URL、Phone、匿名、JWT、Custom Token,以及 MFA 多因素保护。选择思路:

本页描述应用项目用户认证。Console 管理面登录(账号密码 Session / OAuth Browser Session → 短期 JWT)是控制面凭据,见 console-sdk/nodejs.md 与 organization.md,两者的 Provider 与用户边界不可混用。

前置

使用骨架

Email/Password(内建)

  1. 注册:account.create({ userId: ID.unique(), email, password, name })(name 可选)。

  2. 登录:account.createEmailPasswordSession({ email, password });SDK 自动管理 Session Cookie。

  3. 当前用户:account.get();登出:account.deleteSession('current')。

OAuth 2.0(社交 / 企业 Provider)

  1. Console → Auth → Providers 启用目标 Provider 并填入凭据;把回调 URL 填进上游应用配置: {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId}({provider} 小写)。

  2. 前端跳转:account.createOAuth2Session({ provider, success, failure });success/failure 必须是已注册 Platform origin 下的路径。

  3. 常用枚举:OAuthProvider.Github、Google、Apple、Facebook、Discord、Microsoft、Gitlab、Linkedin、Okta、Auth0、Authentik、Salesforce、Oidc 等;内部统一认证沿用既有 OAuthProvider.Weavefox。不要用字符串强转。

Custom OAuth2(2.6.0 亮点)

适合上游提供标准 OAuth 2.0 Authorization Code 的企业身份系统,项目可直接配置,不再要求新增服务端 Provider 类:

  1. Console 在项目 OAuth Provider 管理入口保存配置:Client ID/Secret、Authorization/Token/UserInfo endpoint、clientAuthMethod、字段映射;登录端使用 OAuthProvider.CustomOauth2(agentbase-web-sdk@2.12.0 与 agentbase-node-sdk@2.12.0 均已包含,不要用字符串拼 customOauth2)。

  2. 先在 Console「认证 → 设置 → 测试 OAuth2 登录」验证当前项目已启用的 Provider,再接入应用登录;测试 Session 与 Console Session 相互隔离。

  3. 配置边界:

    • 三个 endpoint(2.7.0 起另有可选邮箱端点,留空即停用)必须是绝对公网 HTTPS 地址,不得指向本机、私网、云元数据或带 userinfo/fragment;Token/UserInfo 重定向只允许有限次数的同源 HTTPS 跳转。

    • clientAuthMethod 只允许 client_secret_post 或 client_secret_basic。

    • subjectPath 与 emailPath 必填;字段路径只支持点分隔对象属性(2.7.0 起另支持十进制数组下标,如 0.email),不执行表达式;emailVerifiedPath 只有明确返回布尔 true 才标记邮箱已验证。

    • Client Secret 保存后不回显,留空保存保留原值;变更 Client ID、endpoint(含 2.7.0 新增的邮箱端点)或 subjectPath 会切换 identity generation,不会静默接管旧 Identity。

    • 不支持 OIDC Discovery、PKCE、动态 Client Registration 或自定义 grant;专用 callback origin 缺失或不满足 HTTPS 隔离规则时不能启用。

  4. 2.7.0 增量(appbase release-2.7.0 PR 565 等):

    • Gitee 接入内置化:Console 配置表单直接给出 Gitee 示例提示(主体 id、邮箱 0.email、姓名 name、验证状态留空),并新增可选「邮箱端点」字段(如 Gitee https://gitee.com/api/v5/emails);配置独立邮箱端点后,邮箱与邮箱验证状态都从该端点的同一响应读取。SDK 侧没有新增枚举:agentbase-web-sdk@2.12.0 与 agentbase-node-sdk@2.12.0 的 OAuthProvider 均无 Gitee,Gitee 仍走 OAuthProvider.CustomOauth2。

    • 登录测试自定义 Scope:Console「测试 OAuth2 登录」的 Custom OAuth2 卡片提供可选 Scope 输入(逗号或空白分隔,提交前 trim、过滤空值并去重;空输入不传 scopes);Scope 只传给 Custom OAuth2,其他 Provider 即使页面曾输入也不会收到该参数;切换 region/project 会清空输入并重新绑定公开测试 Client。测试 Session 与 Console Session 继续相互隔离。

    • 状态与邮箱错配阻断:登录 state 一次性使用并绑定项目、浏览器、callback、Client ID 与服务端 state revision;Client Secret、任一端点、clientAuthMethod 或任一字段映射变化都会轮换 state revision——即使配置从 A 改为 B 再改回 A,旧 state 也不恢复有效。上游返回整数型主体(如 Gitee 数字 id)时服务端归一化为字符串。

Magic URL / Phone OTP(无密码)

  1. 发送:account.createMagicURLToken({ userId, email, url })(url 可选)(或 account.createEmailToken / account.createPhoneToken 触发 OTP)。

  2. 回调页取 userId + secret:account.createSession({ userId, secret });Phone 对应 account.updatePhoneSession。

匿名(游客)

  1. account.createAnonymousSession();匿名用户有唯一 userId,email/phone 为 null。

  2. 转正:account.updateEmail({ email, password })(匿名用户没有旧密码,该 password 即新设密码;userId 不变、数据全保留、邮箱验证态重置),或匿名 Session 活跃时直接 createOAuth2Session 自动并入同一账号。

  3. 限流约每 IP 每小时 50 次;完整指引见 skills/ob-agentbase/references/anonymous-auth.md。

JWT(服务端代表用户)

用户登录后 account.createJWT({ duration })(duration 可选)(默认 15 分钟)拿 jwt,交给可信后端;后端用 agentbase-node-sdk 的 Client().setJWT(...) 以该用户身份调用,权限与签发者一致。不要打印或落库 JWT。

Custom Token(自有账号体系)

  1. 业务后端自行完成外部身份校验(SSO 网关、风控、多步骤认证等)。

  2. 后端用 Server SDK 签发短期 token:users.createToken({ userId }) → 返回一次性 secret(见 users.md)。

  3. 前端 account.createSession({ userId, secret }) 换取正式 Session。该路线不依赖 OAuth 跳转或上游 UserInfo 契约。

MFA(多因素)

  1. 账号级开关:account.updateMFA({ mfa: true })。

  2. 注册认证器:account.createMFAAuthenticator({ authenticatorType })(TOTP),用 account.updateMFAAuthenticator 校验激活;account.listMFAFactors 查看已注册因子。

  3. 登录时若命中 MFA:account.createMFAChallenge({ factorId }) → account.updateMFAChallenge({ challengeId, otp }) 完成二次验证后才得到可用 Session。

  4. 恢复码:account.createMFARecoveryCodes / getMFARecoveryCodes / updateMFARecoveryCodes;换设备用恢复码兜底。

  5. 启用 MFA 的账号在自动化脚本里登录时,必须完成对应 factor challenge 才能拿到可用凭据。

关键参数与返回

调用关键参数返回
createuserId(ID.unique() 或自定义)、email、password、name(可选)Models.User
createEmailPasswordSessionemail、passwordSession(secret 在 Cookie,不在响应体明文)
createOAuth2Sessionprovider 枚举、success、failure浏览器重定向完成登录,无返回体
createSession(token 换会话)userId、secretSession
createJWTduration(可选;秒,默认 900){ jwt }
createMagicURLTokenuserId、email、url(可选)Token(含 userId)
updateMFA / MFA 族mfa、authenticatorType、factorId、challengeId、otpUser / MfaType / Challenge 等

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

Email/Password 注册与登录

Node Server SDK 不发起用户登录(见「SDK 类别差异」),登录发起统一在客户端 Session 面;Node 的角色见「JWT 与 Custom Token」卡。

import { Client, Account, ID } from 'agentbase-web-sdk';

const client = new Client()
    .setEndpoint(import.meta.env.VITE_APPWRITE_ENDPOINT)   // 带 /v1
    .setProject(import.meta.env.VITE_APPWRITE_PROJECT_ID);
const account = new Account(client);

await account.create({ userId: ID.unique(), email, password, name });  // 仅注册一次
await account.createEmailPasswordSession({ email, password });         // Session 落 Cookie
const me = await account.get();            // 抛 401 = 未登录/会话失效
await account.deleteSession('current');    // 登出当前设备

OAuth 2.0 社交 / 企业登录

浏览器重定向完成登录:无 REST 形态,服务端语言面不发起跳转,本卡仅客户端页签。

// 前置:Console 启用 Provider,回调 URL 已注册进上游应用配置(见「使用骨架」)
await account.createOAuth2Session({
    provider: OAuthProvider.Github,   // 枚举,勿用字符串强转
    success: window.location.origin + '/',
    failure: window.location.origin + '/?error=auth_failed'
});

Custom OAuth2(企业身份系统)

先在 Console 保存 Provider 配置(Client ID/Secret、三个 endpoint、clientAuthMethod、字段映射)并用「测试 OAuth2 登录」验证,再接入应用登录;登录发起与 OAuth2 相同的浏览器重定向,无 REST 形态。

await account.createOAuth2Session({
    provider: OAuthProvider.CustomOauth2,   // 2.6.0 内置枚举,不要字符串拼 customOauth2
    success: window.location.origin + '/',
    failure: window.location.origin + '/?error=auth_failed'
});

Magic URL / Phone OTP(无密码)

发送 token 邮件/短信后,回调页用 userId + secret 换正式 Session;token 发送端点未列入 API 参考,REST 从略。

// 1. 发送登录邮件(可选自定义回调 URL);Phone 短信 OTP 用 createEmailToken / createPhoneToken 触发
await account.createMagicURLToken({
    userId: ID.unique(),
    email: 'user@example.com',
    url: window.location.origin + '/auth/magic'
});
// 2. 回调页取 userId + secret 换正式 Session;Phone 对应 updatePhoneSession
await account.createSession({ userId, secret });

匿名(游客)

匿名 Session 有唯一 userId、email/phone 为 null;限流约每 IP 每小时 50 次。转正走 updateEmail(或匿名 Session 活跃时 createOAuth2Session 自动并入),userId 不变、数据全保留。

await account.createAnonymousSession();
// 转正:匿名用户没有旧密码,该 password 即新设密码;邮箱验证态重置
await account.updateEmail({ email: 'user@example.com', password: '<password>' });

JWT 与 Custom Token(服务端凭据)

服务端自验外部身份后签发 Custom Token 交前端换 Session(不依赖 OAuth 跳转或上游 UserInfo 契约);或登录用户出站 JWT 交可信后端以本人身份代调用。

import { Client, Users } from 'agentbase-node-sdk';

// Custom Token:后端自验外部身份后签发短时 token,secret 交前端换 Session
const token = await new Users(client).createToken('<userId>');   // { secret, expire }

// JWT 代调用:以用户 JWT 装载客户端,权限与签发者一致;不要打印或落库 JWT
const userClient = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setJWT('<jwt>');

MFA(多因素)

账号级开关 → 注册认证器 → 登录二次验证 → 恢复码兜底;均为用户 Session 操作,REST 端点未列入 API 参考,REST 从略。

await account.updateMFA({ mfa: true });   // 账号级开关
// 注册 TOTP 认证器并校验激活
await account.createMFAAuthenticator({ authenticatorType: 'totp' });
await account.updateMFAAuthenticator({ authenticatorType: 'totp', otp: '<code>' });
await account.listMFAFactors();           // 已注册因子

// 登录命中 MFA:先 createMFAChallenge,二次验证通过才有可用 Session
await account.createMFAChallenge({ factorId: '<factorId>' });
await account.updateMFAChallenge({ challengeId: '<challengeId>', otp: '<code>' });

// 恢复码:生成 / 查看 / 换新(换设备兜底)
await account.createMFARecoveryCodes();
await account.getMFARecoveryCodes();
await account.updateMFARecoveryCodes();

示例指引