跳转至

新服务接入:统一账号 HTTP 契约

ChatLogin 0.2.1 把账号接口和页面作为每个服务自己的插件挂载。一次 create_managed_auth 可得到登录、会话、本人资料和用户管理;宿主选择齿轮、普通链接或自有前端,不复制认证实现。这不是共享 Cookie 的 SSO、集中身份服务或任意外部用户库的通用 CRUD。

从空服务到可登录页面

python -m pip install "ChatLogin[web]==0.2.1" uvicorn

先在受保护的进程环境中提供 MY_SERVICE_BOOTSTRAP_PASSWORD,再初始化空实例。命令行只接收变量名,不接收密码值;没有生产默认账号或自动注册。

chatlogin users bootstrap operator --instance my-service --password-env MY_SERVICE_BOOTSTRAP_PASSWORD

把 完整 factory 保存为 auth_app.py,再建立 app.py:

import os
from auth_app import create_app
from chatlogin.account_ui import AccountMenuUI

app = create_app(
    instance="my-service",  # 与 bootstrap 相同
    origin=os.environ["MY_SERVICE_ORIGIN"],
    prefix="/auth",         # 也可 /admin;不影响角色策略
    menu_ui=AccountMenuUI(mode="gear"),
    allow_insecure_loopback=os.environ.get("MY_SERVICE_ALLOW_LOOPBACK") == "1",
)

部署使用浏览器真正访问的固定 HTTPS origin,由宿主负责 TLS/反代:

MY_SERVICE_ORIGIN=https://service.example.com python -m uvicorn app:app --host 127.0.0.1 --port 8765

仅在本机开发时显式开启 loopback HTTP:

MY_SERVICE_ORIGIN=http://127.0.0.1:8765 MY_SERVICE_ALLOW_LOOPBACK=1 python -m uvicorn app:app --host 127.0.0.1 --port 8765

打开首页 → 齿轮“账号设置” → 登录;owner/admin 登录后可进入用户管理,普通用户只进入本人资料。示例还提供 /private 的 auth.current_user 和 /operator 的明确角色依赖。业务数据仍需 require_owner 或宿主 ACL,admin/owner 不自动读取他人的业务记录。

factory 自建的 store 在 ASGI shutdown 关闭。测试或共享同进程服务可显式注入 users;注入对象由调用方拥有并负责关闭,不因一个宿主退出而被销毁。它不会迁移既有账户或读取演示默认凭据。

统一的 API 发现入口

GET /auth/api 返回 version(安装包版本)、schema_version=1(发现格式)、operations(实际注册的 HTTP 方法和路径)、pages(存在的页面)和 capabilities(login/managed_users/profile)。prefix="/admin" 时入口为 /admin/api;可信 ASGI mount 也计入 URL,忽略任意 forwarded-prefix 头。

发现接口验证 Host、返回 no-store,不返回用户目录、Cookie、CSRF、凭据或 state 路径。它描述功能是否提供,不代表当前用户有权限。固定账号/callback 不虚报用户管理;pages=False 的页面表为空。

默认 HTTP 契约

以下路径均相对 /auth(或宿主选择的前缀)。会话身份由服务端解析,绝不从请求的 actor/role 字段获得管理员权限。

方法与路径 JSON/结果 权限
GET /api 发现信息 可信 Host,可匿名
GET /session authenticated、user、csrf_token 可信 Host;匿名也返回 200
POST /login username、password、可选 next 同源;已有会话还需当前 CSRF
POST /logout 撤销会话 登录、同源、CSRF
GET /api/users?offset=0&limit=100 安全用户列表;limit≤100 owner/admin,范围由后端策略限制
POST /api/users username、password、可选 display_name/role;201 owner/admin;只有 owner 可授予 admin
GET /api/users/{user_id} 用户安全元数据 owner/admin 的可管理范围
PATCH /api/users/{user_id} display_name、role、enabled 的合法组合 对象级权限、同源、CSRF
DELETE /api/users/{user_id} deleted 对象级权限、同源、CSRF;禁止删 owner
POST /api/users/{user_id}/password new_password 对象级权限、同源、CSRF
GET /api/profile 本人用户资料 当前登录用户
PATCH /api/profile display_name 本人、同源、CSRF
POST /api/profile/password current_password、new_password 本人、同源、CSRF;旧会话失效
POST /api/owner/transfer target_user_id、current_password、confirm_username owner 复验、同源、CSRF、原子交接

浏览器 credentials: 'same-origin',从 /session 读取当前 CSRF,在写操作 X-CSRF-Token 头发送;不要把密码、Cookie 或 CSRF 写入 localStorage、URL 或日志。常见错误为 400(非法请求/Host)、401(未认证)、403(权限/Origin/CSRF)、404(对象不存在)、409(状态冲突)、413(体上限)、429(限流)、503(受控容量/服务不可用)。发现目录不是完整请求/响应 Schema,也不替代上述契约和宿主 OpenAPI。

齿轮、普通链接与 DIY

from chatlogin.account_ui import AccountMenuUI

# 宿主 async GET handler 内;request 为真实 FastAPI Request。
menu = await auth.render_account_menu(request)  # 中文、原生齿轮浮层
menu = await auth.render_account_menu(request, ui=AccountMenuUI(mode="links"))
menu = await auth.render_account_menu(request, ui=AccountMenuUI(language="en"))
# 自有模板或可信 renderer:
menu = await auth.render_account_menu(
    request, ui=AccountMenuUI(template_dirs=["templates"], template_name="account/menu.html")
)
# 完全 DIY:只拿安全导航信息,自行渲染。
navigation = await auth.navigation_from_request(request)

宿主承载当前身份的 HTML 响应也需设置 Cache-Control: no-store,不要由 CDN 或共享缓存保存用户菜单。导航从真实当前 session 解析 identity/role/links/assets_path;改密、禁用或角色变化后旧会话不继续提供管理入口。菜单不依赖 JS 初始化;CSS 仅作用于自身,并继承宿主字体和 ChatLogin 色板。默认片段自动转义身份/标签并验证本地链接,renderer 的 HTML 安全由可信宿主负责。退出仍是现有页面中的受 CSRF 保护 POST,不提供 GET 退出链接。

pages=False 保留 JSON API、没有默认 HTML/assets;默认菜单也不生成假的空设置按钮。自有前端按同一 HTTP 契约工作。LoginUI、UserAdminUI、UserProfileUI 保持独立模板/renderer 覆盖,安装位置不应被手动修改。

已有用户库应选择 适配路径:callback 只认证,不自动接管账户生命周期;ChatVoice legacy schema 使用明确保留式 adapter。统一 HTTP 契约不等于统一账号库、共享 Cookie 或跨站 SSO。