开始使用 Signet

这份指南是写给对接方开发者的：您要将既有的应用接上已经部署好的 Signet。若您要找服务器运维与部署文档（启动服务器、环境变量、密钥生成等），请参考项目 README。

审计页面（/admin/audit 与 /account/audit）始终使用游标式“上一页／下一页”导航，不显示总条数或页码。仅含旧式 ?page=N 的网址会打开第一个游标页面；现有游标链接仍可使用。已移除的 AUDIT_CURSOR_PAGINATION_ENABLED 环境变量不再生效。JSON API 保留 offset 分页与总条数。运维文档请参考项目 README。

Signet 是一个 OAuth 2.0 + OpenID Connect 授权服务器，会签发令牌（token）给您的应用，用于认证用户与调用受保护的 API。

选择流程

您的应用类型	建议流程
服务器端网页应用（有后端）	Authorization Code + PKCE（机密客户端）
单页应用（React / Vue / Svelte 等）	Authorization Code + PKCE（公开客户端）
移动或桌面应用	Authorization Code + PKCE（公开客户端）
CLI 工具、IoT 设备、无头环境（SSH、容器）	Device Authorization Grant
后端服务调用另一个服务（无用户）	Client Credentials
跑不了任何流程的 script、CI job、cron	个人 API 密钥（`sgk_`）

还没头绪？任何「有用户」的场景请用 Authorization Code + PKCE，「服务对服务」请用 Client Credentials。个人 API 密钥是最后手段，给完全跑不了任何流程的调用端 — 它拿短命 token 与离线验证换来「一行 curl 就能跑」。

对接之前

向 Signet 管理员索取：

Base URL — 例如 https://your-signet。其他信息都可以从 BASE_URL/.well-known/openid-configuration 发现（见下节）。
client_id — 标识您的应用。
client_secret — 只有机密客户端才会拿到（服务器端网页应用、Client Credentials 服务）。公开客户端（SPA、移动、CLI）没有 secret。
允许的 redirect URI — Authorization Code Flow 会用到。Signet 做 完全字符串比对：https://yourapp.example/cb 与 https://yourapp.example/cb/ 是不同的。
允许的 scope — 此客户端可请求的 scope 子集（例如 openid、profile、email、offline_access）。管理员也可能注册了自定义的 API scope，请向管理员询问。
启用的 grant type — 此客户端开启了 Device Flow / Auth Code Flow / Client Credentials 中的哪几种。
Resource 标识符 — _除非您在集成 MCP server 或多 RS 部署且需要 audience binding（RFC 8707），否则略过此项_。要带入 resource= 的绝对 http(s) URI，这样签发的 access token 的 aud 才会等于您的 resource server。每个值都必须由管理员加进您客户端的 allowed-resources 白名单 — 它 默认全部拒绝，所以白名单为空的客户端，送任何 resource= 都会得到 invalid_target。

从这里开始：OIDC Discovery

不要把端点 URL 写死，改成抓取 OIDC Discovery 文档：

curl https://your-signet/.well-known/openid-configuration

{
  "issuer": "https://your-signet",
  "authorization_endpoint": "https://your-signet/oauth/authorize",
  "token_endpoint": "https://your-signet/oauth/token",
  "userinfo_endpoint": "https://your-signet/oauth/userinfo",
  "revocation_endpoint": "https://your-signet/oauth/revoke",
  "jwks_uri": "https://your-signet/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "grant_types_supported": [
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:device_code",
    "refresh_token",
    "client_credentials"
  ],
  "claims_supported": [
    "sub",
    "iss",
    "aud",
    "exp",
    "iat",
    "jti",
    "auth_time",
    "nonce",
    "at_hash",
    "name",
    "preferred_username",
    "email",
    "email_verified",
    "picture",
    "updated_at"
  ],
  "code_challenge_methods_supported": ["S256"],
  "authorization_response_iss_parameter_supported": true
}

多数成熟的 OAuth / OIDC 库可以直接读取这份文档并自动把流程接起来。

几个需要注意的细节：

jwks_uri 与 id_token_signing_alg_values_supported 只在 Signet 配置为 RS256/ES256（非对称签名）时才会出现。HS256 部署会省略这两个字段。
/oauth/introspect 与 /oauth/device/code 有支持，但 未在 Discovery 声明，请直接使用本指南列出的路径。
scopes_supported 只列出内建的 OIDC scope（openid、profile、email）。offline_access 以及管理员为某客户端注册的任何 自定义 API scope，即使没在这里声明，被请求时仍会被接受 — 请向管理员确认哪些适用。

非 OIDC / MCP 客户端：Signet 也在 /.well-known/oauth-authorization-server 发布一份 RFC 8414 授权服务器 metadata，会声明 resource_indicators_supported: true 与 device_authorization_endpoint，是 MCP 与纯 OAuth 2.1 客户端惯用的版本。两份文档重叠字段内容相同；根据您库的需求挑一份即可。

支持的 scope

Scope	用途
`openid`	要拿到 ID token 与使用 `/oauth/userinfo` 的必要条件
`profile`	在 UserInfo / ID token 中解锁 `name`、`preferred_username`、`picture`、`updated_at`
`email`	在 UserInfo / ID token 中解锁 `email`、`email_verified`
`offline_access`	表示您想拿到 refresh token（OIDC Core §11）

注意事项：

openid 与 offline_access 在 Client Credentials 流程中 不合法，会被拒绝。
客户端只能请求管理员为其注册过的 scope。
scope 以空白分隔字符串传送（scope=openid profile email）。

令牌速览

流程成功后，Signet 会签发：

Access token — JWT；短效；带在 API 调用的 Authorization: Bearer <token> 中。
Refresh token — 不透明；较长效；拿到 /oauth/token 换取新的 access token。
ID token — 关于用户的 JWT（只有 scope 包含 openid 时才会有）。详见 OpenID Connect。

Access token 的生命周期会依每个客户端的配置而异（short ≈ 15 分钟、standard ≈ 10 小时、long ≈ 24 小时）。请一律看 token response 的 expires_in 字段，绝对不要写死时间。

在 token 请求带 resource=<URL> 时，access token 的 aud claim 会绑到该 resource（RFC 8707）— 前提是该值在您客户端的白名单内（默认全部拒绝）。Resource server 应对自己的标识符验证 aud — 见 JWT 验证 §Audience Binding。

速率限制、撤销、反查、refresh rotation：请见 Token 与撤销。

最小对接检查清单

[ ] 与管理员确认 BASE_URL、client_id、（必要时）client_secret、redirect URI、scope。
[ ] 启动时抓一次 /.well-known/openid-configuration 并缓存。
[ ] 选一个流程并实现（见下方各流程文档）。
[ ] 在 resource server 以 JWKS 验证 token（JWT 验证）。
[ ] 处理常见的 OAuth 错误（错误处理）。
[ ] 实现登出：以 refresh token 调用 /oauth/revoke（Token 与撤销）。
[ ] 如果是公开且长效的客户端，使用 PKCE（Signet 只接受 S256）。

下一步

Authorization Code Flow + PKCE — 网页、SPA、移动应用
Device Authorization Flow — CLI 与无头客户端
Client Credentials Flow — 服务对服务
API 密钥 — 给跑不了流程的 script 与 CI 用的不透明 sgk_ 密钥
OpenID Connect — ID token 与 UserInfo
JWT 验证 — 在 resource server 验证 access token
Token 与撤销 — 刷新、撤销、反查
错误处理 — OAuth 错误码与对应做法