Miduo Third Party Sso Integration

Read First

Always read these in order:

1. The exported handoff Markdown the user provided (example data often includes secrets and local URLs)
2. miduo-md/todo/令牌发放-todo/快捷入口-令牌发放与第三方校验-技术分析.md
3. If practical examples are needed, read:
   • miduo-md/todo/令牌发放-todo/快捷入口-令牌发放与第三方校验-curl测试文档.md
   • miduo-md/todo/令牌发放-todo/快捷入口-令牌发放与第三方校验-本机9186测试结果.md

If the export Markdown conflicts with tested behavior, trust tested behavior.

Primary Goals

Do both:

1. Determine whether the exported handoff contains everything a third-party team needs to implement Miduo SSO safely and correctly.
2. Provide a new-project-ready implementation blueprint that a third-party can follow without guessing.

Core Model（必须说清楚）

Miduo SSO uses two tokens:

• exchange token（交换 token / request field token）: short-lived, opaque, one-time token delivered to the browser via redirect (QUERY or FORM_POST).
• sessionToken: returned only after backend validation; must be stored and used server-side only (refresh/revoke).

Non-negotiables:

• appSecret is backend-only; never expose to browsers/mobile apps.
• Third party must not trust URL PII (mobile, name, etc.) as identity proof.
• Login bridge redirectUri must match allowlist (strict). Production should require HTTPS. (Current backend code accepts http/https, but HTTPS is strongly recommended.)
• state must be generated by the third party and verified on callback (CSRF/session binding).
• For validate-login-token, Miduo returns wework_userid when valid=true. This value is the authoritative Enterprise WeChat userid (企业微信用户ID).

Integration Intake（每次接入必问：让第三方逐项确认）

Use this as the first checklist in both review/build mode. Do not start coding until P0 items are confirmed.

P0 必须确认（缺一不可）

• 对接环境

  • MIDUO_BASE_URL：<https://admin.t.ebcone.cn>（第三方后端调用 open API / 登录桥的域名）
  • 第三方环境：<dev/test/prod>，时区（默认 Asia/Shanghai）

• 应用凭据（仅后端）

  • appCode：<...>
  • appSecret：<...>（只能放第三方后端，禁止出现在前端/浏览器）

• 第三方回调/落地（必须提供完整 URL）

  • callbackUrl（你方接收 exchange token 的入口页面/接口对应的页面）：<https://third.example.com/sso/callback>
  • token 交付方式：QUERY 或 FORM_POST（默认 QUERY；若 FORM_POST，第三方必须实现自动提交表单接收）

• 登录桥回跳白名单（必须精确列出）

  • redirectUri allowlist（至少包含 callbackUrl；推荐 HTTPS）：
    • <https://third.example.com/sso/callback>
  • 确认口径：是否要求精确匹配到 path（推荐）还是仅同 host（目前后端按 host 匹配；如需更严格必须提前约定）

• state 策略（防 CSRF）

  • 第三方必须回答：state 如何生成、保存（cookie/session/db）、回调时如何校验与过期（建议 5–10 分钟）

• 第三方必须具备的后端接口/能力

  • POST /auth/miduo/callback（或等价）：前端把 token/state 交给后端
  • 后端能调用：validate-login-token / refresh-session-token / revoke-session-token
  • sessionToken 只存后端（db/redis），不会写入浏览器存储

P1 强烈建议确认（不上线会很痛）

• 时钟偏差窗口：允许 X-App-Timestamp 偏差 ±<300> 秒
• nonce 去重窗口：<600> 秒（第三方侧需要保证同 appCode 下 nonce 不复用）
• 签名输出格式：Base64（是否需要去掉换行、是否 URL-safe Base64）
• 日志脱敏策略：token/sessionToken/appSecret 全量禁止打印；最多输出 hash 或前 6 后 4

需要第三方回传的“确认结果模板”（直接复制给对方填）

【第三方系统接入确认单】
1. 环境
   - 对接环境: <dev/test/prod>
   - MIDUO_BASE_URL: <https://...>

2. 应用凭据（第三方后端持有）
   - appCode: <...>
   - appSecret: <已通过安全渠道接收/已配置在密钥管理，不出现在前端>

3. 回调与白名单
   - callbackUrl: <https://.../sso/callback>
   - redirectUri allowlist:
     - <https://.../sso/callback>
   - tokenDeliveryMode: <QUERY|FORM_POST>

4. state 与会话
   - state 生成方式: <...>
   - state 保存位置: <cookie/session/db>
   - state 过期时间: <...>

5. 令牌与存储
   - exchange token 仅用于一次校验: <确认>
   - sessionToken 仅后端存储: <确认>
   - refresh 策略: <定时/按请求/混合，频率...>
   - logout revoke: <确认>

Required Completeness Check（交付信息必须齐）

Treat these as required unless the user explicitly says the audience only needs a subset.

A) Identity And Environment

The handoff should clearly contain:

• baseUrl
• appCode
• appSecret
• shortcutId
• callbackUrl（第三方落地页/回调入口）
• redirectUri allowlist（登录桥回跳白名单）
• token delivery mode: QUERY or FORM_POST
• exchange token TTL (seconds)
• sessionToken TTL (seconds)
• session max age if enabled (seconds)
• allowed claims (e.g. userId, mobile, ...)
  • Note: allowedClaims controls optional PII fields like mobile/email. When returned, these fields are plain/original (not masked/encrypted), so treat them as sensitive.

Recommended (if missing, flag as P1):

• clock skew tolerance window (e.g. ±300s)
• nonce uniqueness window (e.g. 5–10 minutes)
• exact signature encoding (Base64 recommended; if hex allowed, clarify lowercase/uppercase)

B) API Surface

The handoff should clearly contain:

• POST /api/sso/redirect-url（发放跳转 URL）
• GET /api/gzt/workbench/shortcut/jump/{shortcutId}（工作台快捷入口统一跳转）
• POST /api/open/sso/validate-login-token（校验 exchange token）
• POST /api/open/sso/refresh-session-token（续期 sessionToken）
• POST /api/open/sso/revoke-session-token（吊销 sessionToken）
• GET /api/sso/bridge/redirect-url（登录桥：失效后回米多再回第三方）

C) Authentication And Signing（开放接口必签）

Open API headers (required):

Content-Type: application/json
X-App-Code: <appCode>
X-App-Timestamp: <unix seconds>
X-App-Nonce: <random string>
X-App-Signature: <HMAC-SHA256 signature>

Canonical string:

canonical = appCode + "\n" + timestamp + "\n" + nonce + "\n" + signedValue
signature = HMAC_SHA256(appSecret, canonical)  // Base64 output recommended

Reference implementations (copy-paste safe):

// Node.js
import crypto from "crypto";

export function miduoSignatureBase64({ appCode, appSecret, timestamp, nonce, signedValue }) {
  const canonical = `${appCode}\n${timestamp}\n${nonce}\n${signedValue}`;
  return crypto.createHmac("sha256", appSecret).update(canonical, "utf8").digest("base64");
}

// Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public static String miduoSignatureBase64(String appCode, String appSecret, String timestamp, String nonce, String signedValue) throws Exception {
    String canonical = appCode + "\n" + timestamp + "\n" + nonce + "\n" + signedValue;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(appSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] raw = mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8));
    return Base64.getEncoder().encodeToString(raw);
}

Signed value per endpoint:

• validate: signedValue = token
• refresh: signedValue = sessionToken
• revoke: signedValue = sessionToken

D) Integration Behavior（落地逻辑必须正确）

The handoff should clearly explain:

• Browser only transports exchange token; browser must not hold appSecret
• Third-party backend must validate exchange token
• exchange token is one-time and should fail on second validate
• Third-party backend stores sessionToken server-side
• Third-party backend refreshes sessionToken
• Third-party logout revokes sessionToken
• When refresh fails (success=false), go through login bridge
• redirectUri must be HTTPS and allowlisted
• Token delivery mode:
  • QUERY: landing receives query params
  • FORM_POST: landing receives form body

New Project Quickstart（新项目直接照做）

Miduo 配置项模板（发给第三方即可）

Copy-paste this section to the third-party team. Replace all <...> placeholders. Do not send real appSecret in group chats; use secure channels.

1) 环境信息

环境: <DEV|TEST|UAT|PROD>
米多星球 Base URL: <https://admin.xxx.com>           # 第三方对接 open API/登录桥的域名
米多星球 前端登录页: <https://admin.xxx.com/login>    # 浏览器重认证会跳这里
时区: Asia/Shanghai
签名时间戳单位: unix seconds
允许时钟偏差: ±<300> seconds
nonce 去重窗口: <600> seconds

2) 应用信息（SSO App Config）

appCode: <YOUR_APP_CODE>
appName: <YOUR_APP_NAME>
appSecret: <YOUR_APP_SECRET>  # 仅第三方后端保存与使用
appStatus: <1=启用>

callbackUrl(落地/回调): <https://third.example.com/sso/callback>

redirectUri allowlist(登录桥白名单):
- <https://third.example.com/sso/callback>   # 推荐精确匹配；至少需同域同host命中

allowedClaims(可返回字段):
- userId
- employeeNo
- userName
- mobile
- email

exchangeTokenTTLSeconds: <600>
sessionTokenTTLSeconds: <28800>
sessionMaxAgeSeconds: <null|604800>
tokenDeliveryMode: <QUERY|FORM_POST>  # 默认 QUERY

3) 必须对齐的 URL/参数约定

登录桥入口（浏览器 GET）:
  GET {MIDUO_BASE_URL}/api/sso/bridge/redirect-url
    ?appCode=<appCode>
    &redirectUri=<url-encoded redirectUri>
    &state=<state>

登录桥回跳（第三方 callback 接收）:
  <redirectUri>?token=<exchangeToken>&app_code=<appCode>&state=<state>&source=bridge

注意:
- `state` 必须由第三方生成并在 callback 时校验（CSRF/会话绑定）
- `redirectUri` 必须命中 allowlist；生产强烈建议使用 https
- `redirectUri` 可能在多层重定向后仍是 percent-encoded，一般只需 decode 一次（避免双重 decode）

4) Open API（第三方后端调用米多）

Required headers:

Content-Type: application/json
X-App-Code: <appCode>
X-App-Timestamp: <unix seconds>
X-App-Nonce: <random string>
X-App-Signature: <HMAC-SHA256(appSecret, canonical) base64>

Canonical string:

canonical = appCode + "\n" + timestamp + "\n" + nonce + "\n" + signedValue
signature = Base64(HMAC_SHA256(appSecret, canonical))

Endpoint list:

POST {MIDUO_BASE_URL}/api/open/sso/validate-login-token
  body: { "token": "<exchangeToken>" }
  signedValue = token

POST {MIDUO_BASE_URL}/api/open/sso/refresh-session-token
  body: { "sessionToken": "<sessionToken>" }
  signedValue = sessionToken

POST {MIDUO_BASE_URL}/api/open/sso/revoke-session-token
  body: { "sessionToken": "<sessionToken>" }
  signedValue = sessionToken

Response rules（务必按业务字段判断成功）: