验证码服务API文档

Size: px

Start display at page:

Download "验证码服务API文档"

麻奠贵
4 years ago
Views:

1 天御业务安全防护验证码服务 API 文档

2 版权声明腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制修改抄袭传播全部或部分本文档内容商标声明及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有本文档涉及的第三方主体的商标, 依法由权利人所有服务声明本文档意在向客户介绍腾讯云全部或部分产品服务的当时的整体概况, 部分产品服务的内容可能有所调整您所购买的腾讯云产品服务的种类服务标准等应由您与腾讯云之间的商业合同约定, 除非双方另有约定, 否则, 腾讯云对本文档内容不做任何明示或模式的承诺或保证第 2 页共 25 页

3 文档目录文档声明... 2 接入说明... 4 内嵌页面方式... 4 后台接入方式验证码接口获取验证码 JS 验证码验证码票据获取验证码图片地址验证用户输入是否正确验证码类型说明第 3 页共 25 页

接入说明内嵌页面方式 1. 调用流程 2. 服务端开发 2.1 获取验证码 JS URL 获取验证码 JS URL 2.2 验证验证码票据验证验证码票据 3. 客户端开发 3.1 PC Web 客户端开发 3.1.1 页面头部引入 JS <!

4 接入说明内嵌页面方式 1. 调用流程 2. 服务端开发 2.1 获取验证码 JS URL 获取验证码 JS URL 2.2 验证验证码票据验证验证码票据 3. 客户端开发 3.1 PC Web 客户端开发页面头部引入 JS  <script type="text/javascript" src="xxx"></script> 第 4 页共 25 页

5 3.1.2 添加验证码展示控件   <div id="tcaptcha" style="width:230px;height:54px;" ></div> 初始化并显示验证码 : <script type="text/javascript"> var capoption=callback :cbfn; capinit(document.getelementbyid("tcaptcha"), capoption); // 回调函数 : 验证码页面关闭时回调 function cbfn(retjson) if(retjson.ret==0) // 用户验证成功 else // 用户关闭验证码页面, 没有验证 </script> 完整页面代码示例 <html> <head>  <script type="text/javascript" src="xxx"></script> </head> 第 5 页共 25 页

6 <body>   <div id="tcaptcha" style="width:230px;height:54px;" ></div> </body> </html> <script type="text/javascript"> var capoption=callback :cbfn; capinit(document.getelementbyid("tcaptcha"), capoption); // 回调函数 : 验证码页面关闭时回调 function cbfn(retjson) if(retjson.ret==0) // 用户验证成功 else // 用户关闭验证码页面, 没有验证 </script> 3.2 手机 Web 客户端开发页面头部引入 JS  <script type="text/javascript" src=""></script> 初始化并显示验证码 : 第 6 页共 25 页

7 <script type="text/javascript"> var capoption=callback :cbfn, showheader :true; capinit(document, capoption); // 回调函数 : 验证码页面关闭时回调 function cbfn(retjson) if(retjson.ret==0) // 用户验证成功 else // 用户关闭验证码页面, 没有验证 </script> 完整页面代码示例 <html> <head>  <script type="text/javascript" src="xxx"></script> <meta name="viewport" content="initial-scale=1.0, maximumscale=1.0, minimum-scale=1.0, user-scalable=no, width=device-width"> </head> <body>  </body> </html> <script type="text/javascript"> var capoption=callback :cbfn, showheader :true; capinit(document, capoption); 第 7 页共 25 页

8 // 回调函数 : 验证码页面关闭时回调 function cbfn(retjson) if(retjson.ret==0) // 用户验证成功 else // 用户关闭验证码页面, 没有验证 </script> 4. javascript 接口说明函数名 capinit(iframe_div, options) 描述初始化并显示验证码输入参数 : 1 iframe_div( 必填 ): 嵌入验证码 iframe 的元素 2 options( 选填 ): json 格式对象 callback:xxx, showheader:xxx 其中 callback: 验证码页面关闭时的回调函数它的参数是 json 格式验证结果 ret:xxx,ticket:" xxx",randstr:"xxx",ret=0 表示用户验证完成, 业务可以校验 ticket;ret=1 表示用户未验证验证码, 此时没有 ticket 和 randstr 参数 showheader: 类型 boolen, 是否显示验证码页面的 header( 返回和帮组 ),false 不显示,true 显示只对手机页面有效 capgetticket() 获取验证码验证结果返回 Josn 格式数据 ticket:"xxx", randstr: "xxx" 其中 tic ket 是验证码验证成功票据, 如果票据为空表示验证码验证没通过 caprefresh() 刷新验证码第 8 页共 25 页

9 函数名描述要求用户重新验证当票据验证失败时也可调用该接口刷新验证码 5. 接入规范 1) 请不要使用 iframe 页面嵌入验证码验证码弹出的 iframe 框大小会变化, 如果业务使用 iframe 会导致验证码 iframe 页面显示不全 2)PC 预留给验证码展示的地方尺寸不能小于 362px( 宽 )*40px( 高 ), 否则会导致验证码显示异常而影响用户使用 3)PC 页面必须设置验证码显示页面初始宽高 4) 手机验证码页面要全屏显示, 否则验证码页面会显示异常影响用户使用 5. 样例代码样例代码第 9 页共 25 页

10 后台接入方式 1. 调用流程 2. 服务端开发 2.1 获取验证码图片地址获取验证码图片地址 2.2 获取验证码图片获取验证码图片地址之后, 即可获取到对应的验证码图片和验证码签名, 图片和签名是一一对应的, 其中图片在 HTTP 的 body 中返回, 验证码签名是在名称为 vsig 的 cookie 里, 验证时需要带上该签名 HTTP/ OK Server: nginx/1.6.0 Date: Wed, 30 Mar :54:12 GMT Content-Type: image/jpeg Content-Length: 1848 Connection: keep-alive Accept-Ranges: bytes Pragma: No-cache P3P: CP=CAO PSA OUR Set-Cookie: vsig=b011hpjymfjjnhtpbwa_9cg-kqmk1lzqvtsrxyhptly4tqeo1-iyumtclmtynih 第 10 页共 25 页

11 dcrfz5twd9l6oaf5jfg_xteg7dnpnijdwnpmipvdquxndu*; PATH=/; DOMAIN=guard.qcloud.com; 2.2 验证用户输入是否正确验证用户输入是否正确该接口的中 captchasig 是获取验证码图片的时候返回的验证码签名 3. 接入规范 1) 后台接入方式只支持字符验证码 2) 字符验证码图片尺寸为 130*53, 业务展示时请勿缩放验证码图片, 缩放图片尺寸会导致图片内容模糊不清, 用户无法识别 3) 输入框请勿限制用户输入字符数 ( 如果限制建议不小于 18), 因为验证码长度可能变化 4) 请勿限制用户输入的字符格式, 因为可能会对码工打码的请求下发中文 5) 请业务展示验证码图片时支持 jpg gif, 否则会导致验证码无法显示第 11 页共 25 页

12 验证码接口获取验证码 JS 1. 接口描述协议 :HTTPS 域名 :csec.api.qcloud.com 接口名 : CaptchaIframeQuery 获取验证码的 JavaScript 连接, 通过将验证码的 JavaScript 嵌入页面实现验证码的刷新和验证操作 2. 输入参数参数名称必选类型描述 accounttype 可选 UInt 用户账号类型 0: 其他账号 1:QQ 开放帐号 2: 微信开放帐号 4: 手机账号 6: 手机动态码 7: 邮箱账号 appid 可选 stringaccounttype 是 QQ 或微信开放账号时, 该参数必填, 表示 QQ 或微信分配给给网站或应用的 appid, 用来唯一标识网站或应用 uid 可选 string 用户 ID accounttype 不同对应不同的用户 ID 如果是 QQ 或微信用户则填入对应的 openi d associateaccount 可选 stringaccounttype 是 QQ 或微信开放账号时, 用于标识 QQ 或微信用户登录后关联业务第 12 页共 25 页

13 参数名称必选类型描述自身的账号 ID registertime 可选 UInt 注册时间戳, 单位秒 userip 可选 string 用户操作来源的外网 IP xforwardedfor 可选 string 用户 Http 请求中的 x_forwa rd_for captchatype 可选 string 验证码类型 disturblevel 可选 string 验证码干扰程度 ishttps 可选 string 返回的 JavaScript 中是否使用 HTTPS 0:HTTP 1:HTPS clienttype 可选 UInt 客户端类型 1: 手机 Web 页面 2:PCWeb 页面 3: APP macaddress 可选 stringmac 地址或设备唯一标识 imei 可选 string 手机设备号 businessid 可选 UInt 业务 ID 网站或应用在多个业务中使用此服务, 通过此 ID 区分统计数据 sceneid 可选 UInt 场景 ID 网站或应用的业务下有多个场景使用此服务, 通过此 ID 区分统计数据 3. 输出参数参数名称类型描述 url string 验证码 JavaScript 地址, 该链接单次有效 4. 示例第 13 页共 25 页

14 输入 &accounttype=4 &appid= &associateaccount= &businessid=0 &captchatype=5 &clienttype=1 &disturblevel=0 &imei= &ishttps=1 &macaddress= a-3c-7a-00 &registertime= &sceneid=1 &uid= &userip= &xforwardedfor= &COMMON_PARAMS 输出 "code":0, "message":"no Error", "url": " entype=1&lang=2052&asig=-dhjtukdwlzjpmifamasxfn1y6zckrqun8werrs4lvnmudcuodiyylmo Kqd-Ev77Eogpq97Dpb69_MrwGjWXKmTGg9y9iW7wjdriTu_y6WBN4qGsHn6VRk0W1hLB6ZWvqHqw2E5I FCRUcGrHBzMF7A**" 第 14 页共 25 页

15 5. 样例代码样例代码第 15 页共 25 页

16 验证码验证码票据 1. 接口描述协议 :HTTPS 域名 :csec.api.qcloud.com 接口名 : CaptchaCheck 用户输入验证码之后会获取 API 返回的票据, 必须将此票据通过本接口进行校验, 以确认票据是从安全 API 返回的, 否则将可能导致验证码功能被绕过 2. 输入参数参数名称第 16 页共 25 页

17 第 17 页共 25 页

18 获取验证码图片地址 1. 接口描述协议 :HTTPS 域名 :csec.api.qcloud.com 接口名 : CaptchaGetUrl 2. 输入参数参数名称必选类型描述 accounttype 可选 UInt 用户账号类型 0: 其他账号 1:QQ 开放帐号 2: 微信开放帐号 4: 手机账号 6: 手机动态码 7: 邮箱账号 appid 可选 stringaccounttype 是 QQ 或微信开放账号时, 该参数必填, 表示 QQ 或微信分配给给网站或应用的 appid, 用来唯一标识网站或应用 uid 可选 string 用户 ID accounttype 不同对应不同的用户 ID 如果是 QQ 或微信用户则填入对应的 openi d associateaccount 可选 stringaccounttype 是 QQ 或微信开放账号时, 用于标识 QQ 或微信用户登录后关联业务自身的账号 ID registertime 可选 UInt 注册时间戳, 单位秒 userip 可选 string 用户操作来源的外网 IP 第 18 页共 25 页

19 参数名称必选类型描述 xforwardedfor 可选 string 用户 Http 请求中的 x_forwa rd_for captchatype 可选 string 验证码类型 disturblevel 可选 string 验证码干扰程度 ishttps 可选 string 是否返回 HTTPS 的 URL 0:HTTP 1:HTPS macaddress 可选 stringmac 地址或设备唯一标识 imei 可选 string 手机设备号 businessid 可选 UInt 业务 ID 网站或应用在多个业务中使用此服务, 通过此 ID 区分统计数据 sceneid 可选 UInt 场景 ID 网站或应用的业务下有多个场景使用此服务, 通过此 ID 区分统计数据 3. 输出参数参数名称类型描述 url string 验证码图片地址 4. 示例输入 &accounttype=4 &appid= &associateaccount= &businessid=0 &captchatype=5 &disturblevel=0 第 19 页共 25 页

20 &imei= &ishttps=1 &macaddress= a-3c-7a-00 &sceneid=1 &uid= &userip= &xforwardedfor= &COMMON_PARAMS 输出 "code":0, "message":"no Error", "url": " &buid=0&sceneid=1&asig=cPzM3rJU7lwyx0zfgncVB7heUkCnh7fQPm-p-oUKMKecYy2e4 Lyd2sV0pxwDUc4-iMmyiLdZv2oDZgV6p9XVNJ- ExTc01mowCLMEbu_OLW2znNfAoEpyedKbrnPDy7vZf5aSjryaOUROd7sjDUWqZg**" 5. 样例代码样例代码第 20 页共 25 页

21 验证用户输入是否正确 1. 接口描述协议 :HTTPS 域名 :csec.api.qcloud.com 接口名 : CaptchaVerify 2. 输入参数参数名称必选类型描述 accounttype 可选 UInt 用户账号类型 0: 其他账号 1:QQ 开放帐号 2: 微信开放帐号 4: 手机账号 6: 手机动态码 7: 邮箱账号 appid 可选 stringaccounttype 是 QQ 或微信开放账号时, 该参数必填, 表示 QQ 或微信分配给给网站或应用的 appid, 用来唯一标识网站或应用 uid 可选 string 用户 ID accounttype 不同对应不同的用户 ID 如果是 QQ 或微信用户则填入对应的 openi d associateaccount 可选 stringaccounttype 是 QQ 或微信开放账号时, 用于标识 QQ 或微信用户登录后关联业务自身的账号 ID registertime 可选 UInt 注册时间戳, 单位秒 userip 可选 string 用户操作来源的外网 IP 第 21 页共 25 页

22 参数名称必选类型描述 xforwardedfor 可选 string 用户 Http 请求中的 x_forwa rd_for captchasig 必选 string 验证码图片的签名 verifycode 必选 string 验证码输入字符 captchatype 可选 string 验证码类型, 参考验证码类型说明 macaddress 可选 stringmac 地址或设备唯一标识 imei 可选 string 手机设备号 businessid 可选 UInt 业务 ID 网站或应用在多个业务中使用此服务, 通过此 ID 区分统计数据 sceneid 可选 UInt 场景 ID 网站或应用的业务下有多个场景使用此服务, 通过此 ID 区分统计数据 3. 输出参数参数名称类型描述 is_right UInt 0: 输入验证码错误 1: 输入验证码正确 4. 示例输入 &accounttype=4 &appid= &associateaccount= &businessid=0 &captchasig=b01b-qy1zgpgg8v3wciau3hvwndkyhwgnfqzsxtum4jh- 第 22 页共 25 页

23 yi8iiqfejqyltxfb3mvpda26gnigegyfwcbfcw6178x85fsws-qwtdrklpsp8hrsk* &captchatype=5 &imei= &macaddress= a-3c-7a-00 &sceneid=1 &uid= &userip= &verifycode=uazm &xforwardedfor= &COMMON_PARAMS 输出 "code":0, "message":"no Error", "is_right":0 5. 样例代码样例代码第 23 页共 25 页

24 验证码类型说明 1. 验证码类型说明天御验证码提供了固定类型和按策略下发类型两种选择, 如果通过接口参数 (captchatype 和 disturblevel) 设定类型只会下发指定的验证码类型和难度, 如果未通过参数 (captchatype 和 disturblevel) 设定类型, 则天御验证码策略会根据请求的恶意情况下发不同类型和难度的验证码注 : 下图展示一些不同难度的验证码图片例子, 验证码为了保证持续对抗能力, 会实时监控破解率切换干扰, 实际下发的图片干扰不仅这些, 但同一难度的验证码会经过测试保证其通过率 2. 参数设置与验证码类型 captchatype disturblevel 示例用户验证通过率说明 1 1 >90% 策略判断请求没有明显恶意时下发 1 2 >80% 策略判断请求有明显恶意时下发 4 1 >85% 后台接入方式不支持 5 1 >90% 主要用于对人工破解验证码, 也具备自动第 24 页共 25 页

25 Powered by TCPDF ( 机对抗能力策略判断请求没有明显恶意时下发 5 2 >80% 主要用于对人工破解验证码, 也具备自动机对抗能力策略判断请求有明显恶意时下发第 25 页共 25 页

其他服务API文档

其他服务API文档天御业务安全防护其他服务 API 文档版权声明 2015-2016 腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制修改抄袭传播全部或部分本文档内容商标声明及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有本文档涉及的第三方主体的商标, 依法由权利人所有服务声明本文档意在向客户介绍腾讯云全部或部分产品