reCAPTCHA Enterprise集成malformed token及invalid site key错误排查

报错场景汇总 #

集成过程中先后触发三类异常，常规调整方案无法解决，具体表现如下：

1. 后端校验令牌返回MALFORMED错误 #

初始阶段参照官方文档在登录页嵌入reCAPTCHA复选框，通过POST请求的g-recaptcha-response参数获取用户校验令牌，调用google-cloud-recaptcha-enterprise库校验令牌有效性时，接口持续返回invalid_reason: MALFORMED错误。
相关代码与返回结果：

# 后端从POST请求提取令牌的核心代码
recaptchaToken = request.form.get("g-recaptcha-response")

# 调用企业版库返回的响应内容（已隐去项目ID、评估ID敏感信息）
# action name: "projects/<project_id>/assessments/<action_id>"
# event {
#   token: "AW-bC4mm022xpjWh2zI7od65_YdX81M6XfBPW5wIJtr8s5XXIzZ6ojfTFl9PjRlDHo601Svqpuyn5E8WhDlcBswXnrPGDbtUHekXcw60deyb8w0wyk1gZA0mJ0Hx9eAhGMI"
#   site_key: "6LfpqZcgAAAAAC7RH7qroayHutXeXkpLuKY5iV6a"
# }
# token_properties {
#   invalid_reason: MALFORMED
#   create_time {
#   }
# }

2. 前端execute接口抛出站点密钥无效错误 #

调整实现逻辑，在grecaptcha.enterprise.execute执行完成后将令牌追加到表单再提交后端，前端控制台抛出Invalid site key or not loaded in api.js错误。
相关代码与报错信息：

// 前端调用execute接口的JS代码
grecaptcha.enterprise.ready(function() {
    grecaptcha.enterprise.execute("6LfpqZcgAAAAAC7RH7qroayHutXeXkpLuKY5iV6a", {action: "login"}).then(function(token) {
        console.log(token);
    });
});

// 控制台报错栈
// Uncaught (in promise) Error: Invalid site key or not loaded in api.js: 6LfpqZcgAAAAAC7RH7qroayHutXeXkpLuKY5iV6a
//     at Array.<anonymous> (recaptcha__en.js:113:393)
//     at recaptcha__en.js:62:400

3. JS资源加载异常 #

引入reCAPTCHA Enterprise JS资源时，必须给render参数后的site_key包裹单引号，否则Google会直接返回Bad Request 400错误，对应可临时绕过报错的引入代码：

<script src="https://www.google.com/recaptcha/enterprise.js?render='6LfpqZcgAAAAAC7RH7qroayHutXeXkpLuKY5iV6a'"></script>

已确认的排查线索 #

• MALFORMED令牌错误与创建密钥时启用Web Application Firewall (WAF) Action Token功能直接相关
• 启用复选框功能时会稳定触发该类错误，新建密钥并禁用复选框选项后功能可正常运行
• 官方文档明确规则：使用WAF action-tokens或session-tokens时无需调用assessment接口做校验，这类令牌需要附加到请求头传递，不能放在表单参数中走常规校验流程。

根因与修复方案 #

核心问题是创建reCAPTCHA Enterprise密钥时误开启WAF令牌功能，同时混淆了三种不同集成模式的实现规则——复选框模式、无交互评分模式、WAF令牌模式的令牌格式、传递要求、校验逻辑完全不通用，混用就会触发上述所有报错。

• 若需使用复选框验证模式：重新创建站点密钥，创建过程中不要勾选WAF Action Token、WAF Session Token相关选项。引入JS SDK时render参数直接传入不带额外引号的站点密钥，前端渲染复选框后，从POST表单的g-recaptcha-response字段提取令牌，调用create_assessment接口走常规校验流程即可，不会再返回MALFORMED错误。
• 若需使用WAF令牌防护模式：不需要在Flask后端调用google-cloud-recaptcha-enterprise库的assessment接口做校验。前端生成的令牌不要存入表单参数，要附加到WAF规则指定的请求头字段中，由前置WAF层直接完成校验。这类WAF专用令牌的格式和普通校验令牌不兼容，强行调用assessment接口必然返回MALFORMED错误。
• 针对“render参数必须给site_key加单引号才不返回400”“execute报站点密钥无效”两个连锁问题：本质都是用开启了WAF特性的密钥跑普通集成逻辑导致的，切换到对应模式的正确密钥、按对应模式的规则引入SDK后，两个问题会同时消失。普通模式下不要给render参数的密钥加额外单引号，否则SDK无法识别正确的密钥值，就会抛出无效key错误。

内容的提问来源于stack exchange，提问作者KJHJason