---
name: pilotus-oidc-integration
description: Use when a developer asks to add Sign in with PILOTUS, connect a web, mobile, or desktop app to auth.pilotus.studio, or prepare a PILOTUS OIDC client application. 适用于接入 PILOTUS 账号登录、配置 OIDC 回调或申请客户端。
---

# 接入 PILOTUS 账号登录

PILOTUS 使用 Keycloak 提供 OpenID Connect（OIDC）。应用将用户引导到 PILOTUS 登录页，收到授权码后换取令牌，再建立自己的应用会话。

- Issuer `https://auth.pilotus.studio/realms/pilotus`
- [OIDC Discovery](https://auth.pilotus.studio/realms/pilotus/.well-known/openid-configuration)

应用配置固定的 issuer，通过 Discovery 获取授权、换令牌、UserInfo 和 JWKS 地址。保持 HTTPS 证书校验。用户在 PILOTUS 页面输入账号和密码。

## 准备客户端申请

先读目标项目的登录和会话实现，确定应用类型与实际回调路径。每个应用、每个环境使用独立的客户端。已经有客户端时，核对登记内容与本次用途是否一致。

缺少客户端时，按下列字段生成 YAML 申请。根据项目填写已知字段，未知处明确标注待补。正式入口是 [PILOTUS 开发者站](https://developer.pilotus.studio/)。有浏览器权限且开发者授权提交时，可以代填表单。PILOTUS 登录由账号持有人完成，提交前核对回调、环境和所需字段。也可以将 YAML 交给开发者登录后粘贴提交。提交后保存详情链接，在「我的接入申请」查看意见与状态。申请退回补充时，在原单修改并重提。门户当前使用浏览器表单。审批期间可以完成本地实现和模拟测试，将真实登录标为待验证。

```yaml
app_name: <用户看到的应用名称>
app_url: <应用首页>
owner_contact: <负责人的工作邮箱或其他可核实联系方式>
environment: <test 或 production>
client_type: <web-backend、spa 或 native>
redirect_uris:
  - <完整回调 URI>
requested_scopes:
  - openid
scope_purposes:
  openid: 使用 PILOTUS 身份建立应用会话
eligible_users: <所有可登录的 PILOTUS 账户，或指定资格及核验方式>
# privacy_policy_url: https://example.org/privacy
```

回调地址列出完整协议、域名和路径。Web 回调使用 HTTPS，禁止通配符。原生 App 可提交 HTTPS、反向域名 scheme 或 loopback IP 回调，在资格说明旁的申请沟通中说明平台和 SDK。测试与生产环境分别申请。默认请求 `openid`。确实需要姓名或邮箱时，再申请 `profile` 或 `email` 并解释用途。隐私政策地址可省略。审批通过后，管理员在 Keycloak 开通客户端，详情变为「已开通」并显示 `client_id`。客户端密钥经独立渠道交付，申请单和审核意见均只记录配置元数据。

## 实现应用侧登录

1. 优先用项目现有的成熟 OIDC SDK，配置 Authorization Code Flow 和 PKCE `S256`，为每次登录生成并校验 `state` 和 `nonce`。有后端的 Web 应用由后端换码并从密钥管理读取 secret。SPA 或原生 App 使用批准的 public client，原生 App 通过系统浏览器登录。
2. 使用 SDK 校验 ID Token 签名、issuer、audience、有效期和 nonce，按 OIDC 规则处理多受众。用 `(iss, sub)` 绑定应用账户，应用权限由自身规则授予。需要从 UserInfo 取字段时，确认其 `sub` 与 ID Token 一致。现有账号关联走应用已有的账号绑定流程，避免仅凭邮箱自动合并。
3. PILOTUS 自助新注册只允许 `hust.edu.cn`。开发者站接受已验证的校园邮箱，以及经管理员确认并按账号 ID 放行的早期第三方注册外域账号。外部合作方可由符合该规则的内部对接人代提交。接入的应用执行其审批确认的用户资格规则。若规则是已验证校园邮箱，检查 `email_verified` 为真且域名精确匹配 `hust.edu.cn`，并申请邮箱字段。需要在校状态等额外资格时，向 PILOTUS 管理员确认可用凭据。
4. 对接 PILOTUS 业务 API 需要单独申请对应资源、audience 和 scope。ID Token 用于应用登录。业务 API 按自身规范接收并校验限定受众和权限的 access token。使用已经批准的凭据和测试账号验证，避免记录口令、密钥、授权码和令牌。

## 验收和交接

先在本地验证成功回调、用户拒绝、无效或过期的登录事务、会话创建和权限默认值。取得获批测试客户端后，在允许的回调地址用真实 PILOTUS 登录复验，并核对发给应用的 claims 和适用的资格校验。交付时列出应用改动、所需环境变量名、待审批配置和实际测试结果。以管理员确认的客户端配置和已完成的端到端测试为接通依据。

规范参考：[OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html) · [OAuth 2.0 安全最佳实践](https://www.rfc-editor.org/rfc/rfc9700.html) · [原生 App OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8252.html)
