产品动态
安全公告
产品公告
移动端集成概述
概述
客户端认证通过确保每个 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 收到带有有效认证令牌的请求后，验证令牌的有效性，并允许请求继续流向后端服务。
认证凭证 Token 处理流程
认证令牌是客户端与 EdgeOne 认证服务之间建立信任的关键凭证。在 iOS 或 Android 应用中，开发者需要理解并正确处理认证令牌的生命周期，包括获取、使用和续期。
获取新的认证凭证 Token（或手动认证）
在某些场景下，您可能需要主动触发客户端认证以获取新的认证令牌，例如：
首次请求前： 在应用启动后首次向受保护的 API 发送请求之前，可以主动调用 SDK 进行认证，以避免首次请求就收到 428 挑战。
处理 HTTP 428 挑战： 当收到服务器返回的 HTTP 428 状态码时，需要提取挑战 ID 并调用 SDK 接口发起认证挑战。
强制认证： 业务逻辑需要强制用户进行认证时。
您可以通过调用 SDK 的
attestWithParams() 方法来发起认证挑战。此方法会根据挑战参数执行相应的认证流程，并在成功后通过 AttestCallbackDelegate 返回认证令牌。注意：
每次调用
attestWithParams() 成功后，SDK 都会生成或更新认证令牌。在将令牌附加到请求头之前，务必再次调用 getAttestationToken() 获取最新的令牌，每次需要使用令牌数据时，请重新获取新的令牌数据。请勿保存或重复使用 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 在您的应用中稳定运行，请参考以下关键指标来判断集成是否成功（建议按顺序进行验证排查）：
验证项 1：客户端访问了 EdgeOne 边缘服务
客户端认证需要您的客户端访问 EdgeOne 服务。如您的业务使用了多个 CDN 服务商，只有通过 EdgeOne 提供服务的部分支持客户端认证。
请确保您收到的响应中，包含
EO-LOG-UUID 头部。若响应中未包含该头部，客户端可能访问了 EdgeOne 以外的服务。验证项 2：SDK 成功加载
SDK 需要成功加载后，才能完成客户端认证流程所需流程。
SDK 成功加载后，将访问业务域名的 /.eo-sec-bot/ 服务进行初始化。若未观察到该请求，SDK 可能初始化异常。
验证项 3：完成客户端认证规则配置
客户端认证规则正确配置后，当客户端未进行任何认证流程，直接访问受保护 API 时，将收到 HTTP 428 挑战响应。该响应将携带
EO-Attest-Challenge 头部。说明：
未配置客户端认证规则时，您仍可以通过在客户端调用
attestWithParams() 接口，手动发起认证流程。但由于服务端 API 未受保护，EdgeOne 不会校验认证凭证，也不会响应 HTTP 428 挑战。若客户端未收到 HTTP 428 挑战时，可参考以下流程进行以下排查：
1. 客户端的 API 请求是否访问了正确域名
客户端访问的域名是否已经解析至 EdgeOne 的接入 CNAME，并正常访问 EdgeOne 的边缘节点地址。
2. 客户端请求是否被其他安全策略拦截
若客户端收到了 HTTP 567 等拦截状态码，请记录响应中 EO-LOG-UUID 头部内容，并在 Web 安全分析中，使用请求 ID 筛选条件进行查询，以确认具体的拦截原因。
3. 客户端的 API 请求是否正确匹配到了客户端认证规则
首先，应先确认访问的域名使用了何种 Web 防护策略（站点级策略、域名级策略或者策略模板），在站点的 Web 防护 配置页中，选择对应的策略后，进行进一步配置确认。
然后，确认 Bot 管理 > 客户端认证中，是否配置并启用了规则。规则的匹配条件应当包含 API 请求范围，策略配置应当覆盖对应客户端类型。
验证项 4：客户端正确处理 HTTP 428 挑战
客户端需要正确处理挑战响应，才能进行自适应认证、认证续期等流程。
当客户端收到
HTTP 428 挑战响应后，将进行认证流程，然后重新发起请求。说明：
若您的客户端认证规则配置中，对一个 API 资源使用了多种认证方式（例如：配置了多个规则保护一个 API 资源，或者使用了 SDK 挑战来进行二次认证），客户端将收到多次 HTTP 428 请求，请确保您的客户端处理完每一个挑战后，都重新发起请求。
验证项 5：交互式认证的渲染（可选）
如果您的应用使用了交互式认证（如：交互式验证码），请确保其 UI 能够正确渲染，并响应用户操作。
触发认证流程，检验交互式认证的渲染位置。完成认证后，确认操作流程正常完成。
文档反馈