AuthRouter：统一 OIDC 登录入口

## AuthRouter简介

最近，我在自建服务中发现，各个应用（如 Wiki、博客、Mailcow 等）都有各自的登录方式。一些应用支持 Google 登录，有些则只支持标准 OIDC，更有些即使支持 OIDC，但账号字段又不一致。为了解决这个困扰，我开发了一个轻量的自托管 SSO 中间件：**AuthRouter**。

- **GitHub**：[AuthRouter 项目地址](https://github.com/YIYI-16/AuthRouter)
- **Docker 镜像**：`ghcr.io/yiyi-16/authrouter:latest`

这个项目采用 MIT License，欢迎体验、反馈问题或提交 PR。如果该项目能为你带来帮助，欢迎给个 Star 表示支持！

## 它的功能

简单来说，AuthRouter 是连接登录账号与自建应用的桥梁：

```text
Google / GitHub / Keycloak / Azure AD / Authentik ...
|
OIDC / OAuth2
v
AuthRouter
|
标准 OpenID Connect
v
Mailcow / Wiki / Blog / 自建服务 ...
```

在与上游系统对接时，AuthRouter 扮演 OIDC / OAuth2 Client；对下游应用则是一个标准 OIDC Provider。这样，一旦集成 AuthRouter，后续如需更换登录方式（如 Google、GitHub 等），只需在 AuthRouter 中进行修改，所有下游应用无需个别调整。

## 目前支持的功能详解

- 支持多个标准 OIDC 上游，并可自动发现 Issuer 端点。
- 支持通用 OAuth2 上游，可手动配置授权、令牌、用户信息及邮箱接口。
- 提供一个 Web 管理面板，便于在不修改配置文件的情况下管理上游 IdP、下游客户端及身份映射。
- 配置变更后无需重启容器即可即时生效。
- 为每个下游应用生成独立的 Client ID 和 Client Secret。
- 支持 `client_secret_post` 与 `client_secret_basic`。
- 支持 SQLite 和 MySQL，个人部署无需额外数据库准备。
- 自动生成并持久化 JWKS、加密密钥及 Session 签名密钥。
- 上游仅一个时可直接跳转；多个上游则提供登录方式选择页。
- 提供标准的 Discovery、Authorization、Token、UserInfo 和 JWKS 端点。
- 提供 `/health` 健康检查接口。

## 实用功能：按应用映射身份

AuthRouter 除了可以直接透传账号外，还支持对不同下游应用进行不同身份的映射。例如，使用 `yourname@gmail.com` 登录：
- 进入 Mailcow 时，映射为 `postmaster@example.com`；
- 进入 Wiki 时继续使用原始 Gmail 邮箱。如果一个来源账号配置了多个目标身份，登录过程中会显示账号选择页面。映射规则基于“下游客户端 + 上游登录源 + 上游身份”生效，而未配置映射时，则进行直接透传。

## Docker 快速部署指南

需准备域名和 HTTPS 反向代理。由于公网 OIDC 登录依赖正确的 Issuer 和安全 Cookie，不建议使用单纯 IP + HTTP 部署。

```bash
docker run -d \
--name authrouter \
--restart unless-stopped \
-p 127.0.0.1:3000:3000 \
-e SSO_BASE_URL=https://sso.example.com \
-e ADMIN_PASSWORD='请替换为足够长的随机密码' \
-v sso-data:/app/data \
ghcr.io/yiyi-16/sso:latest
```

这款镜像由 GitHub Actions 构建并发布，目前同时支持 `linux/amd64` 和 `linux/arm64`。

你也可以通过源码使用 Docker Compose 部署：

```bash
git clone https://github.com/YiYi-16/AuthRouter.git
cd AuthRouter
cp .env.example .env

# 编辑 .env 并设置 SSO_BASE_URL 和 ADMIN_PASSWORD

docker compose up -d --build
```

Nginx 反向代理的核心配置示例如下，完整的 `nginx.conf` 示例也在仓库中提供：

```nginx
location / {
proxy_pass http://127.0.0.1:3000;
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 X-Forwarded-Host $host;
}
```

启动后可先进行检查：

```bash
curl https://sso.example.com/health
curl https://sso.example.com/.well-known/openid-configuration
```

然后访问管理界面 `https://sso.example.com/admin` 进行以下操作：
1. 添加一个上游 OIDC 或 OAuth2 登录源；
2. 在上游平台登记回调地址：`https://sso.example.com/sso/{provider_id}/callback`；
3. 创建下游 OIDC 客户端并保存显示一次的 Client Secret；
4. 将 Discovery URL、Client ID 和 Client Secret 填入下游应用；
5. 从下游应用发起完整的登录测试。当下游应用支持自动发现时，仅需使用：
```text
https://sso.example.com/.well-known/openid-configuration
```
手动配置时，对应端点见下表：

| 配置项 | 地址 |
| --- | --- |
| Issuer | `https://sso.example.com` |
| Authorization Endpoint | `https://sso.example.com/auth` |
| Token Endpoint | `https://sso.example.com/token` |
| UserInfo Endpoint | `https://sso.example.com/me` |
| JWKS URI | `https://sso.example.com/jwks` |
| Scopes | `openid email profile` |

## Database选择：SQLite与MySQL

默认使用 SQLite，数据库保存于 `/app/data/sso.db`，适合个人和单机环境。如果已具备 MySQL，可通过环境变量切换：

```dotenv
DB_DRIVER=mysql
MYSQL_HOST=mysql.example.internal
MYSQL_PORT=3306
MYSQL_USER=sso
MYSQL_PASSWORD=replace-with-a-database-password
MYSQL_DATABASE=sso
```

应用会自动创建必要的表格，然而需提前创建 MySQL 数据库和相应用户。无论使用何种数据库，都应持久化并备份 `/app/data`，因为 JWKS、加密密钥和 Session 密钥也一并存储在此。

## 当前版本能力边界

当前版本仍在完善阶段，主要聚焦于个人、小团队及可信网络内的自托管场景，目前需注意：
- 仅建议单实例部署，管理员 Session 和部分授权状态存于内存中，多副本状态共享尚未实现；
- 服务重启时，进行中的授权流程会中断，需从下游应用重新发起登录；
- 管理面板的 MFA、精细权限和审计日志尚未实现；
- TLS 终止未集成，需结合 Nginx、Caddy 或 Traefik 使用；
- 自动备份与密钥轮换尚未实现，需自行备份数据库及 `/app/data`。

如果你面临多副本高可用、完整审计等需求，可以考虑 Keycloak 或 Authentik 等成熟选项，而 AuthRouter 更适合解决个人服务的统一登录与身份转换场景。