Gerege SSO¶
Production · 第 2 层 — 认证 / SSO ·
仓库：sso-gerege-mn · sso.gerege.mn
民商线的 OAuth2 / OpenID Connect 提供方。生态系统内的应用与第三方依赖方 （RP）都在这里完成公民登录。
Nexus 上的 Gerege SSO 是另一回事
2026 年 8 月，从 Gerege Nexus 分叉出了一个名为
sso-gerege-nexus 的新仓库，它同样叫作「Gerege SSO」。本页所述行为描述的是
production 上运行的 sso-gerege-mn 代码。新分叉尚无自己的域名，因此
sso.gerege.mn 上的契约没有变化——RP 无需做任何调整。
三项职责¶
1. 身份提供方¶
RP 可以提供 Sign in with Gerege。支持的能力：
| 能力 | 说明 |
|---|---|
| Authorization code + PKCE (S256) | 主流程；对公开客户端同样安全 |
| 轮换式 refresh token | 带重用检测——旧令牌被再次使用时会作废整条链 |
client_credentials |
机器对机器集成 |
| Access token | 不透明（opaque）——内容对 RP 不可见 |
id_token |
使用 RS256 签名的 JWT |
| Discovery | /.well-known/openid-configuration |
| UserInfo | /userinfo |
2. eID 代理¶
应用从不直接访问 eID Mongolia。SSO 会代理获授权的 eID 服务，并只转发给已注册的应用。
原因在于：这样 eID 凭据只存在于一处，审计链路也保持为单一链条。若把 eID 凭据 分发给每个应用，轮换、吊销以及追溯"谁做了什么"都将无从谈起。
3. 应用注册的唯一场所¶
OAuth client 与 client secret 只在这里创建，也只保存在这里。 即便是 Developer Portal 也不创建 client——它只说明该怎么做， 并深链接到 SSO 控制台。
为什么只能有一处？
如果凭据同时存在于两套系统，迟早会产生分歧：一侧已删除的 client 在另一 侧仍能使用，secret 轮换传不到对面，诸如此类。除了单一来源之外，没有别的 可靠办法。
登录方式¶
| 方式 | 说明 |
|---|---|
| eID | 主要方式——二维码 / 移动端 deep-link / 按登记号推送 |
| 辅助方式——首次绑定必须经 eID 核验，以便对应到真实自然人 |
没有密码。 也没有邮箱/OTP 登录。这是有意为之：不存在的密码不会泄露。
周边服务¶
同一仓库下运行的相关网关：
-
dan.gerege.mn—— DAN 身份识别网关。 -
gsign.gerege.mn—— 签名网关。 -
xyp.gerege.mn—— 法人/工商登记查询。
会话与登出¶
- 会话由 JWT access + refresh 一对令牌承载；refresh 会轮换。
- 登出会同时作废 refresh 与 access（access 拒绝名单）。
- 登出后用户会回到其发起时所在的域名，而不会被抛到
/login。这条规则 保证不会打断 RP 的用户流程。
一段架构史——摆脱 Hydra¶
SSO 此前使用 Ory Hydra 作为 OIDC 提供方。如今该依赖已被彻底移除，所需机制
改写为自研 Go 代码（usecases/oidc）。原本独立的 Hydra 数据库也已并入主库。
结果是：
- 外部依赖减少一项；
- 原先的两个数据库、两条迁移链合并为一；
- OIDC 的行为由自己掌控（特别是可以与 eID 流程紧密衔接）。
与平台同一份代码¶
SSO 并非另行编写的系统——它运行在与平台模板完全相同的代码基座上。唯一的区别
是一项配置：AUTH_MODE=provider 时登录卡片显示在本地；为 client 时则跳转到
上游 SSO。同一个 Docker 镜像可启动为其中任一角色。
接入（成为 RP）¶
大致步骤：
- 注册应用——在 SSO 控制台创建 client，取得
client_id/client_secret。redirect URI 必须精确登记。 - 读取 discovery——从
/.well-known/openid-configuration获取各 endpoint。 - 实现 authorization code + PKCE 流程。
- 换取令牌——code → access + refresh +
id_token。 - 校验
id_token——RS256 签名、iss、aud、exp。 - 获取用户信息——
/userinfo。
详细流程与检查清单请见认证与授权页面。
redirect URI 必须精确登记
这是 OIDC 中最常见的错误。redirect URI 必须逐字符吻合——结尾的 /、
http 与 https 之别、端口，全都重要。变更域名时若忘记更新这份清单，
登录就会悄无声息地失败。
详细文档¶
实现层面的文档（endpoint 结构、数据库模型、RP 注册的管理手册）位于
sso-gerege-mn 仓库内。