Base Account / Integration
账号系统接入文档
按能力模块拆分的接入规范，供产品工程和 AI Agent 按需获取。
Quick Start
准备环境变量
下游服务至少配置 AUTH_ISSUER、AUTH_AUDIENCE、AUTH_JWKS_URL；账号中心配置 AUTH_ALLOWED_RETURN_ORIGINS、AUTH_ALLOWED_RETURN_SUFFIXES。
接入统一授权入口
外部服务统一跳转 /authorize?return_to&state（service 可传但会被忽略），禁止直接跳 /login。
登记服务域名
推荐通过 CLI 注册服务：ba admin services create --origin https://your-app.example.com（也可在 Admin Console 的 Services 区域手动登记）。需先登记/启用 origin，再让外部服务发起授权。
处理回跳并建立应用会话
回跳后在服务端读取共享 access_token cookie 验签 JWT，提取用户 email，然后创建应用自有的 gateway session cookie（HMAC 签名的 email + 过期时间）。重要：不要直接依赖共享 access_token cookie 作为日常登录态，否则跨应用切换账号会导致身份污染。
按需接入 JWT 校验
如果你的服务需要在后端验签 access token，再接入 auth-sdk 的 JWKS 验签。
推荐使用 CLI 工具完成服务注册和管理操作，无需访问 Admin Console：npm install -g @stringzhao/base-account-cli