# 图奕统一认证接入指南

面向图奕自有产品的服务端、Web 和桌面客户端开发者。文档可以公开阅读，不代表平台开放第三方注册；创建产品、分配权限及管理配置仍需管理员授权。

> 本文描述仓库当前已实现的接口，不表示线上已部署最新版本，也不代替真实产品联调。未标记为已支持的登录方式不要自行拼装内部接口。

## 接入前先分清三种身份

| 身份 | 用途 | 凭据放在哪里 | 能否调用短信、支付 API |
| --- | --- | --- | --- |
| Web OIDC Client | 官网用户登录 | Client Secret 仅服务端 | 不能 |
| Native OIDC Client | 桌面用户登录 | 无 Client Secret；刷新令牌存系统凭据库 | 不能 |
| Service Client | 产品服务调用 | Client Secret 仅产品服务端 | 依已授权 Scope |

平台负责认证、事务短信发送和支付处理。产品负责商品、定价、业务订单、权益，以及自己的业务用户和业务会话。平台登录成功不等于已经登录产品，需要产品完成回调验证和本地会话建立。

## 当前可以接到哪一步

| 能力 | 当前接口 | 注意事项 |
| --- | --- | --- |
| Web 登录 | OIDC 授权码 + S256 PKCE | 验签后建立本地业务会话 |
| 官网自定义登录 | 浏览器直连 + 后端换码，不跳页 | Web Client 显式授权、精确 Origin；见 [自定义网页登录](CUSTOM_WEB.md) |
| 直接找回 / 设置密码 | Web / Native 独立密码事务 | 默认关闭；短信验证后统一撤销，见 [密码管理](PASSWORDS.md) |
| 桌面登录 | 系统浏览器 + OIDC + 回调 | 支持 Public Native Client |
| 桌面原生扫码、短信、密码直连 | 本版新增第一方原生认证扩展 | 部署新版本并显式开启 Native Client，见桌面章节 |
| Device Authorization Grant | **未支持** | 不要调用 `/device_authorization` |
| 事务短信 | 服务 Token + 模板 API | 首期仅大陆 +86；并非身份验证 API |
| 支付与退款 | 服务 Token + 收银台 + 签名事件 | 真实渠道闭环验收前保持关闭 |
| 存量账号映射 | CLI 预导入 + OIDC 自定义声明 | 不迁移密码，不自动合并冲突账号 |

## 创建产品与领取配置

管理员在平台后台“产品 → 创建产品”中填写名称、产品代码、官网地址和需要的能力。网云穿使用 `product_code=wyc`，不要因为仓库叫 wyc2026 就换一个产品代码。

以 `https://www.example.com` 为官网、`https://api.example.com` 为产品 API 地址时，向导默认生成：

| 配置项 | 示例值 | 谁来实现 |
| --- | --- | --- |
| Web Client ID | `wyc-web` | 平台创建 |
| Web 回调 | `https://www.example.com/auth/tuyi/callback` | 网云穿服务端 |
| Native Client ID | `wyc-desktop` | 平台创建 |
| Native 回调 | `tuyi-wyc://oauth/callback` | 网云穿桌面安装程序注册，客户端处理 |
| Service Client ID | `wyc-service` | 平台创建，仅服务端使用 |
| Webhook | `https://api.example.com/api/tuyi/events` | 网云穿服务端 |
| 收银台返回 | `https://www.example.com/payment/result` | 网云穿网页，仅展示结果 |

这些地址是默认建议和平台注册记录，**不会自动在产品仓库生成接口**。创建前可以改为产品实际拥有的地址；回调、返回地址不允许通配符。勾选短信/支付不会自动完成短信模板授权、商户绑定和真实验收，仍需分别配置。

产品向导和“产品 → 编辑产品”提供“强制绑定微信”开关，默认关闭。开启后，平台只允许已验证微信身份的账号完成该产品的新授权：已经绑定微信的用户仍可选择短信或密码登录；尚未绑定的用户须改用微信扫码，并用原手机号验证码把微信绑定到同一个平台账号。该策略按 `product_code` 隔离，不影响其他产品，也不能被中央登录 Cookie、`prompt=none`、Native 或自定义网页登录绕过。

开关不会回收产品已经建立的本地业务 Session；新授权和 Refresh Token 轮换会执行策略检查。产品仍须消费安全事件并维护自己的会话。启用前应确认公众号登录渠道可用，否则未绑定用户无法完成登录。

创建成功的一次性配置包包含 Web Secret、Service Secret、Webhook Secret（按所选能力）。保存到产品服务端的受限配置或 Secret 管理中，不要贴进工单、前端代码、Git 或日志。关闭一次性回执后不能再次查看原文；丢失应按密钥轮换流程处理。

## 环境配置

以下是**产品侧建议变量名**，不是平台 `config.env` 新增配置。域名以本页顶部的本实例 Issuer 为准；正文默认正式域名。

```dotenv
TUYI_ISSUER=https://platform.too1.net
TUYI_PRODUCT_CODE=wyc
TUYI_WEB_CLIENT_ID=wyc-web
TUYI_WEB_CLIENT_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
TUYI_WEB_REDIRECT_URI=https://www.example.com/auth/tuyi/callback
TUYI_NATIVE_CLIENT_ID=wyc-desktop
TUYI_NATIVE_REDIRECT_URI=tuyi-wyc://oauth/callback
TUYI_SERVICE_CLIENT_ID=wyc-service
TUYI_SERVICE_CLIENT_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
TUYI_WEBHOOK_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
```

桌面包只包含 Issuer、Native Client ID 和 Native 回调；不能打包上述任何 Secret。开发、staging、正式环境使用不同客户端和回调配置，不要让本地调试端接收生产授权。

## 标准端点

| 方法 | 地址 | 用途 |
| --- | --- | --- |
| GET | `/.well-known/openid-configuration` | 发现文档 |
| GET | `/.well-known/jwks.json` | ID Token 签名公钥 |
| GET | `/oauth2/authorize` | 浏览器授权 |
| POST | `/oauth2/token` | 换取/刷新用户 Token，或获取服务 Token |
| GET | `/oauth2/userinfo` | 获取当前用户信息 |
| POST | `/oauth2/revoke` | 撤销令牌 |
| GET | `/oauth2/logout` | 中央登出 |

不要用旧 `sso.too1.net` 作为新接入的 Issuer，不要通过 HTTP 跳转来发现 Token 端点。Issuer 必须完全匹配，包括协议和路径。

## 建议阅读顺序

1. [Web 登录](OIDC.md)：所有产品先理解这份认证契约。
2. [桌面客户端](NATIVE.md)：原生扫码/短信/手机号密码 API、事务、PKCE、错误恢复，以及保留的标准浏览器模式。
3. [网云穿实施清单](WYC2026.md)与[旧账号映射](MIGRATION.md)：保留老用户、资源和权限。
4. [服务凭证及短信](PLATFORM_API.md)、[产品成员](MANAGED_USERS.md)、[支付退款](PAYMENTS.md)、[Webhook](WEBHOOKS.md)。
5. [联调验收与排障](TROUBLESHOOTING.md)：通过后再灰度。

所有章节支持 Markdown 下载，便于交给另一仓库的开发者或代码助手；下载的是文档，不包含实际产品配置和密钥。