为确保 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 能够正确渲染,并响应用户操作。
触发认证流程,检验交互式认证的渲染位置。完成认证后,确认操作流程正常完成。