ThunderID 三大集成模型详解:Redirect-Based、App-Native 与 Direct API 该如何选择

原创2026-11-15 10:47:391,960 阅读

ThunderID 三大集成模型详解:Redirect-Based、App-Native 与 Direct API 该如何选择

ThunderID 是一个开源的高性能身份认证技术栈,它为你提供三种集成模型——Redirect-Based、App-Native 与 Direct API,分别对应"委托登录"、"应用自绘界面"和"可组合单步 API"三种信任假设。选型的核心在于:你的应用是否愿意把登录界面交给 ThunderID 托管、是否要自己渲染每一个界面、以及是否只需要单步原语。本文用一张对比表和一套决策清单,帮你快速做出正确选择。

ThunderID 支持 People、AI Agents 与 Machines 三种一等身份类型,统一目录、角色与 API 授权

为什么 ThunderID 提供三种集成模型?

认证的本质是验证身份。但"验证发生在哪里、界面归谁管、凭证经过谁的手",这三个问题的答案不同,就产生了三种集成模型:

  • Redirect-Based(基于重定向):委托模型。登录界面托管在 ThunderID 侧,用户凭证永不离开服务端。
  • App-Native(应用原生):共享责任模型。界面由你的应用渲染,流程编排与策略仍由 ThunderID 服务端强制执行。
  • Direct API(直接 API):应用全权模型。只暴露单步认证端点,由你的应用自行组装完整的认证顺序。

从架构上看,三种模型最终都落在 Data Plane 的协议引擎与 Flow 编排服务上,区别只是你的客户端与它们之间的交互方式:

ThunderID 身份架构图:Control Plane 管理目录与配置,Data Plane 提供 OAuth 端点、App Native Flow API 与可组合 API

模型一:Redirect-Based —— 把整个登录界面委托给托管页面

这是最经典的 OAuth 2.0 授权码流程(RFC 6749 + OpenID Connect)。用户点击登录后,你的应用把他重定向到 ThunderID 托管的登录页;认证完成后,ThunderID 带着 authorization code 重定向回你注册的 redirect URI,你的应用再用它换取 access token、ID token 和 refresh token。

ThunderID Browser SDK 面向现代 Web 应用的 Redirect-Based 集成登录方案

工作流程(4 步):

  1. 应用把用户重定向到 ThunderID 授权端点(GET /oauth2/authorize);
  2. ThunderID 渲染登录页,引导用户完成凭证输入、MFA、同意等全部步骤;
  3. 完成后重定向回你的应用并附带 authorization code;
  4. 应用用该 code 换取 OAuth 2.0 token。

核心优势:

  • 🛡️ 凭证隔离:用户密码和认证密钥始终留在 ThunderID 内部,你的应用只收到签名的 token(JWT),从不触碰明文凭证;
  • 🧩 互操作性:任何符合 OAuth 2.0 / OIDC 规范的客户端库或框架都能接入;
  • 🎨 托管页面可定制:登录、注册、账号恢复、MFA、同意界面全部由 ThunderID 托管,并可通过控制台里的 Flow Builder 可视化定制。

ThunderID 控制台 Flow Builder 可视化编辑器,可编排登录、MFA、同意等可组合认证流程

适用场景:Web 应用、单页应用(SPA)、移动端 App 中"跳转一下也无妨"的登录体验。任何能执行浏览器重定向的应用都可以使用。主要权衡是:用户会短暂离开你的应用,且 UI 定制受限于托管页面暴露的能力。

📌 注意:浏览器 SPA 注册为 browser 应用类型后,只能通过 Redirect-Based 模型登录。注册和恢复流程没有重定向等价物,SPA 仍需通过 Flow Execution API 驱动这些流程。

模型二:App-Native —— 你的 App 渲染界面,服务端掌控流程

App-Native 模型调用 Flow Execution API(POST /flow/execute)从你的应用界面内部驱动认证。ThunderID 负责"流程怎么走":步骤排序、策略应用、上下文分支都在服务端;你的应用负责"界面长什么样":渲染每一步的屏幕、收集用户输入、把结果提交回去。流程走完后,ThunderID 返回一个 assertion token(签名 JWT),你的应用再通过 Token Exchange 授权(RFC 8693)换取标准 OAuth 2.0 token。

ThunderID Android SDK 提供 App-Native 集成所需的 Compose 组件

为什么它很适合原生移动应用? 因为登录界面全程不出现在你的 App 内部,没有跳转、没有 iframe,品牌体验完整保留;而 ThunderID 侧新增 MFA 或条件步骤后立即生效,无需修改或重新发布你的应用。

两种集成模式(由 verbose 字段控制):

模式 服务端返回 你的应用职责
Verbose(逐步) inputs + actions + meta 组件树 按服务端描述精确渲染(建议配合官方 SDK,SDK 会自动渲染组件树)
Non-Verbose(托管) 仅 inputs + actions 完全用自己的组件决定界面呈现

身份验证的两种方式(这是 App-Native 独有的安全设计):

  • 🔑 Flow Secret:面向可保密的服务端应用(如后端服务)。ThunderID 在创建应用时一次性签发,之后不再返回,应用在发起流程时通过 Flow-Secret 请求头出示;
  • 📱 Attestation(平台认证):移动端无法安全保存静态密钥,因此 Mobile 应用类型通过 Google Play Integrity(Android)或 Apple App Attest(iOS)来证明身份,发起流程时出示 Attestation-Token 请求头。

适用场景:原生移动与桌面应用、可保密的服务端应用。限制:浏览器 SPA 不能直接发起 App-Native 登录(见上文提示);另外流程不支持"回退到上一步",界面设计时需注意。

模型三:Direct API —— 用可组合的单步端点自己组装登录

Direct API 把认证拆成一个个单一职责的端点:校验用户名密码、发送 OTP、校验 OTP、发起社交登录……每个端点只做一件事。你的应用按自己的逻辑随意组合调用顺序,无需应用注册、无需流程配置。

工作流程(3 步):

  1. 应用直接调用某个认证端点并提交用户输入;
  2. ThunderID 校验输入,返回用户信息和一个签名 assertion token(记录已完成的认证方式、保证级别与用户身份);
  3. 需要增强认证时,把上一次的 assertion 传入下一次请求——这就是 Step-Up(逐步增强)认证,例如"密码 + 短信 OTP"两次调用后,最终 assertion 会同时记录两种认证方式。

安全边界(务必了解):

  • 由于 Direct API 端点不接收应用标识,ThunderID 用服务器级密钥做门禁:配置 server.security.direct_auth_secret 后,所有 /auth/** 调用必须在 Direct-Auth-Secret 头中出示该密钥,否则返回 401。密钥标识的是"调用方集成",不代替用户身份;
  • ⚠️ ThunderID 不对 Direct API 做限流。它只提供基于身份和登录方式的自动账号锁定,这不能替代限流器。若要把这些端点暴露到可信网络之外,务必先加 API 网关并施加限流,否则将面临密码猜测、OTP 枚举与短信费用失控的风险;
  • 不需要 assertion 时可在请求体中设置 skip_assertion: true;不使用的部署可直接将 direct_api.enabled 设为 false 从服务器移除这些端点。

适用场景:CLI 工具、自动化脚本、server-to-server 认证等无头场景。如果认证需要服务端强制执行策略(MFA、条件步骤),请改用 App-Native 或 Redirect-Based。

三大集成模型一张表速览

维度 Redirect-Based App-Native Direct API
信任模型 委托:ThunderID 是权威方 共享:ThunderID 控制流程顺序,应用渲染界面 应用所有:应用控制顺序
凭证暴露 仅 ThunderID 可见 经过应用 经过应用
认证逻辑 服务端流程强制执行 服务端流程强制执行 应用自行实现
Token 输出 OAuth 2.0 access / ID token assertion token,经 Token Exchange 换取 OAuth 2.0 token assertion token,经 Token Exchange 换取 OAuth 2.0 token
需要流程配置 ✅ 需要 ✅ 需要 ❌ 不需要
需要应用注册 ✅ 需要 ✅ 需要 ❌ 不需要
典型场景 Web / SPA / 移动端 原生移动 / 桌面 / 服务端 CLI / 脚本 / 机器间

4 个问题快速选出正确的集成模型 🎯

按顺序回答下面 4 个问题,答案基本就是选型结果:

  1. 你的应用能安全持有密钥吗? 不能(浏览器 SPA / 移动端)→ 优先考虑 Redirect-Based;能 → 继续下一题。
  2. 登录界面必须留在你的应用内部吗? 必须(强品牌、原生体验)→ App-Native;可以短暂跳转托管页面 → Redirect-Based。
  3. 需要 ThunderID 服务端强制执行 MFA、条件步骤等策略吗? 需要 → App-Native(或 Redirect-Based);不需要、且只需单步原语 → Direct API。
  4. 这是无头 / 脚本 / 机器间场景吗? 是(CLI、自动化、server-to-server)→ Direct API,并注意在网关层自行限流。

💡 一个实用的组合策略:Web 端用 Redirect-Based 拿到最快上线路径,原生 App 用 App-Native 保留完整品牌体验,运维脚本与内部工具用 Direct API——三者可以并存于同一个 ThunderID 部署。

更多相关资源

想深入了解某一模型,可以从官方文档与源码入手:

一句话总结:Redirect-Based 最省心、App-Native 体验最好、Direct API 最灵活也最"自负责"——先想清楚"界面归谁、策略归谁、凭证经过谁",答案自然浮现。

登录后查看全文
thunderid