Auth Service

可自托管的多应用统一认证服务，提供 Google / GitHub 登录、无密码邮箱验证码登录、 Authorization Code + PKCE、RS256 JWT/JWKS、Refresh Token 轮换与跨应用 SSO 会话。

本项目提供自己的认证协议与端点契约，不宣称兼容 OpenID Connect。接入前请以 认证契约 为准。

架构

┌──────────────────────┐
│ Web / Desktop Clients│
└──────────┬───────────┘
           │ Authorization Code + PKCE
           ▼
┌───────────────────────────────────────────┐
│ Auth Service (FastAPI)                    │
│                                           │
│ • Google / GitHub 登录                    │
│ • 无密码邮箱验证码注册 / 登录             │
│ • RS256 JWT 签发、JWKS 发布               │
│ • Refresh Token 轮换、撤销与 SSO 会话     │
│ • 多应用与登录审计                        │
└──────────────┬─────────────────┬──────────┘
               │                 │
               ▼                 ▼
        ┌────────────┐     ┌────────────┐
        │ PostgreSQL │     │   Redis    │
        │ 用户与审计 │     │ 会话与限流 │
        └────────────┘     └────────────┘
               │
               │ RS256 JWT / JWKS
               ▼
        ┌────────────────┐
        │ Business APIs  │
        └────────────────┘

快速开始

默认 Compose 会拉取固定版本的公开 GHCR 镜像，并创建独立的 PostgreSQL、Redis、JWT 密钥卷、 数据库迁移任务和 Auth Service，不依赖任何现有 Docker 网络或其他项目。

要求：Docker Engine 与 Docker Compose 2.20 或更高版本。

# 1. 克隆项目
git clone https://github.com/HyxiaoGe/auth-service.git
cd auth-service

# 2. 创建本地配置
cp .env.example .env

# 3. 生成数据库随机密码，将结果写入 .env 的 POSTGRES_PASSWORD
openssl rand -hex 32

# 4. 一次启动；JWT 密钥初始化和数据库迁移会在 auth 启动前自动完成
docker compose up -d

# 5. 查看状态
docker compose ps
curl http://localhost:8100/health

# 6. 可选：创建首个管理员和示例应用（不会生成固定密码）
AUTH_ADMIN_EMAIL=admin@example.com \
  docker compose exec -e AUTH_ADMIN_EMAIL auth \
  python scripts/init_admin.py

若希望从刚克隆的源码构建镜像，而不是拉取 GHCR 版本镜像：

docker compose -f compose.yaml -f docker-compose.build.yml up -d --build

默认配置不会启用 Google、GitHub、邮箱验证码或内部账密入口，因此无需真实第三方凭据 也能启动基础服务、查看 OpenAPI 和 JWKS。启用登录方式、配置反向代理以及生产加固请见 自托管指南。

服务启动后：

• API 文档：http://localhost:8100/docs
• 健康检查：http://localhost:8100/health
• JWKS：http://localhost:8100/.well-known/jwks.json

外部 PostgreSQL / Redis、密钥备份、反向代理和生产加固见 自托管指南。docker-compose.local.yml 仅作为 v1.0 命令的兼容入口； 项目维护者的现有 dev 部署继续显式使用 docker-compose.yml。

不克隆源码直接使用镜像

docker pull ghcr.io/hyxiaoge/auth-service:v1.1.0

镜像只包含认证服务，不内置 PostgreSQL 或 Redis。直接运行时必须先用同一镜像执行一次 python -m scripts.bootstrap，再让服务容器只读挂载同一个 /app/keys 持久卷；容器默认以 UID 10001 运行。完整的外部依赖、网络、端口和健康检查命令见 直接消费容器镜像。

业务项目接入

新应用接入分为三步：注册 client_id、接入客户端 SDK、实现登录与会话恢复。建议从 完整接入指南 开始；简版清单见 ONBOARDING，端点与 Token 契约见 认证契约，可复制示例见 examples/。

Python 后端

默认通过 PyPI 安装正式发行包：

pip install "seanfield-auth-client[fastapi]==0.3.1"

from auth_service_client import JWTValidator

validator = JWTValidator(
    jwks_url=f"{AUTH_URL}/.well-known/jwks.json",
    issuer=AUTH_URL,
    audience=CLIENT_ID,
    require_token_type="access",
)
user = validator.verify(token)

业务 API 必须校验 issuer、本应用的 audience 和 type=access，不能仅验证签名。 完整模式见 FastAPI 接入示例。

Next.js / React 前端

npm install auth-client-web@^0.4.0

import {
  configure,
  handleCallback,
  login,
  reconcileSession,
  resumeSession,
} from "auth-client-web"

configure({
  authUrl: AUTH_URL,
  clientId: CLIENT_ID,
  redirectUri: `${window.location.origin}/auth/callback`,
})

本地无票据时优先调用 resumeSession() 无跳转恢复中央 SSO 会话，首次冷启动也可使用 silentLogin() 顶层跳转探测；已登录页面在聚焦或 visibilitychange 时调用 reconcileSession() 对账中央账户。登录回调页调用 handleCallback() 完成 state 校验与 授权码换 Token。完整模式见 前端 SSO 接入示例。

auth-client-web 是无 UI 的浏览器认证 SDK，不提供登录弹窗、按钮或表单样式；应用负责 实现登录界面，并调用 SDK 与 Auth Service 的邮箱交互端点。

核心端点

方法	路径	说明
GET	/auth/authorize	Authorization Code + PKCE 授权入口
GET	/auth/capabilities	查询指定应用与 Origin 可用的登录能力
POST	/auth/email/headless/start	创建邮箱验证码授权事务
POST	/auth/email/headless/send	发送邮箱验证码
POST	/auth/email/headless/verify	验证邮箱验证码并返回一次性授权码
POST	/auth/session/reconcile	对账本地 token 与当前浏览器 SSO session
POST	/auth/session/resume	从当前浏览器 SSO session 无感恢复本地登录
POST	/auth/oauth/token	使用授权码与 PKCE verifier 换取 Token
GET	/auth/oauth/google	发起 Google 登录
GET	/auth/oauth/github	发起 GitHub 登录
POST	/auth/token/refresh	轮换 Refresh Token 并签发新 Token
POST	/auth/token/revoke	撤销 Refresh Token
POST	/auth/logout	兼容旧 SDK，仅完成安全回跳，不猜测或撤销当前中央会话
POST	/auth/logout/session	0.3+ SDK 按公开 session_id 严格定向登出
POST	/auth/logout/all	显式全设备登出
GET	/auth/userinfo	获取当前用户信息
GET	/.well-known/jwks.json	发布 JWT 验签公钥
GET	/health	进程健康检查

管理端点、完整请求字段和错误语义见 认证契约。

邮箱验证码登录

邮箱验证码支持新用户无密码注册与现有用户登录；相同规范化邮箱会复用统一用户身份。 该能力默认关闭。启用时至少需要：

• EMAIL_LOGIN_ENABLED=true 与不少于 32 字符的 EMAIL_CODE_PEPPER
• SMTP 或 Resend 投递配置
• 已注册且回调地址、CORS Origin 均精确匹配的应用
• 弹窗 JSON 流程还需 EMAIL_HEADLESS_LOGIN_ENABLED=true

生产 HTTPS 环境还必须配置精确的受信代理 CIDR。详细安全约束见 自托管指南。

技术栈

• FastAPI + Uvicorn
• PostgreSQL + SQLAlchemy 2.0（async）
• Redis（SSO 会话、授权事务、限流与撤销状态）
• Alembic 数据库迁移
• RS256 JWT / JWKS
• Docker Compose

开发验证

python -m pip install -r requirements-dev.txt
python -m pip install -e "./auth-client[fastapi]"
python -m pytest -q tests auth-client/tests
ruff check .

架构与编码约定分别见 docs/ARCHITECTURE.md 和 docs/CODING_CONVENTIONS.md。