# 动态口令
jAccount提供动态口令机制对登录用户进行二次认证,业务系统可通过动态口令来保护系统中的特定功能,在这些功能被使用前通过jAccount对是否用户本人操作进行再次确认。
# 基本概念
- jAccount动态口令是基于时间的一次性密码(TOTP),用户可以使用交我办app(安卓3.2.9版本、苹果3.2.6版本或以上)开通自己jAccount账号的动态口令。
- 动态口令为6位数字,每30秒由交我办app离线计算产生,不支持多设备共享,如果用户先后在多个手机上开通动态口令,仅最后开通的手机可以提供有效的动态口令。
# 业务系统接入
业务系统使用动态口令对特定功能进行保护的基本流程为:
执行特定功能前,业务系统需要在其前端获取用户的动态口令,并将动态口令和其余业务参数一起传递给其后端。
业务系统后端通过jAccount提供的动态口令验证接口验证口令的合法性,仅在口令合法时才执行特定功能并返回结果数据。
参考下图:
为了实现以上过程,业务系统需要关注以下两点:
- 从用户处获取动态口令
jAccount提供了前端开发包来标准化动态口令的获取界面,并简化用户提供动态口令的操作。使用方式参考如下代码:
<script src="https://jaccount.sjtu.edu.cn/jaccount/totp/index.js?t=20220524"></script>
<script>
const account = 'userAccount'; //当前用户账号
function doQuery() {
getTotp(account, callback)
}
function callback(totp) {
//...
// 获取到口令,执行自身业务功能
//...
}
}
</script>
2
3
4
5
6
7
8
9
10
11
12
13
14
15
以上代码分为两步:
1、引用jAccount的前端开发包 https://jaccount.sjtu.edu.cn/jaccount/totp/index.js
2、在需要获取动态口令时,调用getTotp方法,该方法需要提供两个参数:
参数 | 类型 | 描述 |
---|---|---|
account | string | 要获取动态口令的账号(jAccount),应该为当前登录用户的账号 |
callback | function | 接收动态口令的回调方法,jAccount的前端开发包会在获取到动态口令后回调该方法 |
注:为了实现更好的用户体验,jAccount的前端开发包会对获取到的动态口令进行校验,仅校验通过时才会触发回调。
即便如此,业务系统仍应该将获取到的动态口令传回其后端系统,由后端系统通过jAccount提供的校验接口进行验证。
业务系统应该仅信任后端校验结果,仅在后端校验通过后才允许被保护的功能执行。
调用getTotp方法后,会出现如下界面,用户可以使用交我办App扫码获取动态口令或者直接输入动态口令。
- 校验动态口令的合法性
jAccount提供了后端校验接口用于校验动态口令是否有效。
接口地址:https://jaccount.sjtu.edu.cn/oauth2/introspect
调用方法:POST
调用参数编码:application/x-www-form-urlencoded
调用参数:
参数 | 类型 | 描述 |
---|---|---|
token | string | 要验证的动态令牌 |
token_type_hint | string | 固定为 'otp' |
access_token | string | 具有 basic、essential、profile、privacy 中任意scope的用户授权访问令牌,一般等价于登录对接时获取的用户访问令牌 |
响应结果:application/json
{
"token_type": "OTP", //固定值,表示验证的是动态口令
"sub": {string}, //动态口令所属用户,总是等于访问令牌所属的用户
"active": {boolean}, //动态口令是否有效
"blocked": {boolean} //动态口令验证是否由于过于频繁而被拒绝
}
2
3
4
5
6
为了保护用户的动态口令不被暴力破解,验证接口对单个账号2分钟内连续10次动态口令验证未通过的,停止验证2分钟。 在停止期间内,接口返回结果中blocked为true,active为false。