SaaS 接入说明

1. 申请接入信息

1. 在管理台创建 Client。
2. 记录生成的 client_id。
3. 配置 redirect_uri 白名单（严格匹配）。
4. 选择允许的登录方式（google / github / email）。

2. 登录入口

SaaS 将用户重定向到 Auth Center，支持两种方式：

方式 A：快速接入 - 显示选择页面

GET /login?client_id=app_xxx&redirect_uri=https%3A%2F%2Fsaas.example.com%2Fauth%2Fcallback

方式 B：高级接入 - 直接跳转指定登录方式

GET /login/provider?client_id=app_xxx&redirect_uri=https%3A%2F%2Fsaas.example.com%2Fauth%2Fcallback&provider=google

两种方式都支持可选参数：state（Auth Center 会原样回传）

3. 回调与 Token

登录完成后，Auth Center 会重定向回 redirect_uri：

https://saas.example.com/auth/callback?token=JWT&state=STATE

SaaS 从 query 读取 token，并自行保存（推荐设置为 HttpOnly Cookie）。

4. JWT 验签

获取 JWKS：

GET /.well-known/jwks.json

验签字段：sub / iss / aud / exp

推荐校验位置：SaaS 的 Middleware / API Gateway 统一校验，避免页面层漏验。

推荐使用 createRemoteJWKSet（自带缓存与自动刷新，不会每次拉取 JWKS）。

解码示例（Node.js / jose）：

import { jwtVerify, createRemoteJWKSet } from "jose";

const jwks = createRemoteJWKSet(
  new URL("https://auth.umomo.top/.well-known/jwks.json"),
);

const { payload } = await jwtVerify(token, jwks, {
  issuer: "https://auth.umomo.top",
  audience: "app_xxx",
});

console.log(payload.sub, payload.iss, payload.aud, payload.exp);

5. Email 登录

若启用 email 登录，SaaS 使用登录页即可完成验证码流程，无需自行实现。

6. 常见错误

• invalid_client：client 不存在或 disabled
• invalid_redirect_uri：回调地址不在白名单
• provider_not_allowed：该 client 未启用此登录方式