选择接入方式

查看 Markdown

Sudomimus 提供四条并列的初始签发路径。请按客户端形态与现有技术栈选择；它们彼此之间没有前置依赖。初始签发完成后，普通应用会话统一使用 Session API 做 refresh、introspect、logout 与 revoke-all。

选定路径后，大多数集成都应该从选择 SDK 继续。SDK 页面会把每条路径对应到 TypeScript、Python、C# 包；本页负责说明你需要哪种协议形状。

路径	适合场景	协议形状	从这里开始
Connect	Web 应用与自定义浏览器登录	`establish → authenticate → redeem → session`	Connect 流程
OIDC	已支持 OpenID Connect 的框架或合作方系统	Authorization code + PKCE	OIDC 流程
设备码授权	CLI、启动器、终端工具，以及没有 client secret 的公共客户端	`device-authorize → 浏览器批准 → device-token`	设备码授权流程
原生 direct-issue	使用 Steam ticket 或 AccessKey 的游戏、桌面应用、CLI 与服务	一次凭据交换；需要补救时可进入浏览器 errand	原生流程

四条路径通过六个公开服务暴露。共享的浏览器服务是 via.sudomimus.com：Connect、OIDC、设备批准和原生 errand 共用的托管浏览器界面。

六个服务

域名	调用方	协议
`connect-api.sudomimus.com`	应用后端	Connect inquiry 协议（JSON over HTTPS）
`session-api.sudomimus.com`	应用后端、公共客户端、服务端 BFF	普通应用会话生命周期（JSON over HTTPS）
`via.sudomimus.com`	浏览器中的最终用户	托管认证页面（仅浏览器）
`device-api.sudomimus.com`	公共客户端（CLI、启动器、共享设备）	设备码授权（JSON over HTTPS）
`native-api.sudomimus.com`	原生客户端（桌面应用、游戏、CLI）	一次性 direct-issue（JSON over HTTPS）
`oidc.sudomimus.com`	OIDC 接入方	OpenID Connect 1.0

`connect-api.sudomimus.com`

由应用后端调用的 HTTPS API。它承载：

认证请求生命周期：POST /establish、POST /redeem、POST /status-poll、POST /info

/establish 需要用应用 client-auth 私钥签的 client-auth JWT（RS256，60 秒有效期，通过 body_sha256 与请求体绑定，通过 jti 防重放）。其余端点要么是公开的（/info），要么由三密钥兑换过程本身鉴权。

端到端示例见 Connect 流程。

`session-api.sudomimus.com`

由持有普通应用 token 的后端、BFF 或公共客户端调用的 HTTPS API。它承载登录之后的会话生命周期：

POST /refresh 轮换 refresh token 并签发新的 access token。
POST /introspect 查询 access token 背后的 refresh-token 会话是否仍 active。
POST /logout 结束单个 refresh-token 会话。
POST /revoke-all 结束某账户在调用应用下的全部会话。

/refresh、/introspect 和 /logout 由提交的 token 自鉴权。/revoke-all 需要 client-auth JWT，签名方式与 Connect /establish 相同，但 aud = "sudomimus-session"。详见管理会话。

`via.sudomimus.com`

这是承载用户认证流程的托管网页，包括通行密钥提示、邮箱验证码输入和平台登录等界面。应用将用户跳转到 via.sudomimus.com，并在 URL 中携带 exposure-key。用户完成挑战后，平台会按照认证请求指定的返回方式将控制权交还给应用。

via.sudomimus.com 面向用户。你的代码不会直接调用它的端点——它只把用户送过去。

`device-api.sudomimus.com`

面向无法安全保存应用 client-auth 私钥的公共客户端。它承载：

POST /device-authorize —— 开启短暂的设备码会话，返回 { deviceCode, userCode, verificationUri, verificationUriComplete, expiresIn, interval }。
POST /device-token —— 用 deviceCode 轮询，直到浏览器里的用户批准、拒绝，或会话过期。

/device-authorize 不需要 client-auth JWT。应用通过 Layer 3 DEVICE_CODE ReturnRule 选择开放这条路径，用户在 via.sudomimus.com 中完成普通 Sudomimus 认证。/device-token 成功后，后续 refresh、logout、introspect、revoke 继续使用 Session API。详见设备码授权流程。

`native-api.sudomimus.com`

为无法承载浏览器跳转的原生客户端提供两个一次性端点：

POST /direct-issue/steam-ticket —— 携带 Steamworks ticket 的游戏直接换取 { accessToken, refreshToken }。
POST /direct-issue/access-key —— 携带预签发 AccessKey 凭据的 CLI 或服务直接换取 { accessToken, refreshToken }。

两个端点都不需要 client-auth JWT —— Steam ticket 和 AccessKey secret 各自就是凭据。详见原生流程。

`oidc.sudomimus.com`

这是标准的 OpenID Connect 提供方，包含以下端点：

GET /.well-known/openid-configuration
GET /.well-known/jwks.json
GET /authorize（强制 PKCE，仅支持 S256）
POST /token
GET /userinfo、POST /userinfo
GET /end-session

支持的 grant：authorization_code、refresh_token。支持的客户端认证：private_key_jwt、client_secret_basic、client_secret_post（机密客户端可选项）以及 none + PKCE（公开客户端选项）。详见 OIDC 流程。

一次典型请求的流向

走 Connect 协议的 Web 应用：

   浏览器 ─────────────────► via.sudomimus.com
                                │
                                ▼  用户完成挑战
                                │
                            confirmation-key
                                │
应用后端 ─────────────────► connect-api.sudomimus.com
                                │
                                ▼
                        返回签名后的令牌
                                │
                                ▼
                    应用后端验证令牌（通过 Session JWKS）

浏览器与应用后端分别和不同的服务通信。Sudomimus 在平台内部关联两条链路，因此应用无需直接处理用户的认证凭据。

走设备码授权的公共 CLI 从 device-api 开始，把用户送到 via.sudomimus.com/device，然后继续轮询 device-api，直到批准返回令牌。走 Steam direct-issue 的游戏把整个流程压缩成对 native-api 的一次往返。OIDC 接入方只与 oidc.sudomimus.com 通信；用户在底层仍然通过 via.sudomimus.com 认证，但接入方看不到这一层。

其余皆为内部

以上六个服务是仅有的受支持集成入口。Sudomimus 还运行其他内部服务，但它们无法从平台外部访问。如果某项流程未通过上述服务公开，就不能作为外部集成入口使用。