如何将验证码1.0升级到2.0
本文将为您介绍如何将已集成的阿里云验证码1.0平滑升级到验证码2.0,提升安全性和用户体验。
前提条件
已开通阿里云验证码2.0服务。
已在验证码2.0控制台中成功创建验证场景。
客户端升级步骤
完整验证码2.0客户端代码请参见Web和H5客户端V3架构接入。
资源引入替换
删除验证码1.0的JS资源引用代码
<script src="https://g.alicdn.com/AWSC/AWSC/awsc.js"></script>
在HTML的head标签中添加全局变量配置,并动态引入验证码2.0的JS资源
<script> window.AliyunCaptchaConfig = { // 必填,验证码示例所属地区,支持中国内地(cn)、新加坡(sgp) region: "cn", // 必填,身份标。开通阿里云验证码2.0后,您可以在控制台概览页面的实例基本信息卡片区域,获取身份标 prefix: "xxxxxx", }; </script> <script type="text/javascript" src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"></script>
初始化代码升级
验证码1.0初始化代码示例(旧)
<div id="nc"></div>
<script>
// 实例化nc
AWSC.use("nc", function (state, module) {
// 初始化
window.nc = module.init({
// 应用类型标识。它和使用场景标识(scene字段)一起决定了滑动验证的业务场景与后端对应使用的策略模型。您可以在阿里云验证码控制台的配置管理页签找到对应的appkey字段值,请务必正确填写。
appkey: "CF_APP_1",
//使用场景标识。它和应用类型标识(appkey字段)一起决定了滑动验证的业务场景与后端对应使用的策略模型。您可以在阿里云验证码控制台的配置管理页签找到对应的scene值,请务必正确填写。
scene: "register",
// 声明滑动验证需要渲染的目标ID。
renderTo: "nc",
//前端滑动验证通过时会触发该回调参数。您可以在该回调参数中将会话ID(sessionId)、签名串(sig)、请求唯一标识(token)字段记录下来,随业务请求一同发送至您的服务端调用验签。
success: function (data) {
window.console && console.log(data.sessionId);
window.console && console.log(data.sig);
window.console && console.log(data.token);
},
// 滑动验证失败时触发该回调参数。
fail: function (failCode) {
window.console && console.log(failCode);
},
// 验证码加载出现异常时触发该回调参数。
error: function (errorCode) {
window.console && console.log(errorCode);
},
});
});
</script>
验证码2.0初始化代码示例(新)
<div id="captcha-element"></div>
<button id="button" class="btn">登录</button>
<!--3.新建一个<script>标签,用于调用验证码初始化函数initAliyunCaptcha-->
<script type="text/javascript">
var captcha;
// 弹出式,除region和prefix以外的参数
window.initAliyunCaptcha({
// 场景ID。根据步骤二新建验证场景后,您可以在验证码场景列表,获取该场景的场景ID
SceneId: "******",
// 验证码模式,popup表示弹出式,embed表示嵌入式。无需修改
mode: "popup",
// 页面上预留的渲染验证码的元素,与原代码中预留的页面元素保持一致。
element: "#captcha-element",
// 触发验证码弹窗或无痕验证的元素
button: "#button",
// 验证码验证通过回调函数
success: function (captchaVerifyParam) {
// 入参为验签captchaVerifyParam
// 1.向后端发起业务请求进行验证码验签captchaVerifyParam校验
// 2.根据校验结果来进行业务处理
// 3.如业务需要重新进行验证码验证,调用验证码初始化方法initAliyunCaptcha重新初始化验证码
},
// 验证码验证不通过回调函数
fail: function (result) {
// 入参为不通过信息
// 正常验证有效期内不需要做任何操作,验证码自动刷新,重新进行验证
console.error(result);
},
// 绑定验证码实例回调函数,该回调会在验证码初始化成功后调用
getInstance: function (instance) {
captcha = instance;
},
// 滑块验证和一点即过的验证形态触发框体样式,支持自定义宽度和高度,单位为px。兼容历史参数名。
slideStyle: {
width: 360,
height: 40,
},
// ...其他参数,参考initAliyunCaptcha参数说明
});
</script>
参数映射对照表
验证码1.0参数 | 验证码2.0对应参数 | 验证码2.0参数说明 |
appkey | prefix | 验证码身份标识,开通验证码2.0后,可获取该值。 |
scene | SceneId | 验证码场景ID,新建验证场景后可获取该值。 |
renderTo | element | 渲染容器选择器。 |
success | success | 验证通过回调函数。 |
fail | fail | 验证失败回调函数。 |
error | onError | 验证码加载出现异常时触发该回调参数。验证码2.0中在初始化接口请求和验证码资源加载失败、超时触发该回调。 |
foreign | region | 地域配置,验证码2.0中通过全局变量 |
width | slideStyle | 滑块宽度,验证码2.0中建议最小值320px,通过slideStyle对象配置。 |
服务端升级步骤
推荐您使用SDK集成的方式接入验证码2.0,具体操作,请参见下载并安装SDK。
调用API对照表
验证码1.0接口 | 验证码2.0接口 |
AuthenticateSig :滑动验证和智能验证服务端调用接口。 | 统一调用VerifyIntelligentCaptcha接口,不区分形态。 |
AnalyzeNvc:无痕验证服务端调用接口。 |
入参对照表
验证码1.0入参 | 验证码2.0入参 | ||||
名称 | 描述 | 示例值 | 名称 | 描述 | 示例值 |
Token | 123e4567-e89b-12d3-a456-426655440000 | CaptchaVerifyParam | 由验证码脚本回调的验证参数,直接将全部参数信息由客户端传给服务端即可。 | eyJjZXxxxxxxxxxxxxxxnVlfQ== | |
Sig | 1 | ||||
SessionId | 3D13211111111 | ||||
Scene | 使用场景标识,与前端页面填写数据一致。在统计报表中将根据该字段的内容进行分类展示。 | Scene | SceneId | 由您服务端写入本次验证对应的场景ID,建议传入,尤其在多场景下,防止前端被篡改为其他场景。 | Udw***d72 |
AppKey | 阿里云验证码配置对应的Appkey。 | CF_APP_1 | / | ||
RemoteIp | 客户端IP。 | 192.168.XX.XX |
返回信息对比
验证码1.0返回信息
名称 | 类型 | 描述 | 示例值 |
RequestId | string | 请求ID。 | B0AEA6F4-14B3-5B94-8E8B-04889C1C1336 |
Msg | string | 调用返回信息。 | pass_1 |
Code | string | 阿里云验证码结果编码,取值:
| 100 |
验证码2.0返回信息
名称 | 类型 | 描述 | |||
HTTP Status Code | Integer | HTTP状态码。更多信息,请参见返回参数说明。 | |||
HTTP Body | RequestId | String | 请求ID。 | ||
Success | Boolean | 请求是否成功。
| |||
Code | String | 返回码。更多信息,请参见返回参数说明。 | |||
Message | String | 返回详细信息。更多信息,请参见返回参数说明。 | |||
Result | VerifyResult | Boolean | 验证结果。
| ||
VerifyCode | String | T001 | 服务端校验通过。 | ||
T005 | 控制台开启测试模式,且配置了验证通过。如有疑问,请登录验证码2.0控制台查看对应场景的策略状态的配置。具体操作请参见接入指引。 | ||||
F001 | 疑似攻击请求,风险策略不通过。如有疑问,您可以提交工单进行排查。 | ||||
F002 | 您传入的 | ||||
F003 | 您传入的 | ||||
F004 | 控制台开启测试模式,且配置了验证不通过。如有疑问,请登录验证码2.0控制台查看对应场景的策略状态配置。具体操作请参见场景管理。 | ||||
F005 | CaptchaVerifyParam中的场景ID(sceneId)不合法,CaptchaVerifyParam是由前端自动获取并传给您的服务端,服务端不能做任何更改,直接传给阿里云。请参考发起认证请求检查您的集成代码。 | ||||
F006 |
| ||||
F008 | 验证数据重复提交。同一笔验证码请求只允许提交一次。 | ||||
F009 | 检测到虚拟设备环境,请检查是否使用vmware、virtualbox、hyper-v、parallels等虚拟机,avd、blue stacks、vbox/hyper-v等模拟器,桌面浏览器模拟移动设备等。如不需要拦截,请登录验证码2.0控制台自定义策略中关闭,具体操作请参见设置自定义策略。 | ||||
F010 | 同IP访问频率超出限制。如果需要自定义频率阈值,请登录验证码2.0控制台自定义策略进行配置,具体操作请参见设置自定义策略。 | ||||
F011 | 同设备访问频率超出限制。如果需要自定义频率阈值,请登录验证码2.0控制台自定义策略进行配置,具体操作请参见设置自定义策略。 | ||||
F012 | 您服务端参数里传入的SceneID需要与前端配置的场景ID(SceneId)保持一致。 | ||||
F013 | 您传入的 | ||||
F014 | 无初始化记录,可能存在两种原因:
| ||||
F015 | 验证交互不通过。例如拼图没有滑动到正确位置,可以刷新验证码重新完成交互。 | ||||
F016 | 控制台自定义策略配置URL验证导致不通过,请登录验证码2.0控制台自定义策略中URL验证策略进行调整,具体操作请参见设置自定义策略。 | ||||
F017 | 疑似攻击请求,协议或参数异常不通过。 | ||||
F018 | V3架构下,业务验签请求入参CaptchaVerifyParam重复使用。 | ||||
F019 | V3架构下,行为验证请求和业务验签请求间隔超出90秒或未发起行为验证就直接进行业务验签请求。 | ||||
F020 | V3架构下,业务验签请求的CaptchaVerifyParam与场景ID或用户不匹配。 |
返回参数HTTP Status Code、Code、Message的详细说明,如下表所示。
HTTP Status Code | Code | Message |
200 | Success | 成功。 |
400 | MissingParameter | 缺少必须参数。 |
401 | InvalidParameter | 参数不合法。 |
403 | Forbidden.AccountAccessDenied | 无权限,可能是未开通服务,或已欠费。 |
403 | Forbidden.RAMUserAccessDenied | RAM用户无权限,请授权 AliyunYundunAFSFullAccess。具体操作,请参见为RAM角色授权。 |
500 | InternalError | 系统内部错误,建议重试。如果仍然报错,请提交工单联系我们。 |
测试说明
在将前端接入代码集成至Web页面后,建议您在正式上线前进行充分测试。对于客户端接入测试,可以参考接入验证进行验证;对于验证通过/不通过的测试,可使用验证码2.0场景管理中的测试模式功能进行测试验证。
升级后验证清单
前端组件渲染:确认验证码弹出式/嵌入式组件正常显示,交互无异常。
回调函数触发:验证通过或失败时,success或fail回调正确返回参数。
风险策略验证:模拟异常行为(如快速滑动、重复提交),确认拦截机制生效。
服务端结果返回符合预期。
通过以上步骤,可完成从阿里云验证码1.0到2.0的平滑升级,享受验证码2.0在验证形态、安全防护、性能优化上的升级能力。