区分登录客户端与上游凭证
同名的 client_id 属于不同认证流程，应分别注册和填写；以下域名均需替换。Hub 用户 Token 的 audience 是完整 server.public_url，管理员 Token 的 audience 是 admin.public_url，二者不能互换。
| 用途 | 配置位置 | 注册回调示例 |
|---|---|---|
| 员工 CLI 登录 Hub | CLI 的 --client-id |
http://127.0.0.1:PORT/oauth/callback |
| 普通用户门户 | client_authorization.client_id |
https://hub.example.com/client-auth/auth/callback |
| 管理员浏览器登录 | admin.client_id |
https://admin.example.com/auth/callback |
| Hub 向企业 SSO 验证身份 | auth.sso.upstream.client_id |
https://hub.example.com/sso/callback |
| 用户连接上游业务账号 | backends[].credentials.oauth.client_id |
https://hub.example.com/client-auth/api/accounts/callback |
backends[].oauth 是 Hub 自己的服务账号 OAuth client_credentials，没有浏览器回调；credentials.oauth 是用户个人授权，两者互斥。Hub 的 required_scopes 和上游的 oauth.scopes 分别由各自身份服务解释，不会自动映射或相互授予。
auth
默认内建模式可在管理台的 身份服务 页面配置 LDAP 与 OIDC，密钥加密保存在管理数据库，保存立即生效。首次 UI 保存后，数据库连接设置优先于 auth.sso.upstream；以下 YAML 身份源设置仍属于需重启的静态配置。
| 字段 | 默认/要求 | 说明 |
|---|---|---|
mode |
builtin（默认模板） |
内建账号；企业身份源可选。高级外部验证使用 external。 |
issuer |
内建模式自动推导 | 从 server.public_url 的 HTTPS origin 推导为 /sso；不要求 issuer 环境变量。外部模式必须配置 HTTPS issuer。 |
sso |
可选 | 内建模式可添加 upstream 企业身份源或额外公开客户端；默认注册 MCPBridge、门户和管理台。见内建账号与 SSO。 |
enterprise_membership_max_age |
24h |
企业组关系的最长验证有效期，范围 1m–720h；过期要求重新登录或同步目录。本地账号不受此期限影响。 |
管理数据库中的权限组来源为 mcphub:permissions，source_groups 映射稳定的 LDAP/OIDC 组织组 ID。权限组 API 的 permissions.scope_mode: derived 在保存时编译所选能力的 Scope 快照，explicit 保留手动配置。通过管理台或 API 配置这些权限，不在启动 YAML 中添加用户授权。见组与权限。
内建模式要求管理存储。账号权限与会话由 Hub 检查，密码重置、停用和 MFA 绑定会撤销凭证。普通密码认证没有 MFA 标记。以下 discovery/JWKS 要求针对 external 验证模式。
JWT 必须满足以下条件：签名和 iss 由该 issuer 验证；aud 必须包含完整的 server.public_url（包含路径）——aud 为字符串时必须等于 public_url，为数组时必须包含 public_url；必须有非空 sub 和 exp；nbf（如有）也会校验。过期、未生效和 OIDC 时间比较允许 30 秒时钟偏差。只有在 OIDC discovery 成功、jwks_uri 是绝对 HTTPS URL，且可达的 JWKS 响应至少包含一个可解析、有效且非对称的公开验证密钥后，verifier 才会 ready；对称 oct 密钥以及无效或空 key 均不满足此条件。首次成功刷新前 MCP 入口返回 503；ready 后 discovery 或 JWKS 刷新暂时失败会保留 last-known-good verifier。OIDC discovery 和 JWKS 响应分别限制为 1 MiB。
JWKS ready 还要求至少一个可用 key：use 为空或为 sig；存在 key_ops 时必须包含 verify；显式 alg 必须匹配 OIDC discovery 宣告的支持 RSA、EC 或 Ed25519 JWS 算法。若 discovery 未宣告 id_token_signing_alg_values_supported，则按 RS256。同一 JWKS 中的坏 key 或不支持 key 不会遮蔽其他可用 key。
scope 取自 JWT 的 scope 和 scp 两个 claim：scope 只接受空格分隔字符串（包括空字符串或 JSON null）；scp 接受空格分隔字符串或字符串数组。两个 claim 的值会合并、去重；数组项不能包含空白。后端访问采用 all-of 语义：required_scopes: [a, b] 要求 token 同时拥有 a 和 b；缺任一项，该后端不会出现在该 token 的目录视图中，对已识别的直接调用返回 403 insufficient_scope。未配置 required_scopes 的后端不受 scope 限制。Protected Resource Metadata 的 scopes_supported 是所有后端 required scope 的去重并集。
用户 CLI 的外部 OIDC 注册
以下要求适用于直接使用外部 issuer 的部署；启用 auth.sso 时按 SSO 指南登记 MCPHub 自己的公开客户端。完成后，将 MCP 地址、client ID 和必要的固定回调端口交给用户。
先在该身份服务注册一个 公开原生 OAuth 客户端，启用授权码、refresh token、PKCE S256，以及 token endpoint 的 none 认证方式。允许回调 http://127.0.0.1:<port>/oauth/callback；支持原生客户端的服务可允许随机回环端口，否则注册固定端口并传入 --callback-port 8765。Discovery 必须声明支持 S256。身份服务签发的 JWT access token 必须包含完整 MCPHub 公开 URL（含 /mcp）作为 audience，并携带 sub、exp 和所需 scope。本机无需保存 client secret。