Skip to content
lhx-spacePublic

About

Rust 统一 SSO 认证服务,支持 Github / 微信 / QQ / 飞书 OAuth2,提供 SDK 快速接入

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

infra-sso logo

infra-sso

一个面向多站点与业务应用的自托管统一身份认证平台

Rust · Axum · React · TypeScript · OAuth2/OIDC · Docker · Caddy

让登录只发生一次,让身份在可信的边界内流动。

项目定位

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

两个变量必须同时设置。服务仅在数据库中不存在管理员时创建或提升该账号,后续重启不会重置密码。

本地 dev

本地开发中,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

完整 Docker 环境

完整环境由 Caddy、Portal、Admin、SSO Core、PostgreSQL 和 Redis 组成:

make up-full

Caddy 负责统一 TLS 和反向代理,前端容器使用 nginx 提供静态资源,并启用 gzip、长期缓存和 SPA fallback。

本地 Kubernetes

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-status

Kubernetes 模式下 TLS 在 Ingress 终结,sso-core 通过集群内 HTTP Service 暴露;Caddy 只用于 Docker Compose 环境。

OAuth2 / OIDC 接入流程

1. 创建 OAuth 应用

登录 Portal → 账号设置 → 我的应用 → 创建应用。

填写:

  • 应用名称
  • 一个或多个精确的回调地址

系统会生成:

client_id
client_secret  # 只在创建/重置时显示一次

普通用户只能查看和管理自己创建的应用,管理员可以在 Admin 控制台查看全部应用。

2. 授权流程

业务应用
  │ 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
  ▼
当前用户信息

3. 主要端点

方法 路径 说明
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)

SDK

Node.js

pnpm --filter @luhanxin/sso-client build
import {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));

Rust

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?;

Express 示例

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,让接入方进行本地验签。

About

Rust 统一 SSO 认证服务,支持 Github / 微信 / QQ / 飞书 OAuth2,提供 SDK 快速接入

Topics

Resources

Stars

5 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages