文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>DDoS 与 Web 防护>Web 防护>Bot 管理>客户端认证（Beta）>集成指引>步骤 2：集成客户端认证>在移动端集成客户端认证>移动端集成概述

移动端集成概述

最近更新时间：2025-09-23 11:44:51

我的收藏

本页目录：

概述

客户端认证通过确保每个 API 请求都携带有效的认证令牌，从而验证请求源自受信任的移动应用，有效抵御恶意请求。与 Web 端或 WebView 端的自动拦截机制不同，移动客户端的集成需要开发者在应用层面进行适配，以实现请求的发送、认证令牌的获取与附加，以及服务器挑战的响应。

兼容性

EdgeOne 客户端认证 SDK 支持以下移动端：
iOS 11 及以上版本的操作系统。
Android 5.0 (API level 21) 及以上版本的操作系统。

移动端 SDK 运行机制概述

EdgeOne 客户端认证 SDK 在 iOS 或 Android 环境中，其核心运行机制围绕客户端应用、SDK、认证服务和 EdgeOne 之间的协作展开。通过开发者在应用代码中主动调用 SDK 接口，实现完整认证流程。
说明：
开发者需要明确地在代码中处理 HTTP 428 响应，并调用 SDK 进行认证挑战，然后将获得的令牌附加到后续请求中。SDK 负责认证逻辑的执行和令牌的生成与管理，但请求的发送、响应的捕获和重试逻辑需要由应用层实现。
以下是其主要工作原理：
1. API 请求发起： 移动应用向受 EdgeOne 保护的后端服务发起 API 请求。初始请求可能不包含认证令牌，或者包含一个已过期/无效的令牌。
2. EdgeOne 认证挑战： EdgeOne 接收到请求后，会根据配置的认证策略进行校验。如果请求不符合认证要求（例如缺少令牌或令牌无效），EdgeOne 将返回 HTTP 428 状态码，并在响应头 EO-Attest-Challenge 中携带一个认证挑战 ID。
3. 客户端处理挑战： 移动应用接收到 HTTP 428 响应后，需要从响应头中提取 EO-Attest-Challenge ID。随后，应用调用 SDK 的 attestWithParams() 接口，传入此挑战 ID。SDK 会根据挑战类型（例如验证码、无感验证等）执行相应的认证流程。详细客户端认证流程请参考对应产品说明（参考：腾讯云验证码、腾讯云风险识别 RCE）。
4. SDK 与认证服务交互： SDK 接收到挑战 ID 后，会与 EdgeOne 认证服务进行交互，完成客户端认证过程。这可能涉及在 WKWebView 中显示验证码界面供用户交互，或在后台执行工作量证明等。
5. 获取认证令牌： 认证成功后，SDK 会生成一个有效的认证令牌。应用通过 SDK 提供的接口（如 getAttestationToken()）获取此令牌。
6. 重新发送请求： 应用将新获取的认证令牌附加到原始 API 请求的 EO-Attest-Token HTTP 头中，然后重新发送该请求。
7. EdgeOne 继续处理请求： EdgeOne 收到带有有效认证令牌的请求后，验证令牌的有效性，并允许请求继续流向后端服务。

使用 iOS SDK 进行客户端认证的流程
使用 iOS SDK 进行客户端认证的流程


认证凭证 Token 处理流程

认证令牌是客户端与 EdgeOne 认证服务之间建立信任的关键凭证。在 iOS 或 Android 应用中，开发者需要理解并正确处理认证令牌的生命周期，包括获取、使用和续期。

获取新的认证凭证 Token（或手动认证）

在某些场景下，您可能需要主动触发客户端认证以获取新的认证令牌，例如：
首次请求前： 在应用启动后首次向受保护的 API 发送请求之前，可以主动调用 SDK 进行认证，以避免首次请求就收到 428 挑战。
处理 HTTP 428 挑战： 当收到服务器返回的 HTTP 428 状态码时，需要提取挑战 ID 并调用 SDK 接口发起认证挑战。
强制认证： 业务逻辑需要强制用户进行认证时。
您可以通过调用 SDK 的 attestWithParams() 方法来发起认证挑战。此方法会根据挑战参数执行相应的认证流程，并在成功后通过 AttestCallbackDelegate 返回认证令牌。
注意：
每次调用 attestWithParams() 成功后，SDK 都会生成或更新认证令牌。在将令牌附加到请求头之前，务必再次调用 getAttestationToken() 获取最新的令牌。

使用现有认证令牌

一旦成功获取认证令牌，SDK 会在内部缓存该令牌。在令牌的有效期（TTL）内，您可以重复使用此缓存令牌，而无需每次都重新执行认证挑战。即使应用在后台被挂起或从空闲状态唤醒，SDK 也能提供缓存的有效令牌。
在向受保护的 API 发送请求时，您需要从 SDK 获取当前有效的认证令牌，并将其添加到 HTTP 请求的 EO-Attest-Token 头中。SDK 提供了 getAttestationToken() 方法来获取此令牌。

重新获取认证令牌，或续期已过期认证令牌（处理 HTTP 428 挑战）

认证令牌具有有效期。当令牌过期或因其他原因失效时，EdgeOne 服务器会通过返回 HTTP 428 状态码来指示客户端需要进行新的认证。这是 iOS 和 Android 客户端集成中最重要的适配环节之一。
您的应用需要实现一个健壮的机制来捕获并处理 HTTP 428 响应。典型的处理流程如下：
1. 捕获 428 响应： 在您的网络请求回调中，检查 HTTP 响应的状态码。如果为 428，则表明需要进行认证挑战。
2. 提取挑战 ID： 从 HTTP 428 响应的 EO-Attest-Challenge 响应头中提取认证挑战 ID。这是发起新认证挑战的凭据。
3. 执行认证挑战： 调用 SDK 的 attestWithParams() 方法，传入提取到的 challengeId。如果认证器需要用户交互（如验证码），您还需要提供一个 WKWebView 实例。
4. 获取新令牌： 认证挑战成功后，通过 getAttestationToken() 获取 SDK 生成的最新认证令牌。
5. 重新发送请求： 将新令牌附加到原始 API 请求的 EO-Attest-Token 头中，然后重新发送该请求。此时，请求应能通过 EdgeOne 的认证并正常流向后端服务。

使用 WKWebView 或 WebView 进行交互式认证（和 JS 认证）

在一些客户端认证场景中，认证器可能需要用户交互（如：交互式验证码）或执行计算密集型任务（如：加密工作量证明）。此时，EdgeOne SDK 需要特定的运行环境支持。在移动端平台上，WKWebView （iOS 平台）或 WebView （Android 平台）是实现这些功能的关键组件。
说明：
以下内容中，将以 WebView 统一指代不同平台的对应组件，即：WKWebView （iOS 平台）或 WebView （Android 平台）。请以实际集成平台组件名称为准，进行适配。
当认证器需要渲染交互式验证码 (CAPTCHA) 或运行基于 JavaScript 的加密工作量证明 (Proof-of-Work) 挑战时，SDK 要求在调用 attestWithParams() 方法时提供一个 WebView 实例。这意味着开发者需在应用中预先分配 WebView 实例，并在调用认证 API 时将其作为参数传递给 SDK。

交互式认证场景

部分认证器（例如，使用嵌入式或弹出式交互设置的 TC-CAPTCHA）需要 WebView 实例来渲染其交互界面。该 WebView 实例将在应用内部显示验证码页面，因此需要预先设置以确保正确显示。
嵌入式交互认证： 验证码界面以固定区块形式显示在设备屏幕上。为确保 UI 正确显示且不影响用户体验，开发者必须预设渲染窗口的大小、层叠顺序和对齐方式。请注意，嵌入式认证 GUI 不会随屏幕视图缩放。例如，TC-CAPTCHA 嵌入式模式建议预留至少 300x230 像素空间，以获得最佳渲染效果和用户交互体验。
弹出式交互认证： 验证码界面在认证被调用时，以浮动窗口形式显示在设备屏幕上。与嵌入式认证类似，渲染窗口的大小、层叠顺序和对齐方式也需预设。弹出式认证的特点是，当屏幕视图小于特定阈值时，弹出式认证 GUI 会自动缩放以适应不同屏幕尺寸。例如，TC-CAPTCHA 弹出式模式的初始渲染块大小为 360x360 像素。

基于 JavaScript 的认证场景

某些认证器（例如，使用无感模式的 TC-CAPTCHA）需要 WebView 实例作为 JavaScript 运行时环境，主要用于执行加密工作量证明 (PoW) 挑战。在此场景下，WebView 实例仅提供 JavaScript 执行沙箱，无需可见地渲染任何 UI。因此，传入的 WebView 实例无需可见，SDK 也不会将其用于 UI 渲染。

验证集成

为确保 EdgeOne 客户端认证 SDK 在您的应用中稳定运行，请参考以下关键指标来判断集成是否成功（建议按顺序进行验证排查）：

中国站
目录