Files
sso/source/conf/nginx.conf
T
ssw c8a02b8c49 feat: 从网关项目剥离为独立 SSO 统一认证服务
定位:身份层(IdP + IAP),不含动态域名转发 / LLM 上游代理 / 用量计费。

代码(source/rust,nginx 动态模块 + Rust,单进程零外部依赖)
- IdP:authorization_code(含 PKCE)/ refresh_token / client_credentials / password
  四种 grant,含 discovery / introspect / userinfo / jwks 占位
- IAP:access 阶段门禁,注入 X-Auth-* 到后端,客户端伪造同名头被覆盖
- MaxKey 互通:/oauth/v20/* 与 /oauth2.0/* 别名 + context-path 归一化 + 扁平字段
- 管理接口:账号(含角色/部门/用户组)与 OAuth 接入方注册表,热写穿共享内存
- 模块改名 ngx_http_sso_module,指令 sso_state / sso_data_dir / sso_api / sso_iap,
  Cookie sso_sid(终端用户)与 sso_admin_session(管理员)两套身份两套会话

配置(source/conf)
- nginx.conf 生产模板(TLS、IAP 子域、含 auth_sub 的日志格式)
- nginx.test.conf 本机验证配置(明文 18095-18099)
- tls/README.md 证书约定与公钥比对校验

前端(source/www/admin.html)
- 三 tab:账号管理 / 接入方 / 接入指南;去掉审核队列、域名、LLM 上游、用量统计

测试与脚本
- tests/ 三套端到端:协议基线 14 项 · MaxKey 互通与接入 24 项 · 管理接口 31 项,全绿
- tests/demo-system 演示业务系统(Python 标准库),覆盖应用自建客户端与 IAP 零改造两种姿势
- scripts/run-local-e2e.sh 本机一键起停;scripts/seed-data.sh 物化运行时数据目录

文档
- README.md 概览与快速开始;CLAUDE.md 硬约定与排障速查
- docs/design.md 完整设计;docs/roadmap.md 待执行任务(v2 RS256+JWKS、用户管理界面)
2026-09-12 21:42:06 +08:00

164 lines
7.0 KiB
Nginx Configuration File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ============================================================================
# SSO 统一认证网关 —— 生产配置模板
#
# 两个 server,对应两层能力:
# sso.<域名> IdP + 管理台:签发令牌、管理账号与接入方
# *.<域名>(或 *.<子域>)IAP:转发前完成认证并注入 X-Auth-*
#
# 部署前必须替换:域名、证书路径、上游 proxy_pass 地址、OAUTH_* 环境变量。
# 本文件**不参与**本机 e2e(那是 conf/nginx.test.conf)。
#
# 阶段处理器注册在 http 级,靠 `sso_api` / `sso_iap` 两个开关按 location 收敛:
# 少了开关,管理台自己也会被 IAP 门禁 401 掉。
# ============================================================================
load_module /usr/local/nginx/modules/libsso_gateway.so;
worker_processes auto;
error_log /usr/local/nginx/logs/error.log info;
pid /usr/local/nginx/logs/nginx.pid;
# nginx 会剥掉所有环境变量,机制类配置必须显式白名单。
# 未设置时不报错,模块按各自缺省值兜底(见 source/rust/src/config.rs)。
env ADMIN_INIT_PASSWORD; # 播种管理员口令,仅首次启动用
env OAUTH_SIGNING_SECRET; # HS256 对称密钥;不设则每次重启令牌全失效
env OAUTH_ISSUER; # 令牌 iss 与 discovery 的 issuer,必须等于对外访问地址
env OAUTH_COOKIE_DOMAIN; # 跨子域 SSO 用,如 .example.com
events {
worker_connections 2048;
}
http {
include mime.types;
default_type application/json; # 业务侧默认 JSON,HTML 在对应 location 单独覆盖
# 转发 location 里的 `proxy_set_header Connection $connection_upgrade` 依赖此变量;
# 缺它 nginx -t 直接报 unknown "connection_upgrade" variable,服务起不来。
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# $auth_sub 来自模块注入(access 阶段)。没有它,日志里只能看到「谁被拦了」,
# 看不到「谁访问了哪个后端」——排查越权时这两个信息缺一不可。
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" "$http_user_agent" '
'"$http_x_forwarded_for" "$upstream_addr" auth_sub=$auth_sub';
access_log /usr/local/nginx/logs/access.log main;
sendfile on;
keepalive_timeout 65;
# ========== 共享内存(管理会话 / SSO 会话 / 授权码 / 接入方注册表)==========
# 一张表按前缀共用,容量实测约 124 B/条,10m 足够放约 8 万条。
sso_state state 10m;
sso_data_dir /usr/local/nginx/data;
# 可选 TLS:conf/tls/ 下放任意 *.conf(完整的 443 server 块)即启用对应域名的 HTTPS。
# 目录为空时 include 空匹配,不影响启动。说明见 conf/tls/README.md
include /usr/local/nginx/conf/tls/*.conf;
# ==================================================================
# IdP + 管理台
#
# 一个 server 同时承载授权端点与管理接口:接入方与终端用户访问的是同一份
# issuer,分成两个域名会让 discovery 文档里的地址与 Cookie 作用域都不一致。
# ==================================================================
server {
listen 443 ssl;
http2 on;
server_name sso.example.com;
ssl_certificate /usr/local/nginx/conf/tls/example.com/fullchain.cer;
ssl_certificate_key /usr/local/nginx/conf/tls/example.com/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 2m;
client_body_buffer_size 1m;
# 管理台单页(只读静态资源,数据全部走 /api/admin/*)
location = /admin {
default_type text/html;
alias /usr/local/nginx/www/admin.html;
}
location = /admin/ {
default_type text/html;
alias /usr/local/nginx/www/admin.html;
}
location = / {
return 302 /admin;
}
# 其余全部交给模块分发。**不要**逐条列 location:
# 除标准端点外还有 MaxKey 别名(/oauth/v20/*、/oauth2.0/*)以及带
# context-path 的写法(/maxkey/oauth/v20/*,模块内做前缀归一化),
# 逐条列举必然漏,漏掉的表现是接入方拿到 HTML 404。
location / { sso_api on; }
}
# 明文 80 只做跳转,避免用户在浏览器里手敲地址后停在错误页
server {
listen 80;
server_name sso.example.com;
return 301 https://$host$request_uri;
}
# ==================================================================
# IAP:受保护的业务系统
#
# 应用完全不写认证代码,只读 X-Auth-* 头。
# 后端地址按环境写死(本项目不做动态上游路由——那是流量层网关的职责)。
# 多后端时按 server/location 拆分即可,不要引入动态变量:
# 那样会把「谁能在哪台机器上开洞」变成运行时数据。
# ==================================================================
server {
listen 443 ssl;
http2 on;
server_name app.example.com;
ssl_certificate /usr/local/nginx/conf/tls/example.com/fullchain.cer;
ssl_certificate_key /usr/local/nginx/conf/tls/example.com/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
# 门禁:access 阶段判定身份,未登录 → 401 → error_page 跳登录页
sso_iap on;
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# ---- 身份注入:网关断言覆盖客户端伪造同名头 ----
# 后端只信这五个头。它们由模块在 access 阶段写入(见 lib.rs set_auth_vars)。
proxy_set_header X-Auth-User $auth_user;
proxy_set_header X-Auth-Email $auth_email;
proxy_set_header X-Auth-Groups $auth_groups;
proxy_set_header X-Auth-Sub $auth_sub;
proxy_set_header X-Auth-Token $auth_token;
proxy_connect_timeout 5s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
}
error_page 401 = @oauth_login;
location @oauth_login {
return 302 "https://sso.example.com/login?redirect=$scheme://$host$request_uri";
}
}
# 明文 80 跳转(同 IdP)
server {
listen 80;
server_name app.example.com;
return 301 https://$host$request_uri;
}
}