---
title: 选择接入方式
description: 在 Connect、OIDC、设备码授权与原生 direct-issue 之间做选择，并了解每条路径会使用哪些公开服务。
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Sudomimus 提供四条**并列的接入路径**。请按客户端形态与现有技术栈选择；它们彼此之间没有前置依赖。

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

:::tip[使用官方 Sudomimus CLI？]
上表是为“你正在开发的应用”选择接入路径。如果你想让 AI 助手或本地脚本操作 Sudomimus 自身，请使用 [Sudomimus CLI](/zh-cn/ai/cli/)。
:::

:::note[浏览器轮询属于 Connect，而不是 direct-issue]
桌面应用也可以打开系统浏览器，并通过 `STATUS_POLL` 使用 Connect。尽管客户端是原生应用，这仍然是 Connect 协议。原生应用章节会把它和 direct-issue 放在一起，方便桌面端集成方比较两种选择。
:::

:::note[设备码授权不是 Connect `STATUS_POLL`]
两者都可能长得像“原生客户端 + 浏览器”，但信任模型不同。Connect `STATUS_POLL` 从机密客户端签名的 `/establish` 开始；设备码授权从公共客户端无签名的 `/device-authorize` 开始，并要求应用配置 Layer 3 `DEVICE_CODE` ReturnRule。
:::

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

## 五个服务

| 域名 | 调用方 | 协议 |
|---|---|---|
| `connect-api.sudomimus.com` | 应用后端 | Connect 协议（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`
- **令牌操作**：`POST /refresh`、`POST /introspect`、`POST /logout`、`POST /revoke-all`

`/establish` 和 `/revoke-all` 需要用应用 client-auth 私钥签的 client-auth JWT（RS256，60 秒有效期，通过 `body_sha256` 与请求体绑定，通过 `jti` 防重放）。其余端点要么是自鉴权的（令牌本身就证明了对会话的操作权），要么是公开的（`/info`）。

端到端示例见 [Connect 流程](/zh-cn/connect/flow/)；令牌操作端点见 [管理会话](/zh-cn/guides/managing-sessions/)。

### `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 继续使用 Connect 令牌操作。详见[设备码授权流程](/zh-cn/device/flow/)。

### `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 各自就是凭据。详见 [原生流程](/zh-cn/native/overview/)。

### `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 流程](/zh-cn/oidc/flow/)。

## 一次典型请求的流向

走 Connect 协议的 Web 应用：

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

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

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

## 其余皆为内部

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