# 动态口令

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>

1
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}  //动态口令验证是否由于过于频繁而被拒绝
}

1
2
3
4
5
6

为了保护用户的动态口令不被暴力破解，验证接口对单个账号2分钟内连续10次动态口令验证未通过的，停止验证2分钟。在停止期间内，接口返回结果中blocked为true，active为false。

← jAccount认证接入方法