本帖最后由 新手693503 于 2021-3-9 16:17 编辑
1.1功能概述
aTrust支持对接http/https短信网关平台,用于实现用户或管理员的双因素认证、绑定授信终端等功能。设备内置了某公司短信认证与某公司短信认证配置模板,简化配置工作,同时设备支持配置自定义http/https短信认证服务器。本篇文章主要讲述如何对接华为云短信接口以及短信网关服务器整体对接思路,供各位参考。
2.1华为云短信API
华为云消息&短信服务提供了多种不同类型的短信接口,包括发送短信API、发生分批短信API、接受状态报告API以及接收上行短信API。在此我们需要关注的只有发送短信API,其它类型的接口暂时不做介绍。
2.2整体配置思路
2.2.1准备关键参数 华为云发送短信API,该接口用于客户端请求华为云短信业务平台向指定用户发送短信。要使用该接口,我们需要向客户获取以下关键信息(创建短信应用后,登录管理控制台获取): 参数名称 | | | | | | | 申请短信签名后获取,在请求Body参数中作为短信发送方的号码标识。 | | 申请短信模板并通过审核后获取,作为短信模板的标识,决定短信的固定格式。 |
2.2.2配置基础信息 获取以上关键信息后,我们就可以开始配置aTrust短信认证服务器,首先在设备上新建短信认证服务器-自定义HTTP(S)短信认证。若在此处没有短信认证服务器配置,请在“系统管理”-“特性中心”中检查短信认证功能是否被禁用。
认证配置根据需求自定义填写。
2.2.3配置请求
请求配置是整个短信服务器配置中最关键的配置,该处配置决定了aTrust向短信认证平台发送请求时所构造的http报文格式与参数内容。请各位按照官方参考文档或讲解进行配置,并仔细检查参数是否无误: 1) 请求地址:华为云发送短信API接口类型固定请求方式为POST、访问URI为/sms/batchSendSms/v1、通信协议HTTPS。结合之前获取到的APP接入地址,作为完整的请求地址填入。完整实例:https://rtcsms.cn-north-1.myhuaweicloud.com:10743/sms/batchSendSms/v1 2) 请求头部:请求头配置时,通常只包含http报文的编码信息,在调用华为云发送短信api时,还会包含允许短信发送,以及合法身份验证的请求字段,与对接某公司云图短信平台有明显差异,请注意。 参数名称 | | | 该参数说明http报文的编码格式。固定取值为:application/x-www-form-urlencoded。 | | 用于标识认证,固定取值为:WSSE realm="SDP",profile="UsernameToken",type="Appkey"。 | | 包含认证信息,取值为:UsernameToken Username="app_key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。此处取值较为复杂,将详细讲解。 |
X-WSSE是一种验证机制,是提供于Web服务上应用安全的方法的网络传输协议,需要在http头部中包含Authorization和X-WSSE两个特殊参数。在华为云短信API中,X-WSSE参数需要包含的四个值为Username、PasswordDigest、Nonce与Created。其中Nonce是长度为1~128位,可包含数字和大小写字母的字符串,示例:66C92B11FF8A425FB8D4CCFE0ED9ED1F;Created为随机数生成时间,采用标准UTC格式,例如:2018-02-12T15:30:20Z;PasswordDigest参数,是根据PasswordDigest= Base64 (SHA256 (Nonce + Created + Password))生成(Password为app_secret的值):首先使用SHA256对随机数+生成时间+pwd进行转换。注意,在转换时直接将以上三个字符串拼接在一起即可,中间不要加号与空格,推荐使用在线工具进行转换(http://ontool.cn/sha/)。 转换完成之后我们可以获得一串经过SHA256加密的字符串,再将该字符串进行Base64编码(https://base64.us/)。最后获取到的值,就是我们需要填写为PasswordDigest的值。
----------------------------------------------------分割线-------------------------------------------------------------
请注意:由于通过X-WSSE方式进行鉴权,生成随机数的时间不能与发送请求时的本地时间相差太大(具体数值可向华为云管理员确认),否则会导致鉴权失败。所以通过上述手动方式进行配置,手动生成PasswordDigest的方式,可以实现短时间内的正常使用,并且验证短信云对接的有效性。如果需要长期使用,需要启用自定义请求变量,完成参数的自动生成,具体配置请联系研发技术支持。
3) 请求体:完成请求头部的配置之后,请求URL参数与请求Cookie留空不做配置,我们还需要配置请求体。请求体Body中主要的字段有,短信的接收人、接收人的用户名、接收人的手机号以及验证码等信息。并且根据用户需求,我们可能还需要在Body处添加一些自定义信息,这一部分内容由固定的格式、参数加上变量信息所构成,目前aTrust正式版本所提供的变量值(用于编辑短信内容)为用户名:user.user_name、手机号码:user.mobile_phone与·验证码:env.code,若需要其它自定义变量,需要联系研发进行开发。 对接华为云短信服务时,需要使用到的必选参数有三种。from:代表短信发送方的号码,对应2.2.1关键参数中的签名通道号;to:代表短信接收方的号码,标准号码格式为:+{国家码}{地区码}{终端号码},在aTrust中使用系统内置变量{{user.mobile_phone}}表示即可;templateId:短信模板ID,用于唯一标识短信模板,对应2.2.1关键参数中的模板ID。以上三类参数在构造请求时必须携带。 完整构造实例如下:from=1069031221280012&to=%2B8615512345678&templateId=abcdefghabcdefghabcdefghabcdefgh&templateParas=%5B%22520520%22%5D&statusCallback=http%3A%2F%2F205%2E145%2E111%2E168%3A9330%2Freport
除开以上三类必选参数,华为云短信API还提供了多种可选参数以实现更多个性化需求,在这里仅讲述较为常用的templateParas参数,其余参数若感兴趣,可在华为云官方文档处自行学习。
在讲述参数templateParas之前,我们先来看一下短信模板,这里是华为云短信平台提供的一些模板示例:
图中的${1}表明模板的此处位置为一个变量,会根据短信客户端所发起的请求而发生变化,在aTrust用户双因素认证等场景下,用户在登录时获取到短信验证码,这个验证码是由aTrust服务器生成,包含在发往短信网关的请求中,最后再由短信网关将该验证码发送至用户的手机。对于例如验证码这样一类并不固定的变量,我们将会用到templateParas来进行表示,最终实现将变量传递至模板内。 注意,在使用aTrust构造Body的templateParas参数时,需要将env.code或其它参数使用[ ]进行标注,写作[env.code],否则服务端将返回system error,短信发送失败。
2.2.4响应配置 响应配置是发送短信请求成功发送至短信网关之后,短信网关判断请求是否成功,返回的响应信息。其中返回的必选参数包含code与description,分别用于表示请求返回的结果妈与请求返回的结果码描述。这里是华为云返回的成功请求示例(Body):{"result":[{"originTo":"+8615512345678","createTime":"2018-05-25T16:34:34Z","from":"1069031221280012","smsMsgId":"d6e3cdd0-522b-4692-8304-a07553cdf591_8539659","status":"000000"}],"code":"000000","description":"Success"} 在这里我将认证成功条件配置为description相等于Success,也可以根据成功响应结果,使用code码或其它参数进行配置。最后根据需求配置短信发送提示,通过”发送测试短信“验证短信发送正常之后,即可完成配置。
2.3故障排查思路
在完成配置之后,如果使用“发送测试短信”功能,提示短信发送失败,我们需要前往审计中心-日志中心-管理员日志处查看服务器返回的结果码与描述,根据短信网关的结果码提示去排查故障原因。 例如在上述示例中,我们前往审计中心查看错误日志,发生返回的结果码为E000112,在华为云官网的API手册中,可以找到结果码对应的错误提示,最终定位到问题原因是账号欠费被冻结,导致的无法使用,完成问题的排查。 注意,当设备提示错误,并且无法获取到短信网关返回的状态时,应该排查设备的网络连通性是否正常,特别是设备是否能够与短信网关请求地址进行通信,具体操作可以在设备的webconsole界面或设备后排对相应端口进行telnet测试,以此判断网络的连通性。如果设备部署高安全性、在无法联网的环境下,需要单独放通与短信网关之间的交互地址。
3.1总结 |