选择接入方式

查看 Markdown

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

本页是受支持接入路径、公开服务调用方与协议职责的当前能力图谱。

选定协议路径后，请SDK 选择指南。Next.js、React Router、Nuxt 和 Django 服务端应用可以使用框架 SDK处理 Connect callback 和 session。如果你正在用 Connect 构建 Web 应用，请按照完成第一次登录从配置一直走到拿到 token。本页负责说明你需要哪种协议形状。

路径	适合场景	协议形状	从这里开始
Connect	Web 应用与自定义浏览器登录	`establish → authenticate → redeem → session`	完成第一次登录
OIDC	已支持 OpenID Connect 的框架或合作方系统	Authorization code + PKCE	OIDC 流程
设备码授权	CLI、启动器、终端工具，以及没有 client secret 的公共客户端	`device-authorize → 浏览器批准 → device-token`	设备码授权流程
原生 direct-issue	使用 Steam ticket、AccessKey 或 PublicKey 的游戏、桌面应用、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 票据。
POST /direct-issue/access-key —— AccessKey 标识符和密钥。
POST /direct-issue/public-key —— 签名的 Ed25519 断言。

AccessKey 和 PublicKey 支持账户、Agent 和 Automation 主体，各有独立的认证规则准入。这些端点使用各自的凭据证明，不要求应用 client-auth JWT。配置及 Errand 恢复见原生流程。

`oidc.sudomimus.com`

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

GET /.well-known/openid-configuration
GET /.well-known/webfinger
GET /.well-known/jwks.json
GET /authorize, POST /authorize
POST /token
GET /userinfo、POST /userinfo
GET /end-session, POST /end-session
POST /register
GET /register/{client_id}, DELETE /register/{client_id}
GET /claim-state, POST /claim-state

支持的 grant：authorization_code、implicit、refresh_token。机密客户端使用 private_key_jwt、client_secret_basic 或 client_secret_post；公开客户端使用 none。包含授权码的流程中，公开客户端必须使用 PKCE S256，机密客户端建议使用。纯 Implicit 忽略 PKCE。建议优先采用 Code + PKCE。详见 OIDC 流程。

一次典型请求的流向

下图把每条接入路径映射到它会使用的公开服务。采用浏览器轮询的原生客户端走 Connect 路径，而不是 Native direct-issue 路径。

flowchart LR
    subgraph Paths["接入路径"]
        Connect["Connect<br/>Web 应用与机密客户端浏览器轮询"]
        OIDC["OIDC<br/>接入方"]
        Device["设备码授权<br/>公共客户端"]
        Native["Native direct-issue<br/>Steam ticket 与 AccessKey"]
    end

    subgraph Surfaces["Sudomimus 公开服务"]
        ConnectAPI["connect-api.sudomimus.com"]
        SessionAPI["session-api.sudomimus.com"]
        Via["via.sudomimus.com"]
        DeviceAPI["device-api.sudomimus.com"]
        NativeAPI["native-api.sudomimus.com"]
        OIDCAPI["oidc.sudomimus.com"]
    end

    Connect -->|establish、redeem、status-poll| ConnectAPI
    Connect -->|托管认证| Via
    Connect -->|会话操作| SessionAPI

    Device -->|开启授权并轮询| DeviceAPI
    Device -->|浏览器批准| Via
    Device -->|初始签发后| SessionAPI

    Native -->|一次凭据交换| NativeAPI
    Native -->|初始签发后| SessionAPI

    OIDC -->|discovery、authorize、token、userinfo| OIDCAPI
    OIDCAPI -. 托管浏览器跳转 .-> Via

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

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