Themis 作为独立 OIDC 服务
已有身份系统、需要把 Themis 接成外部 OIDC 提供方时读这一份。只做标准部署可以跳过。
← 文档索引
Themis 作为独立 OIDC 服务
themis-auth 不只是 Agentic Hat 的登录后端,它本身是一个标准 OIDC Provider(IdP)。装好
Themis 之后,同一套账号可以接给您的其它应用——内部管理台、移动端、合作方系统——不用每个
应用各建一套用户表。
这一章是「把它当 IdP 用」的完整清单:对外端点、安装顺序、最小配置、RP 注册、接入流程与 验收方法。逐服务的完整部署步骤仍在「路径 B:逐服务手动部署」里, 本章不重复数据库初始化和探针这些内容。
对外端点
RP 只通过一个公开 origin 访问 IdP;五条端点由 themis-web 同源透传、themis-gateway
转发到内网的 themis-auth:
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /.well-known/openid-configuration |
发现文档,RP 的配置来源 |
| GET | /jwks |
公钥集,用于验证 id_token 签名 |
| GET | /authorize |
授权入口(浏览器整页跳转) |
| POST | /token |
授权码换取令牌、刷新令牌 |
| GET | /logout |
RP 发起的登出(浏览器整页跳转) |
所有端点 URL 由 OIDC_ISSUER 推导,因此它必须逐字等于浏览器看到的 origin:
https://accounts.titanides.com,带协议、不带尾斜杠。写错不会在启动时报错,只会让 RP 在验 iss
时失败——这是接入时最常见的一处。
/authorize与/logout是 302 跳转,不是 JSON API。网关必须把它们放在REDIRECT_PROXIES,否则 302 会被当成响应体吞掉,浏览器停在空白页。
安装顺序
三个服务,顺序固定,缺一不可:
| 顺序 | 服务 | 在 OIDC 链路里的角色 | 详细步骤 |
|---|---|---|---|
| 1 | themis-auth |
签发方。持有数据库、签名私钥和 RP 白名单,永远不出内网 | 见 themis-auth 小节 |
| 2 | themis-gateway |
唯一对外入口。验签,并把五条端点原样转发 | 见 themis-gateway 小节 |
| 3 | themis-web |
身份域名的登录/注册页 + 同源透传层 | 见 themis-web 小节 |
即使只把 Themis 当 IdP 用、不跑 Agentic Hat,这三个也必须一起装:OIDC 的 issuer 是一个
公开域名,而按设计 themis-auth 本身不暴露。themis-web 不是可选的「登录皮肤」——未登录
访问 /authorize 时,浏览器要落到它的登录页;同一个域名下的五条端点也靠它转发。
注册、找回密码这些能力还依赖 rhea-email(配置项 EMAIL_SERVICE_URL)。如果账号全部由
外部导入、不需要自助注册,该变量可以留空(不阻止启动),但登录页的「注册 / 忘记密码」
入口会不可用。
最小配置
以下是「作为 IdP 跑起来并接入一个 RP」必须设置的变量。未列出的沿用默认值;完整变量表见 各服务小节。
themis-auth
| 变量 | 值 |
|---|---|
DATABASE_URL |
PostgreSQL 连接串 |
OIDC_ISSUER |
https://accounts.titanides.com |
OIDC_CLIENTS |
RP 白名单 JSON,见下一节 |
LOGIN_URL |
https://accounts.titanides.com/login——themis-web 的登录页,不带语言前缀,中间件会补 |
IDP_SESSION_SECRET |
随机会话密钥;无默认值,缺失时应用拒绝启动 |
JWT_PRIVATE_KEY_PATH |
ES256 签名私钥文件路径 |
JWT_PUBLIC_KEY_PATH |
对应的公钥文件路径 |
OIDC_KEY_ID |
JWKS 里的 kid,签名与公钥必须一致;默认 fewbox |
IDP_SESSION_TTL_SECONDS |
会话 cookie 有效期,默认 7 天 |
AUTH_CODE_TTL_SECONDS |
授权码有效期,默认 60 秒 |
ID_TOKEN_EXPIRES_IN |
id_token 有效期,默认 1h |
JWT_EXPIRES_IN / REFRESH_TOKEN_EXPIRES_IN |
access token 默认 24h,refresh token 默认 7d |
密钥对用 openssl ecparam -name prime256v1 ... 生成,完整命令见 themis-auth 小节的
「生成密钥对」。
themis-gateway
| 变量 | 值 |
|---|---|
AUTH_OIDC_ENDPOINT |
{"protocol":"http","host":"themis-auth","port":80},不带 basePath |
JWT_PUBLIC_KEY_PATH |
与 auth 同一把公钥(验 access token) |
JWT_VERIFY_ALGORITHM |
ES256 |
REDIRECT_PROXIES |
/authorize、/logout |
POST_PROXIES |
/token |
GET_PROXIES |
/jwks、/.well-known/openid-configuration |
CORS |
允许直连 token 端点的浏览器来源;纯后端换令牌时不需要 |
五条端点必须显式写 publicPath,否则默认路径会变成 /auth_oidc/authorize 这类,客户端
按发现文档找不到:
REDIRECT_PROXIES=[{"endpoint":"AUTH_OIDC","path":"authorize","publicPath":"/authorize"},{"endpoint":"AUTH_OIDC","path":"logout","publicPath":"/logout"}]
POST_PROXIES=[{"endpoint":"AUTH_OIDC","path":"token","publicPath":"/token"}]
GET_PROXIES=[{"endpoint":"AUTH_OIDC","path":"jwks","publicPath":"/jwks"},{"endpoint":"AUTH_OIDC","path":".well-known/openid-configuration","publicPath":"/.well-known/openid-configuration"}]
themis-web
| 变量 | 值 |
|---|---|
GATEWAY_ENDPOINT |
http://themis-gateway |
themis-web 的透传路径是镜像内的固定清单,不是配置项。升级网关白名单却不升级
themis-web 镜像,新端点会落到 Next 自己的 404。
注册一个 RP
RP(relying party)= 要接入的客户端应用。注册就是往 OIDC_CLIENTS 里加一项:
[
{
"client_id": "<rp-client-id>",
"redirect_uris": ["https://titanides.com/auth/callback"],
"post_logout_redirect_uris": ["https://titanides.com/"],
"name": "<RP 标注名>"
}
]
规则:
client_id由 RP 自己定,在本 IdP 内唯一;RP 发起授权时原样带回。redirect_uris逐字精确匹配,scheme、主机、端口、路径、尾斜杠都算。不做前缀或通配 匹配——松一档就是开放重定向。post_logout_redirect_uris最好显式写。不写时退回到「已注册redirect_uris的同源 根」,等于允许该域名下任意路径作为登出落点;新接入请写死具体页面。- 所有 RP 都是公共客户端,没有
client_secret。安全性由 PKCE(S256)保证,RP 必须每次 生成新的code_verifier,不能写死。 - 留空或 JSON 解析失败 = 没有任何可用客户端,
/authorize一律返回unauthorized_client。 - 注册表在进程内只读一次。改完
OIDC_CLIENTS要重启themis-auth,没有热加载。
RP 侧接入流程
发现。
GET https://accounts.titanides.com/.well-known/openid-configuration,确认issuer与 配置一致,从文档里取三个端点(authorization_endpoint、token_endpoint、jwks_uri)。 不要把端点硬编码进 RP。发起授权。浏览器整页跳转到:
https://accounts.titanides.com/authorize
?client_id=<rp-client-id>
&redirect_uri=https://titanides.com/auth/callback
&response_type=code
&scope=openid
&state=<每次随机的防 CSRF 串>
&nonce=<每次随机的防重放串>
&code_challenge=<BASE64URL(SHA-256(verifier))>
&code_challenge_method=S256
response_type 只支持 code;scope 必须包含 openid;code_challenge_method 必须是
S256。任何一项不对,IdP 会带 error 回跳(unsupported_response_type / invalid_scope /
invalid_request)。
未登录时,IdP 302 到 LOGIN_URL,并把整个授权请求塞进 continue 参数;登录成功后回到
/authorize 继续。RP 不需要处理这段中间过程。
授权成功后,浏览器被送回 redirect_uri,参数是 code、原样带回的 state,以及 iss。
先校验 state,再校验 iss 等于 OIDC_ISSUER。
- 换取令牌。在 RP 后端
POST /token,Content-Type: application/x-www-form-urlencoded:
curl -s -X POST https://accounts.titanides.com/token \
-d grant_type=authorization_code \
-d code='<授权码>' \
-d redirect_uri='https://titanides.com/auth/callback' \
-d client_id='<rp-client-id>' \
-d code_verifier='<第 2 步的原始 verifier>'
redirect_uri 必须与授权时逐字一致,client_id 也必须一致。授权码一次性,默认 60 秒
过期;重放同一个码返回 invalid_grant。
成功响应:
{
"access_token": "<ES256 JWT>",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "<不透明字符串>",
"id_token": "<ES256 JWT>"
}
- 验证
id_token。用/jwks里的公钥验签,并检查:iss等于 issuer、aud等于自己的client_id、exp未过期、nonce等于第 2 步发出去的值。当前id_token只包含sub(用户 ID)、aud、iss、nonce、exp、iat——没有姓名和邮箱,见「能力边界」。
access_token 用同一把密钥签名,负载里带 id、username、roles、org_ids;它没有
iss / aud,是给业务后端识别用户和权限用的,不要当标准 OIDC 令牌交给第三方验。
刷新。
POST /token,表单参数grant_type=refresh_token、refresh_token、client_id。 刷新会轮换:旧 refresh token 立即作废,响应里给新的一对。RP 要原子地替换本地存储, 并处理「替换失败、旧令牌已失效」的回退路径(让用户重新登录)。登出。RP 先清自己的本地会话,然后让浏览器整页导航到:
https://accounts.titanides.com/logout
?id_token_hint=<id_token>
&post_logout_redirect_uri=https://titanides.com/
&state=<可选>
id_token_hint 只用于识别是哪个 RP,过期也接受;没有 id_token 的客户端可以改用
client_id。post_logout_redirect_uri 必须在白名单里,否则 IdP 只清会话、不跳转,返回一个
「已退出」页面。
这一步必须是整页导航——会话 cookie 是 HttpOnly + SameSite=Lax,只有身份域名自己的响应
能清掉它。用 fetch 调 /logout 看着返回 200,实际什么也没发生。
验收清单
接入前,按顺序跑一遍;任何一项不过,先解决再往下:
- 发现文档 200,
issuer与OIDC_ISSUER逐字一致。 /jwks返回一把kty=EC、alg=ES256、带kid的密钥。- 未登录访问
/authorize(参数完整)→ 302 到登录页,continue里带着原请求。 - 登录后回到
/authorize→ 302 到redirect_uri,带code、state、iss。 - 用授权码换令牌成功;同一个码再换一次返回
invalid_grant。 id_token用 JWKS 验签通过,nonce/aud/iss全部对上。- 刷新一次成功,旧 refresh token 立即失效。
- 登出后再访问
/authorize,需要重新登录(说明会话确实被清掉)。 - 把
redirect_uri改成未注册地址,/authorize应直接 400,不能发生跳转。
能力边界
以下是当前版本明确不做的事。它们是接入方案要绕开或等后续版本的部分,不是配置错了:
| 缺什么 | 现在的影响 | 变通 |
|---|---|---|
没有 userinfo 端点 |
id_token 只有 sub,RP 拿不到姓名、邮箱、头像 |
把 sub 当本地用户 ID;资料走自己的业务接口(如管理 GraphQL) |
scope 不裁剪 claims |
申请 profile / email 也不会多返回任何字段 |
目前只发 openid,不要依赖其它 scope |
| 发现文档字段不全 | 缺 userinfo_endpoint、scopes_supported、claims_supported、token_endpoint_auth_methods_supported |
自动配置的客户端若强校验这些字段,需手工填端点 |
| refresh token 明文入库 | 数据库泄露等于 refresh token 泄露;也没有重用检测 | 按密钥级别保护数据库;缩短 REFRESH_TOKEN_EXPIRES_IN |
| 没有撤销 / 内省端点 | RP 无法单独作废某个 token;停用账号只在下一次签发时生效 | 登出走 /logout;管理端禁用用户后,access token 最多活到 JWT_EXPIRES_IN |
| 没有 consent 页 | 授权即同意,用户看不到 scope 清单 | 接入前自行在 RP 侧做说明 |
不支持 prompt / max_age / login_hint / ui_locales / response_mode |
做不到静默续期、强制重新认证、指定登录账号 | 需要重新认证时,先 /logout 再发起授权 |
| 只有公共客户端 | 不支持 client_secret,后端服务也只能用 PKCE |
RP 后端同样按 PKCE 实现,不要假设有 secret |
| CORS 全放开 | 任意 origin 可直连 /token(虽然仍需 PKCE 和授权码) |
生产在网关收窄允许来源 |
OIDC 响应无 Cache-Control: no-store |
共享缓存环境可能缓存令牌响应 | 在网关给 /token 响应补该头 |
这些边界会随版本收敛;接入方案如果依赖其中某项,请先和我们确认目标版本。