排查 Identity Platform 与 reCAPTCHA Enterprise API 集成的问题

本文档提供了有关排查将 Identity Platform 与 reCAPTCHA Enterprise API 集成（包括 reCAPTCHA 机器人防护和 reCAPTCHA SMS defense 功能）时可能出现的潜在问题的指导。

集成初始配置问题排查

您的用户可能会因 Identity Platform 与 reCAPTCHA Enterprise API 集成时出现错误而遇到问题。一些常见原因可能包括：

  • 您可能遗漏了 Identity Platform 与 reCAPTCHA Enterprise API 集成设置中的某个步骤。例如，未设置服务账号或未在项目中启用 reCAPTCHA Enterprise API。确保您已完成所有集成要求。如需了解设置说明，请参阅将 Identity Platform 与 reCAPTCHA Enterprise API 集成。
  • 如果您自带密钥以与 reCAPTCHA 搭配使用，则您上传的相应 reCAPTCHA 密钥可能无效或可能已停止运行。验证密钥是否正常运行且可供 Identity Platform 访问。
  • 用户可能使用的是过时版本的应用。请务必提供使用客户端 SDK 的更新版应用，并要求用户更新其应用。如需为应用设置客户端 SDK，请参阅配置客户端 SDK。

用户无法通过 reCAPTCHA Enterprise API 支持的流程进行身份验证

如果您在使用 reCAPTCHA Enterprise API 支持的流程（例如 reCAPTCHA 机器人防护或 reCAPTCHA SMS defense）时遇到问题，请参阅以下部分，获取针对特定功能的指导。

reCAPTCHA 机器人防护问题排查

以下主题介绍了您在使用漫游器防护功能时可能会遇到的问题以及解决方法。

用户在使用电子邮件-密码或手机提供商的机器人防护功能时无法进行身份验证

如果您已确定 Identity Platform 与 reCAPTCHA Enterprise API 的集成设置正确，则根据您当前的配置，用户可能无法通过电子邮件密码或手机提供商执行身份验证操作。例如，用户可能无法执行以下操作：

  • 通过邮箱登录、注册或重置密码。
  • 请求通过短信接收验证码，以便使用手机号码登录。
  • 注册或使用基于短信的多重身份验证登录。

如需解决这些身份验证问题，请尝试以下操作：

  • 如果用户请求因 ERROR_CAPTCHA_CHECK_FAILED 而失败，请考虑通过调整为 managedRules 设置的阈值来采用更宽松的配置。任何得分低于您设置的阈值的请求都将被视为漫游器。例如，如果您将阈值设置为 0.6，则 reCAPTCHA 将拒绝任何得分为 0.5 或更低的请求。因此，您设置的分数越高，规则就越严格。
  • 请让用户尝试使用其他设备、浏览器或网络。
  • 对于电子邮件-密码身份验证流程，请将 emailPasswordEnforcementState 还原为 AUDIT 模式并监控指标，然后再重新启用 ENFORCE 模式。
  • 对于手机身份验证流程，请调整 managedRules 得分阈值，或在排查问题时为手机提供商停用机器人防护。如果 reCAPTCHA SMS defense 也已启用，并且您希望保持其处于启用状态，请将 useSmsBotScore 设置为 false，并将 phoneEnforcementState 保持设置为 ENFORCE。如需停用所有手机 reCAPTCHA 保护，请将 phoneEnforcementState 设置为 OFF，将 useSmsBotScore 设置为 false，并将 useSmsTollFraudProtection 设置为 false。

reCAPTCHA SMS defense 问题排查

以下主题介绍了您在使用 reCAPTCHA SMS defense 时可能会遇到的问题以及解决方法。

为手机提供商使用 reCAPTCHA SMS defense 时，用户无法进行身份验证

如果您已确定 Identity Platform 与 reCAPTCHA Enterprise API 的集成设置正确，则根据您当前的配置，用户可能无法通过手机提供方执行基于短信的身份验证操作。例如，用户可能无法请求短信验证码来使用手机号码登录，也无法注册或使用多重身份验证登录。如果您设置的 reCAPTCHA SMS defense 分数过于严格，就可能会发生这种情况。

如需解决此问题，请考虑通过调整为 tollFraudManagedRules 设置的阈值来采用更宽松的配置。任何高于您所设阈值的分数都将被视为短信话费欺诈。例如，如果您将阈值设置为 0.3，则 reCAPTCHA 将拒绝任何得分为 0.4 或更高的请求。因此，您设置的分数越低，规则就越严格。

监控项目发出的 reCAPTCHA 指标，以验证应用在调整得分阈值后是否收到可接受的用户流量。

后续步骤