omni-auth 是 OmniRoute 本地或远程 AI 网关中的认证管理技能，聚焦 API 密钥认证与会话令牌管理，可作为接入 OmniRoute API 的起点。
用途 该技能面向两类认证场景：远程 API 请求使用 Bearer 凭据；仪表盘登录则使用管理密码换取会话 Cookie。它帮助使用者厘清二者差异，并完成登录、登出等认证流程。
主要能力
- Bearer 认证：所有请求以 ${OMNIROUTE_URL}/v1/... 形式发起，并携带 Authorization: Bearer ${OMNIROUTE_KEY}。
- 密码登录：POST /api/auth/login 接收管理密码，返回 auth_token 会话 Cookie。
- 登出：POST /api/auth/logout，需先通过 GET /api/auth/csrf 获取 CSRF 令牌，并在请求头 x-omniroute-csrf 中携带。
- CSRF 与状态查询：GET /api/auth/csrf 获取令牌，GET /api/auth/status 查询认证状态。
- OIDC 登录：GET /api/auth/oidc/login 根据配置的 OIDC issuer/client 构建授权 URL，设置短时 oidc_state Cookie 并重定向；GET /api/auth/oidc/callback 校验 state Cookie、交换授权码、依据 issuer 的 JWKS 验证 ID token（audience 为 client id），并检查 token 的 sub/email 是否在 oidcAllowedSubjects 中（该列表至少需一项，空列表返回 not_configured）。成功后签发与密码登录相同的 30 天 auth_token 仪表盘会话 JWT，并重定向至 /dashboard。
- 启用 OIDC 期间，密码登录仍作为回退方式保留。
使用方式 先设置环境变量：export OMNIROUTE_URL="http://localhost:20128" 与 export OMNIROUTE_KEY="sk-..."（密钥来自 Dashboard → API Keys）。随后可用 curl $OMNIROUTE_URL/api/health 验证，返回 {"ok":true} 即连通。登录示例：curl -X POST http://localhost:20128/api/auth/login -H "Content-Type: application/json" -c cookie.jar -d '{"password":"<management-password>"}'。登出与 OIDC 流程均提供了对应 curl 命令；请求与响应的详细 schema 可参考 GET /api/openapi/spec 或 docs/openapi.yaml。
适用场景 适用于为 OmniRoute 部署配置访问控制、通过管理密码或 OIDC 登录仪表盘、以 API 密钥调用网关接口等场景。
限制 资料未提供收费、价格与平台支持范围等信息。错误处理方面：401 需刷新 OMNIROUTE_KEY；400 Invalid model format 需检查模型是否存在于对应 /v1/models/<kind>；503 表示上游提供方熔断，需按 Retry-After 重试；429 为限流，需遵守 Retry-After。