对接方式总览（统一接口标准）
云集生态唯一官方接口标准 = OAuth 2.1 + OIDC。本文说明为什么它是首选，并对比所有可用的接入方式（REST / 二维码直出 / SDK / iframe），多种方式是标准之上的灵活备选，而非另立标准。
一句话结论
云集生态（UM / 开放平台 / 所有家族产品）的唯一官方接口标准 = OAuth 2.1 + OpenID Connect (OIDC)。
- 对内（家族产品互相对接）：这是唯一固定标准，长期不变、统一维护，覆盖网站 / APP / 小程序。
- 对外（第三方接入）：同样以 OAuth 2.1 为官方推荐；同时提供 SDK / REST / 二维码直出 / iframe 等备选灵活方式，作为标准之上的便利层，方便不同场景的第三方按需取用。
- 多种接入方式 ≠ 多种标准。它们都收敛到同一个身份后端，区别只在"如何把登录/授权呈现给用户、要不要你方后端参与"。
历史口径中部分文档写过 "OAuth 2.0"，现已统一为 OAuth 2.1（= OAuth 2.0 + 强制 PKCE + 废除隐式/密码模式）。契约 MG×UM-对接契约 v1.0 的「契约 1」行为要求本就是 2.1，仅标签此前写成了 2.0，本次已对齐。
为什么 OAuth 2.1 是最好、也是唯一的标准
1. 它是行业共识的"最小安全基线"
OAuth 2.1（RFC 9700，2025 定稿）不是新协议，而是把多年来 OAuth 2.0 的最佳实践固化成了强制要求：
| 要求 | OAuth 2.0 | OAuth 2.1 |
|---|---|---|
| PKCE（防授权码拦截） | 可选（强制开关就绪，默认关） | 强制 |
| 隐式模式（implicit） | 允许 | 废除 |
| 密码模式（password） | 允许 | 废除 |
| 公开客户端（SPA/APP/小程序）安全 | 靠运气 | 靠规范保底 |
也就是说，选 OAuth 2.1 = 直接拿到"不会被轻易攻破"的登录流程，不用自己踩坑。
2. 一个标准通吃网站 / APP / 小程序
授权码 + PKCE 是唯一同时适用于三端的范式：
- 网站（服务端渲染）：后端持有
client_secret，走标准授权码流程。 - SPA / 小程序 / APP（公开客户端）：无
client_secret，靠 PKCE +redirect_uri校验，无需泄露密钥。 - 同一套
authorize / token / userinfo / revoke / discovery端点，三端复用，后端只维护一份。
3. 不绑定私有实现，未来可平滑演进
- 基于标准 OIDC discovery（
/.well-known/openid-configuration），第三方用 Auth.js / Spring Security / OAuth2 Proxy 等现成库即可接入，不用读我们的私有文档、不用装我们的 SDK。 - 家族新增产品（云集通 / 云集圈 / 云集客 / MG）只要实现同一套端点，就能直接互信，互相对接成本趋近于零。
- 标准向前兼容：今天按 2.1 接，明天换 IdP 也不会推倒重来。
4. 对外统一、对内固定，长期维护成本最低
- 对外：第三方只学一个标准，文档/SDK/错误码一套就够。
- 对内：家族产品间只认一个协议（契约 1），不会出现"A 产品用 REST、B 产品用 SDK、C 产品用私有签名"的分裂。
- 安全补丁（如 PKCE 升级、token 过期策略）在一处改、全家族生效。
当前实现状态（2026-07-14 更新）：契约 1 的五个标准端点已全部落地——/oauth/authorize + /oauth/token（授权码 + PKCE 可选校验 + 强制开关 oauth_force_pkce 就绪）、/oauth/userinfo、/oauth/revoke、/.well-known/openid-configuration 均已上线；refresh_token 独立端点已落地（刷新令牌轮换 + 可吊销，表 um_oauth_refresh_tokens）；client_credentials 已支持。PKCE 强制化开关已就绪（默认 0，附 um_oauth_pkce_audit 审计表），观察期结束后在低峰期开启即合规。对外已可用的仍有下方「备选灵活方式」（REST / 二维码 / SDK）；它们与 OAuth 2.1 端点共享同一身份后端，迁移时业务代码几乎不用改。
全部接入方式对比
唯一标准是 OAuth 2.1。下表其余方式都是"标准之上的灵活备选"，按场景选用，不是替代标准。
| 维度 | ① 云集通标准接口（OAuth 2.1 + OIDC） | ② SDK（PHP/JS/Python/小程序） | ③ REST 直连（connect.php?act=*） | ④ 二维码直出（api/qrcode.php） | ⑤ iframe / widget 嵌入 |
|---|---|---|---|---|---|
| 定位 | 云集生态标准接口 | 标准/REST 的封装（官方推荐低代码） | 标准之上的底层 REST | 标准之上的轻量呈现 | 标准之上的嵌入式 UI |
| 适用对象 | 所有新接入、家族产品互联 | 想少写代码的任意语言项目 | 需要服务端精细控制的老系统 | 新项目、SPA、自定义登录弹窗 | 想零前端改动嵌入登录页 |
| 是否需要你方后端 | 视客户端类型（SPA 可纯前端 + PKCE） | 视语言（多数需后端） | 需要（服务端持 appkey 签名） | 不需要（纯前端轮询） | 不需要 |
| 安全模型 | PKCE 强制 + Bearer Token + OIDC claims | 封装了签名与 PKCE | MD5 私有签名 + appkey + timestamp 防重放 | 同 REST，二维码由 UM 服务端生成 | 依赖被嵌套页，受第三方 X-Frame-Options 限制 |
| 是否标准/通用 | ✅ 行业标准，通用库可直接接 | 封装私有协议 | ❌ 私有协议 | ❌ 私有协议 | ❌ 私有 + 受限 |
| 开发量 | 中（接标准库） | 低（装包即用） | 中（手写签名 + 换 token） | 低（一个 <img> + 轮询） | 极低（但可用性差） |
| 覆盖端 | 网站 / APP / 小程序 全通 | 全端（随 SDK 语言） | 网站 / 服务端 | 网站 / H5 | 主要 PC 网页 |
| 与官方标准关系 | 就是标准本身 | 备选（封装层） | 备选（未来收敛到 2.1 端点） | 备选（呈现层） | 备选（受限，谨慎用） |
| 成熟度 | 基本落地（discovery/userinfo/revoke 已上线，PKCE 可选校验+强制开关就绪，client_credentials+refresh_token 独立端点已支持，authorize/token 复用） | ✅ 已可用 | ✅ 已可用 | ✅ 已可用 | ⚠️ 受限，新需求不推荐 |
| 推荐度 | ★★★★★ 首选 | ★★★★ 省事（官方推荐封装） | ★★★★ 老系统兼容 | ★★★★★ 轻量首选 | ☆ 仅遗留兼容 |
怎么选（30 秒）
- 🆕 新接入 / 想要长期稳定 / 家族产品互联 → ① 云集通标准接口（OAuth 2.1 + OIDC）（标准一旦就绪即默认）。
- 📦 用 PHP/JS/Python/小程序、想少写代码 → ② SDK（签名/PKCE 自动处理，官方推荐封装）。
- 🖥️ 不方便改前端、后端想完全掌控 → ③ REST 直连（当前最稳的可用方案）。
- ⚡ 想要最快出登录二维码、纯前端 → ④ 二维码直出（
<img src=...>+ 轮询）。 - 🚫 不要为新需求选 ⑤ iframe（微信/支付宝授权页禁止被嵌套，基本不可用）。
所有方式（② SDK / ③ REST / ④ 二维码 / ⑤ iframe）最终都走同一个 UM 身份后端换取 openid / UMID / token，用户身份在所有方式间一致。区别只在"呈现"与"谁持密钥"，不影响身份互通。
官方标准端点（契约 1，目标形态）
| 端点 | 路径 | Method | 说明 |
|---|---|---|---|
| Authorize | /oauth/authorize | GET | 授权码，PKCE 已支持（可选校验，强制开关 oauth_force_pkce 就绪默认关） |
| Token | /oauth/token | POST | authorization_code / refresh_token（刷新令牌轮换+可吊销） / client_credentials（PKCE code_verifier 校验已支持） |
| Userinfo | /oauth/userinfo | GET/POST | Bearer，返回标准 OIDC claims |
| Revoke | /oauth/revoke | POST | 令牌吊销（RFC 7009），需 client_id + client_secret |
| Discovery | /.well-known/openid-configuration | GET | OIDC discovery JSON，通用库必读 |
基地址：
https://um.yunjii.cn（UM 统一数字身份后端）。open.yunjii.cn是独立的开放平台产品，以客户端身份消费 UM 身份 API，并非 UM 的镜像；sl.yunjii.cn为历史镜像（等价主站，逐步弃用）。三者中仅 UM 承载身份后端与数据库，open 不复刻身份逻辑。开放平台与 UM 的宪法级边界见 开放平台与 UM 划界：宪法级边界协议。