AgentbaseDocs
文档目录

认证(登录方式全谱)

这是什么 / 何时用

应用项目的用户认证面: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(内建)

OAuth 2.0(社交 / 企业 Provider)

Custom OAuth2(2.6.0 亮点)

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

Magic URL / Phone OTP(无密码)

匿名(游客)

JWT(服务端代表用户)

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

Custom Token(自有账号体系)

MFA(多因素)

关键参数与返回

调用关键参数返回
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();

示例指引

事实源