认证(登录方式全谱)
这是什么 / 何时用
应用项目的用户认证面:Email/Password、OAuth 2.0(含 2.6.0 新增的配置型 Custom OAuth2)、Magic URL、Phone、匿名、JWT、Custom Token,以及 MFA 多因素保护。选择思路:
标准 Web / 移动应用:Email/Password 为基座,按需叠加社交 OAuth。
企业身份系统:标准 Authorization Code 上游走 Custom OAuth2(2.6.0 起内置,不需要写服务端 Provider 类);已有自有身份校验后端走 Custom Token。
无密码 / 低门槛:Magic URL、匿名(后续可无损转正)。
服务端代表用户调用:JWT;服务端编排外部身份:Custom Token。
本页描述应用项目用户认证。Console 管理面登录(账号密码 Session / OAuth Browser Session → 短期 JWT)是控制面凭据,见 console-sdk/nodejs.md 与 organization.md,两者的 Provider 与用户边界不可混用。
前置
项目已存在且客户端来源已注册(浏览器需 Web Platform,见 overview.md)。
各方式的启用入口在 Console → Auth → Settings / Providers;匿名登录在新项目默认开启,不用就关掉。
Magic URL / Email 验证 / 恢复邮件需要实例配置 SMTP。
Custom OAuth2 需要上游提供标准 Authorization Code:Client ID/Secret、Authorization/Token/UserInfo 三个 endpoint 与字段映射。
使用骨架
Email/Password(内建)
注册:
account.create({ userId: ID.unique(), email, password, name })(name可选)。登录:
account.createEmailPasswordSession({ email, password });SDK 自动管理 Session Cookie。当前用户:
account.get();登出:account.deleteSession('current')。
OAuth 2.0(社交 / 企业 Provider)
Console → Auth → Providers 启用目标 Provider 并填入凭据;把回调 URL 填进上游应用配置:
{endpoint}/account/sessions/oauth2/callback/{provider}/{projectId}({provider}小写)。前端跳转:
account.createOAuth2Session({ provider, success, failure });success/failure必须是已注册 Platform origin 下的路径。常用枚举:
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 类:
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)。先在 Console「认证 → 设置 → 测试 OAuth2 登录」验证当前项目已启用的 Provider,再接入应用登录;测试 Session 与 Console Session 相互隔离。
配置边界:
三个 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 隔离规则时不能启用。
2.7.0 增量(appbase release-2.7.0 PR 565 等):
Gitee 接入内置化:Console 配置表单直接给出 Gitee 示例提示(主体
id、邮箱0.email、姓名name、验证状态留空),并新增可选「邮箱端点」字段(如 Giteehttps://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(无密码)
发送:
account.createMagicURLToken({ userId, email, url })(url可选)(或account.createEmailToken/account.createPhoneToken触发 OTP)。回调页取
userId+secret:account.createSession({ userId, secret });Phone 对应account.updatePhoneSession。
匿名(游客)
account.createAnonymousSession();匿名用户有唯一 userId,email/phone为null。转正:
account.updateEmail({ email, password })(匿名用户没有旧密码,该 password 即新设密码;userId 不变、数据全保留、邮箱验证态重置),或匿名 Session 活跃时直接createOAuth2Session自动并入同一账号。限流约每 IP 每小时 50 次;完整指引见
skills/ob-agentbase/references/anonymous-auth.md。
JWT(服务端代表用户)
用户登录后 account.createJWT({ duration })(duration 可选)(默认 15 分钟)拿 jwt,交给可信后端;后端用 agentbase-node-sdk 的 Client().setJWT(...) 以该用户身份调用,权限与签发者一致。不要打印或落库 JWT。
Custom Token(自有账号体系)
业务后端自行完成外部身份校验(SSO 网关、风控、多步骤认证等)。
后端用 Server SDK 签发短期 token:
users.createToken({ userId })→ 返回一次性secret(见 users.md)。前端
account.createSession({ userId, secret })换取正式 Session。该路线不依赖 OAuth 跳转或上游 UserInfo 契约。
MFA(多因素)
账号级开关:
account.updateMFA({ mfa: true })。注册认证器:
account.createMFAAuthenticator({ authenticatorType })(TOTP),用account.updateMFAAuthenticator校验激活;account.listMFAFactors查看已注册因子。登录时若命中 MFA:
account.createMFAChallenge({ factorId })→account.updateMFAChallenge({ challengeId, otp })完成二次验证后才得到可用 Session。恢复码:
account.createMFARecoveryCodes/getMFARecoveryCodes/updateMFARecoveryCodes;换设备用恢复码兜底。启用 MFA 的账号在自动化脚本里登录时,必须完成对应 factor challenge 才能拿到可用凭据。
关键参数与返回
| 调用 | 关键参数 | 返回 |
|---|---|---|
create | userId(ID.unique() 或自定义)、email、password、name(可选) | Models.User |
createEmailPasswordSession | email、password | Session(secret 在 Cookie,不在响应体明文) |
createOAuth2Session | provider 枚举、success、failure | 浏览器重定向完成登录,无返回体 |
createSession(token 换会话) | userId、secret | Session |
createJWT | duration(可选;秒,默认 900) | { jwt } |
createMagicURLToken | userId、email、url(可选) | Token(含 userId) |
updateMFA / MFA 族 | mfa、authenticatorType、factorId、challengeId、otp | User / MfaType / Challenge 等 |
错误与边界
所有方式的用户共享同一个项目用户系统;同一账号可同时绑定多种登录方式。
OAuth 常见失败:Provider 未启用、回调 URL 未注册 Platform、
success域名未注册——三者都先查 overview.md 的平台注册。Custom OAuth2 的上游地址不符合 HTTPS/SSRF 规则、字段映射缺失(
subjectPath/emailPath)会直接配置失败或登录失败;失败信息优先对照 Console 登录测试。Session 默认有效期较长(Console → Auth 可调),过期后
account.get()抛 401;前端按未登录处理。凭据(密码、
secret、jwt、Session)不得写入源码、命令参数、日志与版本库。
SDK 类别差异
Web / Client SDK(client-sdk/web.md):承载全部登录方式的发起端;OAuth 为浏览器重定向;Session 由 Cookie / header / fallback 三层恢复。
Server SDK:不发起用户登录,只做 Custom Token 签发(
users.createToken)、用户管理与以 JWT / Session 的受控代调用。Console SDK:管理面凭据(Console 账号 Session、
setCookie、短期 JWT),与应用用户认证是两套边界。Java / 其他语言面按同构方法名使用,见 integration 与对应 index。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
Email/Password 注册与登录
Node Server SDK 不发起用户登录(见「SDK 类别差异」),登录发起统一在客户端 Session 面;Node 的角色见「JWT 与 Custom Token」卡。
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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'); // 登出当前设备import io.agentbase.ID;
import io.agentbase.services.Account;
Account account = new Account(client); // client 初始化见 server-sdk/java.md
account.create(ID.unique(), "user@example.com", "<password>", "Example User"); // 仅注册一次
account.createEmailPasswordSession("user@example.com", "<password>"); // Session 落 Cookie
Object me = account.get(); // 抛 401 = 未登录/会话失效
account.deleteSession("current"); // 登出当前设备from agentbase.id import ID
from agentbase.services.account import Account # agentbase.services 下的 account 模块
account = Account(client) # client 初始化见 server-sdk/python.md
account.create(user_id=ID.unique(), email='user@example.com', password='<password>', name='Example User') # 仅注册一次
account.create_email_password_session(email='user@example.com', password='<password>') # Session 落 Cookie
me = account.get() # 抛 401 = 未登录/会话失效
account.delete_session('current') # 登出当前设备account := agentbase.NewAccount(cl) // facade 构造器;cl 为已装载项目 Key 的 Client
_, _ = account.Create(id.Unique(), "user@example.com", "<password>",
account.WithCreateName("Example User")) // 仅注册一次;userId/email/password 按位置传,name 用 WithCreateName
_, _ = account.CreateEmailPasswordSession("user@example.com", "<password>") // Session 经 Set-Cookie 下发,取 cookie 后可 setSession 回放
me, err := account.Get() // 抛 401 = 未登录/会话失效
_, _ = account.DeleteSession("current") // 登出当前设备# $APPBASE_ENDPOINT 含 /v1。登录:Session 经 Set-Cookie 下发,用 -c 落盘供后续回放
curl -sS -c cookies.txt -X POST "$APPBASE_ENDPOINT/account/sessions/email" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"email":"user@example.com","password":"<password>"}'
# 当前用户:GET /account(回放 Cookie);登出当前设备:DELETE /account/sessions/current
curl -sS -b cookies.txt "$APPBASE_ENDPOINT/account" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Authorization: Bearer $APPBASE_API_KEY"OAuth 2.0 社交 / 企业登录
浏览器重定向完成登录:无 REST 形态,服务端语言面不发起跳转,本卡仅客户端页签。
- Web(用户 Session)
// 前置: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 形态。
- Web(用户 Session)
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 从略。
- Web(用户 Session)
- Java
- Python
- Go
// 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 });import io.agentbase.ID;
// 1. 发送登录邮件(可选自定义回调 URL);Phone 短信 OTP 用 createEmailToken / createPhoneToken 触发
account.createMagicURLToken(ID.unique(), "user@example.com", "https://app.example.com/auth/magic", null);
// 2. 回调页取 userId + secret 换正式 Session;Phone 对应 updatePhoneSession
account.createSession(userId, secret);from agentbase.id import ID
# 1. 发送登录邮件(可选自定义回调 URL);Phone 短信 OTP 用 create_email_token / create_phone_token 触发
account.create_magic_url_token(user_id=ID.unique(), email='user@example.com',
url='https://app.example.com/auth/magic')
# 2. 回调页取 userId + secret 换正式 Session;Phone 对应 update_phone_session
account.create_session(user_id=user_id, secret=secret)account := agentbase.NewAccount(cl) // facade 构造器;cl 为已装载项目 Key 的 Client
// 1. 发送登录邮件(可选自定义回调 URL);Phone 短信 OTP 用 CreateEmailToken / CreatePhoneToken 触发
_, _ = account.CreateMagicURLToken(id.Unique(), "user@example.com",
account.WithCreateMagicURLTokenUrl("https://app.example.com/auth/magic"))
// 2. 回调页取 userId + secret 换正式 Session;Phone 对应 UpdatePhoneSession
_, _ = account.CreateSession("<userId>", "<secret>")匿名(游客)
匿名 Session 有唯一 userId、email/phone 为 null;限流约每 IP 每小时 50 次。转正走 updateEmail(或匿名 Session 活跃时 createOAuth2Session 自动并入),userId 不变、数据全保留。
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
await account.createAnonymousSession();
// 转正:匿名用户没有旧密码,该 password 即新设密码;邮箱验证态重置
await account.updateEmail({ email: 'user@example.com', password: '<password>' });account.createAnonymousSession();
account.updateEmail("user@example.com", "<password>"); // 转正:匿名用户没有旧密码,该 password 即新设密码account.create_anonymous_session()
account.update_email(email='user@example.com', password='<password>')_, _ = account.CreateAnonymousSession() // 匿名 Session:唯一 userId,email/phone 为 null
// 转正:匿名用户没有旧密码,该 password 即新设密码;userId 不变、邮箱验证态重置
_, _ = account.UpdateEmail("user@example.com",
account.WithUpdateEmailPassword("<password>"))# 匿名登录(无请求体):Session 经 Set-Cookie 下发
curl -sS -c cookies.txt -X POST "$APPBASE_ENDPOINT/account/sessions/anonymous" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
# 转正:PATCH /account/email(body: email, password)
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/email" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"email":"user@example.com","password":"<password>"}'JWT 与 Custom Token(服务端凭据)
服务端自验外部身份后签发 Custom Token 交前端换 Session(不依赖 OAuth 跳转或上游 UserInfo 契约);或登录用户出站 JWT 交可信后端以本人身份代调用。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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>');// 登录用户出站 JWT:交给可信后端代调用(默认 15 分钟)
const { jwt } = await account.createJWT();
// Custom Token 流的客户端收尾:token 换 Session
await account.createSession({ userId: '<userId>', secret: token.secret });import io.agentbase.services.Users;
var token = new Users(client).createToken("<userId>", null, null); // { secret, expire }
// 浏览器端用 Client SDK:account.createSession({ userId, secret: token.secret })from agentbase.services.users import Users
token = Users(client).create_token('<userId>') # 方法名同构(snake_case),返回 { secret, expire }token, err := agentbase.NewUsers(cl).CreateToken("<userId>") // 与 Node 面同构;Length / Expire 经 WithCreateTokenLength / WithCreateTokenExpire,返回 { secret, expire }# 服务端签发短时 Custom Token(body 可选参数见 API 参考 users 页)
curl -sS -X POST "$APPBASE_ENDPOINT/users/<userId>/tokens" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "Authorization: Bearer $APPBASE_API_KEY" \
-d '{}'
# 为既有 Session 签发 JWT:POST /users/<userId>/jwts;用户态出站 JWT:POST /account/jwts(回放 Session Cookie)MFA(多因素)
账号级开关 → 注册认证器 → 登录二次验证 → 恢复码兜底;均为用户 Session 操作,REST 端点未列入 API 参考,REST 从略。
- Web(用户 Session)
- Java
- Python
- Go
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();import io.agentbase.enums.AuthenticationFactor;
import io.agentbase.enums.AuthenticatorType;
account.updateMFA(true); // 账号级开关
account.createMFAAuthenticator(AuthenticatorType.TOTP); // 注册 TOTP 认证器(AuthenticatorType 枚举)
account.updateMFAAuthenticator(AuthenticatorType.TOTP, "<code>"); // 校验激活
account.listMFAFactors(); // 已注册因子
// 登录命中 MFA:先 createMFAChallenge(factor 用 AuthenticationFactor 枚举),二次验证通过才有可用 Session
account.createMFAChallenge(AuthenticationFactor.TOTP);
account.updateMFAChallenge("<challengeId>", "<code>");
// 恢复码:生成 / 查看 / 换新(换设备兜底)
account.createMFARecoveryCodes();
account.getMFARecoveryCodes();
account.updateMFARecoveryCodes();from agentbase.enums.authentication_factor import AuthenticationFactor
from agentbase.enums.authenticator_type import AuthenticatorType
account.update_mfa(mfa=True) # 账号级开关
account.create_mfa_authenticator(type=AuthenticatorType.TOTP) # 注册 TOTP 认证器(参数名 type)
account.update_mfa_authenticator(type=AuthenticatorType.TOTP, otp='<code>') # 校验激活
account.list_mfa_factors() # 已注册因子
# 登录命中 MFA:先 create_mfa_challenge(factor 用 AuthenticationFactor 枚举),二次验证通过才有可用 Session
account.create_mfa_challenge(factor=AuthenticationFactor.TOTP)
account.update_mfa_challenge(challenge_id='<challengeId>', otp='<code>')
# 恢复码:生成 / 查看 / 换新(换设备兜底)
account.create_mfa_recovery_codes()
account.get_mfa_recovery_codes()
account.update_mfa_recovery_codes()_, _ = account.UpdateMFA(true) // 账号级开关
_, _ = account.CreateMFAAuthenticator("totp") // 注册 TOTP 认证器
_, _ = account.UpdateMFAAuthenticator("totp", "<code>") // 校验激活
_, _ = account.ListMFAFactors() // 已注册因子
// 登录命中 MFA:先 CreateMFAChallenge(factor 传枚举字符串值),二次验证通过才有可用 Session
_, _ = account.CreateMFAChallenge("totp")
_, _ = account.UpdateMFAChallenge("<challengeId>", "<code>")
// 恢复码:生成 / 查看 / 换新(换设备兜底)
_, _ = account.CreateMFARecoveryCodes()
_, _ = account.GetMFARecoveryCodes()
_, _ = account.UpdateMFARecoveryCodes()示例指引
各语言完整调用写法集中在语言树
examples/(按「SDK 轴初始化 → 功能轴各功能点」分节)。本仓内可运行自动化示例(登录、建项、平台注册组合):主仓 demo 模板
assets/examples/team-kanban-demo/scripts/auto-setup.mjs(纯文本路径引用,不在本树内)。