如果你的应用已实现标准 OIDC 客户端（授权码 + PKCE + state / nonce），目前连接其他身份服务，迁到本平台通常 只需改配置，无需改动代码。本页说明迁移可行的原因与注意事项。
适用场景：应用已具备"授权码流程 → 换 token → 调 userinfo 获取用户信息"的标准实现。
为什么能只改配置#
本平台的协议端点与主流 OIDC 服务同构，标准客户端库（openid-client、requests-oauthlib、各语言 SDK）均按发现端点或显式 URL 配置工作。若你的实现满足以下条件，迁移等同于更换三个端点 URL 与一组凭据：
- 授权码流程带 PKCE，或至少带
state校验； - 通过
userinfo端点获取用户信息，而非依赖某 IdP 特有的字段； - 回调地址固定且可精确配置。
迁移步骤#
1. 取得本平台凭据#
按接入指南创建应用，取得 client_id 与 client_secret（secret 仅在创建时显示一次）。
2. 修改配置#
| 配置项 | 原值 | 新值 |
|---|---|---|
| 授权端点 | 原 IdP 的 /authorize | https://mooc.pneumas.org/oauth/authorize |
| 令牌端点 | 原 IdP 的 /token | https://mooc.pneumas.org/oauth/token |
| 用户信息端点 | 原 IdP 的 /userinfo | https://mooc.pneumas.org/oauth/userinfo |
| 发现端点（可选） | 原 IdP 的 discovery | https://mooc.pneumas.org/.well-known/openid-configuration |
client_id / client_secret | 原凭据 | 本平台凭据 |
| scope | 原值（通常已含 openid profile email） | 保持不变，按需追加 group、member_groups |
3. 核对字段映射#
本平台 userinfo 返回标准字段：
| 字段 | 用途 |
|---|---|
sub | 用户 ID 字符串，作为本地用户主键（稳定，不随改名变化） |
name | 显示名 |
preferred_username | 用户名 |
email / email_verified | 邮箱与验证状态 |
picture | 头像 |
group（申请该 scope 时） | 绑定群的成员身份与角色 |
member_groups（申请该 scope 时） | 用户在群内的全部应用成员组 |
若原实现从 userinfo 读取的是自定义字段名（如 id、user_login），迁移时将字段映射改为上表即可。
权益联动（可选）#
应用的高级功能可对应平台群里的 应用成员组（成员组），两侧双向同步：
① 登录方向（平台 → 应用）
用户登录 → 应用调 userinfo（scope 含 member_groups）
→ 取得应用成员组 → 映射为应用的功能开关
② 管理方向（应用 → 平台）
用户升级 / 降级 → 应用服务器用 client_credentials 调应用成员组管理 API
→ 将该用户加入 / 移出对应应用成员组 → 平台同步课程权益
→ 用户下一次刷新 userinfo 即看到新应用成员组
实现上：登录请求的 scope 带上 member_groups；创建应用时勾选 client_credentials（获得 members:read + member_groups:write）；在升级 / 降级逻辑中调用 POST /oauth/members/{user_id}/member-groups/{group_id} 或 /move。
管理 API 只能操作 已是群成员 的用户。被移出群的用户只能展示访客状态，不能通过 API 重新加回群——加人进群是群管理员在平台侧的操作。
迁移后验证清单#
- 用户用平台账号登录应用成功，显示名与头像正确；
- 用不在绑定群内的平台账号登录，userinfo 返回
is_member=false，应用显示访客视图； - 将用户移出群后，其在应用的会话于下次刷新时失效（
invalid_grant）； - 应用通过管理 API 将用户加入"高级会员"应用成员组后，平台群管理页面可见；
- 用户撤销对该应用的授权后，应用侧立即失去该用户。