infra-sso 既是上游身份平台的 OAuth Client,也是下游业务系统的 Authorization Server / Identity Provider。
GitHub / QQ / 其他身份平台
│
│ OAuth 登录
▼
┌──────────────┐
│ infra-sso │
│ │
│ Portal │ 用户登录与账号管理
│ Admin │ 管理员控制台
│ OAuth/OIDC │ 对外提供统一认证
└──────┬───────┘
│
│ OAuth2 / OIDC
▼
Web App · Mobile · Desktop · API
对于同根域名下的站点,系统通过中心 API 管理 HttpOnly sso_session cookie,实现统一登录态;对于外部业务应用,则通过标准 OAuth2 授权码流程发放 token。
很多业务系统都需要登录,但每个系统重复实现账号、密码、第三方登录、会话吊销和多设备管理,会导致:
- 登录体验不一致
- 用户身份重复
- 密码和会话安全策略分散
- 接入新的业务系统成本高
infra-sso 将这些能力收敛到一个身份中心,并通过 OAuth2/OIDC 和 SDK 让业务系统以较低成本接入。
- GitHub OAuth、邮箱密码、邮箱验证码登录
- 多邮箱管理与邮箱验证
- 已登录用户绑定 GitHub 身份
- 查看活跃设备、IP、登录时间和最后活跃时间
- 踢下线指定设备或退出所有其他设备
- 修改密码后自动吊销其他会话
- 创建和管理自己的 OAuth 应用
client_secret创建/重置时明文返回,关闭后不可再次查看
Admin 控制台提供一个统一的运营视图:
- 仪表盘:用户、活跃会话、登录次数、OAuth 应用和最近活动
- 用户管理:搜索、角色调整、启用/禁用、用户详情
- OAuth 应用管理:查看所有接入应用并进行删除
- 会话管理:跨用户查看和强制踢下线
- 审计日志:记录登录与管理员操作
业务应用只需要注册一个 OAuth 应用,配置回调地址,然后使用 SDK 完成:
跳转 SSO → 获取 authorization code → 换取 token → 获取用户信息
系统采用 cookie-session + JWT 签证 的组合方式:
浏览器
│ HttpOnly sso_session cookie
▼
infra-sso API
├─ 验证 JWT 签名、issuer、过期时间
├─ 检查 Redis 中的 revoked:jti
└─ 通过 sessions 表管理设备元数据
JWT 是 cookie 中的签证格式,不是接入方的 client_secret。两者职责不同:
| 凭证 | 用途 |
|---|---|
sso_session |
浏览器会话,维持用户登录态 |
client_id |
标识一个 OAuth 接入应用 |
client_secret |
接入应用的密码,只用于安全换取 token |
access_token |
下游应用调用用户信息接口的访问凭证 |
refresh_token |
下游应用刷新 access token |
| 领域 | 方案 |
|---|---|
| 核心服务 | Rust、Axum、SQLx |
| 数据存储 | PostgreSQL、Redis |
| Web 前端 | React 19、TypeScript、Ant Design、Zustand |
| 构建体系 | Vite、pnpm workspace、Cargo workspace |
| 接入协议 | OAuth2、OIDC Discovery、PKCE 参数支持 |
| 反向代理 | Caddy、TLS、gzip/zstd |
| 本地证书 | mkcert |
| 密码安全 | Argon2 |
| 运行编排 | Docker Compose |
.
├── apps/
│ ├── portal/ # 用户门户:登录、账号设置、我的应用
│ └── admin/ # 管理后台:用户、应用、会话、审计
├── services/
│ └── sso-core/ # Rust SSO 核心服务
│ ├── migrations/ # SQLx 数据库迁移
│ └── src/
│ ├── handler/ # auth / oauth / admin / client handlers
│ ├── middleware/ # auth / CORS / rate limit / session
│ ├── provider/ # 上游身份平台适配器
│ ├── repository/ # 数据访问层
│ ├── route/ # 路由组合
│ ├── service/ # 认证、邮件、OAuth、会话业务
│ └── utils/ # JWT、加密、设备解析等工具
├── packages/
│ ├── vite-config/ # 共享 Vite 配置
│ └── sso-client/ # Node.js SDK:@luhanxin/sso-client
├── crates/
│ └── sso-client/ # Rust SDK:sso-client
├── examples/
│ └── express-demo/ # Express 接入示例
├── deploy/
│ └── k8s/ # Kubernetes manifests
│ ├── kustomization.yaml
│ ├── postgres.yaml
│ ├── redis.yaml
│ ├── sso-core.yaml
│ ├── portal.yaml
│ ├── admin.yaml
│ └── ingress.yaml
├── Caddyfile # 多域名反向代理与 TLS 配置
├── docker-compose.yml # 完整环境编排
├── Cargo.toml # Rust workspace
├── pnpm-workspace.yaml # pnpm workspace
└── Makefile # 常用命令入口
| 站点 | 用途 | dev | Docker / prod |
|---|---|---|---|
| Portal | 用户登录与账号管理 | https://sso.luhanxin.com:5173 |
https://sso.luhanxin.com |
| Admin | 管理员控制台 | https://admin.sso.luhanxin.com:5174 |
https://admin.sso.luhanxin.com |
| API | SSO 核心服务 | https://api.sso.luhanxin.com:8080 |
https://api.sso.luhanxin.com |
- Rust toolchain
- Node.js 22+
- pnpm
- Docker Desktop
- mkcert
make setup
make setup-hosts
make gen-certs首次启动前,可在 .env 中配置首个管理员:
ADMIN_BOOTSTRAP_EMAIL=admin@example.com
ADMIN_BOOTSTRAP_PASSWORD=change-me-123两个变量必须同时设置。服务仅在数据库中不存在管理员时创建或提升该账号,后续重启不会重置密码。
本地开发中,Vite 和 Rust 服务直连,方便 HMR 和调试;PostgreSQL、Redis 由 Docker 提供。
make up
make migrate
# 分别启动 API、Portal、Admin
make dev
pnpm --filter @app/portal dev
pnpm --filter @app/admin dev完整环境由 Caddy、Portal、Admin、SSO Core、PostgreSQL 和 Redis 组成:
make up-fullCaddy 负责统一 TLS 和反向代理,前端容器使用 nginx 提供静态资源,并启用 gzip、长期缓存和 SPA fallback。
Kubernetes 部署使用 deploy/k8s,由 Ingress Controller 统一处理 TLS 和域名路由;PostgreSQL、Redis 使用 StatefulSet + PVC,SSO Core 启动时执行已编译进二进制的数据库迁移。
# 1. 准备集群、Ingress Controller,并构建本地镜像
make k8s-images
# kind 需要额外加载镜像;minikube 使用 minikube image load
kind load docker-image infra-sso/sso-core:dev infra-sso/portal:dev infra-sso/admin:dev
# 2. 从本地 .env 创建 Secret,并创建 mkcert TLS Secret
# .env 可配置 ADMIN_BOOTSTRAP_EMAIL / ADMIN_BOOTSTRAP_PASSWORD
make k8s-secret
make k8s-tls
# 3. 部署
make k8s-apply
make k8s-statusKubernetes 模式下 TLS 在 Ingress 终结,sso-core 通过集群内 HTTP Service 暴露;Caddy 只用于 Docker Compose 环境。
登录 Portal → 账号设置 → 我的应用 → 创建应用。
填写:
- 应用名称
- 一个或多个精确的回调地址
系统会生成:
client_id
client_secret # 只在创建/重置时显示一次
普通用户只能查看和管理自己创建的应用,管理员可以在 Admin 控制台查看全部应用。
业务应用
│ GET /oauth/authorize
│ client_id + redirect_uri + state
▼
infra-sso
│ 用户已登录:直接签发 code
│ 用户未登录:跳转 SSO 登录,完成后回到授权流程
▼
业务应用 callback
│ POST /oauth/token
▼
access_token + refresh_token + id_token
│ GET /oauth/userinfo
▼
当前用户信息
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /.well-known/openid-configuration |
OIDC 服务发现 |
| GET | /oauth/authorize |
授权端点 |
| POST | /oauth/token |
code / refresh token 换令牌 |
| GET | /oauth/userinfo |
获取用户信息 |
| POST | /oauth/revoke |
撤销令牌 |
| GET | /oauth/jwks |
JWKS 端点(当前 HS256 返回空 key set) |
pnpm --filter @luhanxin/sso-client buildimport {SsoClient} from '@luhanxin/sso-client';
import {createAuthMiddleware} from '@luhanxin/sso-client/express';
const sso = new SsoClient({
domain: 'https://api.sso.luhanxin.com',
clientId: 'app_xxx',
clientSecret: process.env.SSO_CLIENT_SECRET!,
redirectUri: 'https://example.com/auth/callback'
});
const tokens = await sso.exchangeCode(code);
const user = await sso.getUserInfo(tokens.access_token);
app.use('/api', createAuthMiddleware(sso));use sso_client::{SsoClient, SsoClientOptions};
let sso = SsoClient::new(SsoClientOptions {
domain: "https://api.sso.luhanxin.com".into(),
client_id: std::env::var("SSO_CLIENT_ID")?,
client_secret: std::env::var("SSO_CLIENT_SECRET")?,
redirect_uri: "https://example.com/auth/callback".into(),
});
let tokens = sso.exchange_code(&code).await?;
let user = sso.get_user_info(&tokens.access_token).await?;export SSO_CLIENT_ID=app_xxx
export SSO_CLIENT_SECRET=your-secret
pnpm --filter @example/express-demo dev示例代码位于 examples/express-demo,包含登录跳转、回调换 token、用户信息、Bearer 中间件、刷新和登出流程。
- 页面级 KeepAlive:切换 admin/portal 页面时保留组件状态
- 页面激活事件:页面重新出现时按 stale time 判断是否刷新
visibilitychange/online:浏览器恢复可见或网络恢复时按需更新- React.lazy:页面按需拆包
- Rollup vendor 拆分:React、Ant Design、Router 独立缓存
- nginx 静态资源
immutable缓存 - Caddy gzip/zstd 压缩
- 统一
#dacad2莫兰迪粉主题
- OAuth
state使用 HMAC-SHA256 签名,防止 CSRF 和参数篡改 - cookie 使用
HttpOnly,前端 JavaScript 无法直接读取会话签证 SameSite、CORS 和 credentials 按站点白名单配置- 密码使用 Argon2 哈希,不保存明文
- client secret 只保存 SHA-256 哈希
- Redis 即时吊销被踢下线的会话
- 注册、登录等敏感操作使用独立限流
- 审计日志记录登录和管理员操作
- 用户 OAuth 应用通过
owner_id做数据隔离 - 禁止管理员通过普通用户接口越权删除其他用户的应用
make help
make up # PostgreSQL + Redis
make up-full # 完整 Docker 环境
make migrate # 执行迁移
make check # cargo check
make clippy # Rust 静态检查
make fmt # Rust 格式化
make lint # Biome 检查
make typecheck # TypeScript 类型检查
make build # Rust + 前端构建
make down # 停止容器- 上游第三方登录目前以 GitHub 为主,QQ 接入正在推进,飞书等 Provider 后续扩展。
- SDK 当前提供 Node.js 和 Rust;Go SDK 暂不纳入当前版本。
- 当前 OAuth token 签名使用 HS256;未来可升级 RS256 + JWKS,让接入方进行本地验签。
