接入第三方应用
面向任意技术栈的第三方应用，如何在 YeeAuth 中完成注册、选对授权流程并跑通认证。
接入第三方应用
本页是"把一个第三方应用接入 YeeAuth"的完整参考：应用如何注册、该用哪种授权流程、回调地址怎么配、Token 怎么校验。如果你想跟着一步步的教程动手，可以直接看 快速入门指南；本页更适合已经理解基本概念、想一次看完整体方案的开发者。
第一步：在控制台注册你的应用
- 登录 YeeAuth Console，进入 应用管理。
- 点击创建应用，根据你的应用形态选择模板：
| 应用类型 | 适用场景 | 是否使用 Client Secret |
|---|---|---|
| 标准 Web 应用 | 有后端、支持页面跳转的传统 Web 应用（Node.js / Java / PHP 等服务端渲染或有后端会话） | 是 |
| 单页 Web 应用（SPA） | 纯前端渲染、无后端的 React / Vue 等应用 | 否，改用 PKCE |
| 客户端应用 | iOS / Android / 桌面等本地应用 | 否，改用 PKCE |
| 后端应用 | 无前端界面，仅对外提供 API 或运行后台任务的服务 | 是（用于 M2M） |
- 填写应用名称后，进入应用详情页完善配置。系统会为该应用分配一个唯一的 应用标识（identifier），并生成 Client ID（和机密应用的 Client Secret）。
Client Secret 只在生成时完整展示一次，请立即保存；它只能用在你的后端，绝不能出现在浏览器或客户端代码中。
第二步：找到你专属的认证端点
YeeAuth 中每个应用都拥有独立的子域名作为 Issuer，格式为：
https://{应用标识}.yeeauth.com在应用详情页的「协议配置」标签下可以直接看到完整的端点列表，也可以访问发现文档自动获取：
GET https://{应用标识}.yeeauth.com/.well-known/openid-configuration| 端点 | 用途 |
|---|---|
| Authorization Endpoint | /oauth/authorize，引导用户登录并获取授权码 |
| Token Endpoint | /oauth/token，用授权码 / 刷新令牌 / 客户端凭据换取 Token |
| Userinfo Endpoint | /userinfo，获取已认证用户的信息 |
| JWKS Endpoint | /oauth/jwks，供资源服务器获取验签公钥（仅用于校验 ID Token） |
| Check Token Endpoint | /oauth/check_token，供资源服务器内省校验 Access Token（Access Token 不透明，不能走 JWKS 验签） |
| End Session Endpoint | /oauth/logout，用于登出并清除会话 |
请始终以应用详情页展示的端点为准，不要把域名硬编码后长期使用——一旦应用标识变化，端点也会随之变化。
第三步：配置回调地址
在应用的协议配置中填写：
- Redirect URIs（登录回调地址）：用户完成认证后，YeeAuth 允许跳回的地址列表，必须与发起登录时传入的
redirect_uri逐字符匹配（协议、域名、端口、路径）。 - Post Logout Redirect URIs（登出回调地址）：调用 End Session Endpoint 登出后允许跳回的地址。
本地开发可以先填 http://localhost:3000/callback 之类的地址，上线前替换为正式域名。多个环境（开发 / 预发 / 生产）建议配置多条，而不是共用一个应用。
第四步：按应用类型选择授权流程
有后端的 Web 应用 → 授权码流程
最常见、安全性最高的方式。浏览器跳转到 Authorization Endpoint 获取授权码，再由后端用 code + client_secret 向 Token Endpoint 换取 Token。完整步骤见 接入用户登录。
GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=openid profile email&state=...无后端的 SPA / 移动端 / 桌面应用 → 授权码 + PKCE
这类应用无法安全保存 Client Secret，必须使用 PKCE（Proof Key for Code Exchange）：客户端在发起授权请求前生成一个随机的 code_verifier，计算出 code_challenge 一并带上；换取 Token 时再带上原始 code_verifier，服务端据此校验请求方与获取授权码的是同一方，从而在没有 Secret 的情况下防止授权码被截获后被冒用。
推荐直接使用成熟的标准 OIDC 客户端库（Auth.js、oidc-client-ts、AppAuth 等），它们会自动处理 PKCE、跳转与 Token 刷新，你只需要提供 Issuer 和 Client ID。
服务间调用（无用户参与） → 客户端凭据流程
后台任务、定时任务、微服务之间互相访问时，不涉及浏览器和用户，直接用应用自身的凭据换取 Token：
curl -X POST https://{应用标识}.yeeauth.com/oauth/token \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "scope=api:read"拿到的 Access Token 不含用户身份，只代表这个应用本身的权限。
第五步：在你的服务里校验 Token
Access Token 是不透明的（Opaque）：它是一串随机字符串，不是可以直接解析验签的 JWT，无法通过 JWKS 校验。无论走哪种授权流程，你的后端（资源服务器）在收到请求时都应当调用内省端点确认 Token 有效，而不是无条件信任前端传来的内容，也不要尝试把它当 JWT 解析：
- 从
Authorization: Bearer <token>中取出 Token。 - 调用
POST /oauth/check_token?token={Access Token}，向 YeeAuth 确认该 Token 是否有效、尚未过期。 - 根据返回结果中的用户信息 / Scope / 角色权限声明决定是否放行该请求。
ID Token 是例外：它本身就是签名的 JWT，专门用于证明"用户是谁"，可以用 JWKS Endpoint 提供的公钥自行验签（校验 iss、aud、exp 等声明），不需要每次都回源查询。但 ID Token 只在用户登录场景（授权码流程）中签发，client_credentials 换来的 Access Token 依然需要用内省端点校验。
常见问题
跳转登录后报 redirect_uri 不匹配？
检查发起登录时传入的 redirect_uri 是否与控制台配置的地址逐字符一致，包括末尾是否有斜杠。
SPA 里要不要用 Client Secret？ 不要。没有后端的应用一律不下发或不使用 Secret，改用 PKCE。
已有的老系统只支持表单登录，接不了 OIDC 怎么办？ 应用协议配置里也提供了 JWT、表单代填等模板，可用于兼容无法改造的老系统，但新应用建议优先选择标准 OIDC。
相关阅读
- 快速入门指南：从零开始的完整教程。
- 应用程序（Application）：应用与用户池、SSO 的关系。
- OIDC 与 OAuth 2.0：协议基础概念。
- JWT Token：Token 结构与校验细节。