御城河
账号风控接入(物流)
接入方式
基于帐号密码的登录方式一般交互过程如图1所示：
- 用户在登录界面输入帐号、密码，点击登录
- 服务器端验证帐号密码是否正确
- 如果不正确，返回登录页面，并提示帐号不存在或密码输入错误等信息
- 如果正确，进入系统；
图1. 没有接入风控系统的登陆过程
接入风控系统后，登录流程如图2所示。绿色框表示服务器端新增的流程。
- 用户在登录页面输入帐号、密码，点击登录
- 服务器端验证帐号密码是否正确。不管登录成功与否，都需要把登录日志实时发送给风控系统
- 如果不正确，返回登录页面，并提示帐号不存在或密码输入错误等信息
- 如果正确，调用风险控制接口，判断本次登录是否有风险
- 如果有风险，调用短信二次验证流程
- 否则，进入系统。
图2. 接入风控系统的登陆过程
对接准备
由于二次身份验证基于手机短消息，应用需要提供为帐号绑定、解绑、更换手机号码的功能，补全用户的手机信息。可以参考淘宝帐号管理中的手机绑定解绑功能。几个注意点：
- 手机信息为用户敏感信息，需要加密存储。
- 在绑定、更换手机时，请使用应用已有的安全措施验证用户身份，比如通过邮箱或密码问题等，以避免绑定到非法手机。
- 绑定、解绑、更换号码动作为高危操作，需要保存操作日志。
B/S架构对接细节
如图3所示：
- 用户从登录页面登录
- 服务器端在验证完账号密码后，无论验证成功与否，实时调用login发送登录日志
- 如果验证失败，返回错误；如果验证成功，调用computeRisk计算风险
- 判断风险值，如果判定为有风险，进入二次验证流程
- 提供应用的redirectURL，调用getVerifyUrl获取二次验证URL
- 返回302跳转给客户端浏览器，跳转到我们提供的二次验证页面
- 用户交互：获取验证码，并输入，确认
- 我们的服务后台判断二次验证结果，并回调到应用的redirectURL
- 调用isVerifyPassed获取验证结果，如果通过，登录成功，否则失败
图3. B/S架构接入账号风控系统流程图
C/S架构对接细节
如图5所示：
- 用户从客户端登录
- 服务器端在验证完账号密码后，无论验证成功与否，实时调用login发送登录日志
- 如果验证失败，返回错误；如果验证成功，调用computeRisk计算风险
- 判断风险值，如果判定为有风险，进入二次身份验证流程
- 调用getVerifyToken获取二次验证Token
- 显示二次验证界面，界面如图4所示，手机号码需要做模糊化处理
- 用户点击发送验证码，在服务器端调用sendVerifyCode发送验证码，服务器端有调用频率控制，目前60秒内只能发送一条短消息
- 用户点击确认后，在服务器端调用checkVerifyCode对比验证码
- 验证码对比通过后，调用isVerifyPassed获取验证结果，如果通过，登录成功，否则失败。
图4. C/S架构二次验证界面效果图
图5. C/S架构接入账号风控系统流程图
用户风险重置
如果有正常用户反馈风险误报，用户又无法通过短信二次验证来自动重置风险时，接入方可以实现一个后台工具，手动调用resetRisk接口来重置对应用户风险。
API调用说明
注意事项
API调用时设定合理的调用超时时间。如果在指定的时间内没有返回，结束HTTP请求，并做容错处理。当API返回结果为调用失败时，也要进行降级处理，保障系统的可用性。API调用中字符串使用utf-8编码。
API调用签名
护城河会给接入方分配appKey、appSecret(与TOP API不一样)，调用API 时需要对请求参数进行签名验证，服务器也会对该请求参数进行验证是否合法的。
每个API调用必须提供两个额外的参数：appKey和sign,分别代表护城河appKey和签名，签名的具体方法与TOP调用签名算法一致，具体如下：
根据参数名称（包括appKey）将所有请求参数按照字母先后顺序排序:key + value .... key + value,例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值链接后，得到拼装字符串bar2baz3foo1。把secret放到拼装字符串的开始和末尾，形成最后的签名字符串。
注意：参数名称区分大小写；如果参数可能包含&、#等需要做URL转译的字符，参数值的URL encode在在计算签名字符串之后。
hmac：获取拼装字符串的utf-8编码字节序列，采用md5方式加密，再把加密后的字节转化为16进制，格式是：byte2hex(md5(secretkey1value1key2value2... secret))
API返回值
所有API返回json字符串，表示接口调用成功与否，格式如下：
{
"result":"success",
"errMsg":""
}
如果调用成功，result为success，否则为fail。