# 登录模块
系统交互模型，描述了软件产品的网站类型项目中系统基础功能模块的流程、数据模型以及相应 API 输入输出标准格式，包含以下内容：
- 用户登录，包含登录形式及流程
- 认证授权方式
- 数据模型输出
目标在于各端作为 数据服务供应商 或 数据应用消费者 在交互上统一行为，面向标准接口开发，使得项目新建之初可依照 系统交互模型 快速完成系统基础功能建设，从而更从容而有序应对企业后续不断增加的项目和业务
内容目录
# 流程示意
整体登录流程
# 会话管理机制
会话管理是用户在成功登录系统后，对用户信息进行临时存储，保证用户在使用应用程序时可随时提供身份信息及相关应用数据，达到应用程序安全管理及功能状态控制的需求
在长时间未操作或长时间未使用等情况下，用户会话状态失效，系统将清除用户的相关临时存储数据，用户如需使用应用程序需要再次进行登录操作
# 身份信息数据传递
网站、管理平台以及移动原生端 APP 对于会话的应用模式，均通过在数据请的求头部增加以下内容来传递身份信息数据 access token 内容
'x-mmm-accesstoken': access-token 值
在上述内容的基础上，移动原生端会按需额外传递以下头部信息
'x-mmm-devicetype': 设备类型
'x-mmm-timestamp': 请求时间戳
'x-mmm-uuid': uuid
'x-mmm-sign': sign 签名信息
'x-mmm-appname': app 名称
'x-mmm-appproject': app 工程名称
会话的应用模式为短时间的访问令牌与长时间的刷新令牌结合的模式。在用户登录认证成功后，认证授权服务将会分发访问令牌 access token 与刷新令牌 refresh token
访问令牌 在应用闲置一定时间后失效，而在该令牌失效后数据请求模块尝试发起请求，应使用刷新令牌请求认证授权服务换取最新的访问令牌，并使用该令牌重新发起业务数据请求
刷新令牌 在超出使用时效后，需重新进行登录操作
注意
刷新令牌 refresh token 仅用于刷新/交换，禁止直接用于数据请求，应保证应用于数据请求的令牌始终为访问令牌 access token
# 令牌有效时间
在令牌时效方面，手机客户端与网站/管理平台的自动登录模式保持一致，另外会有网站/管理平台标准的短时效模式，详情设定如下表
| 类型 | access token 时效 | refresh token 时效 |
|---|---|---|
| 手机客户端 | 一个小时 | 一个月 |
| 网站/管理平台 | 一个小时 | 一个小时 |
| 网站/管理平台（自动登录） | 一个小时 | 一个月 |
无论是长时效还是短时效模式，用户在保持使用的状态下，应不断延长令牌的时效
# 会话时效模式请求参数
由于网站/管理平台有长、短两种时效模式，在执行登录请求时，需通过数据字段对会话应用的时效模式进行标识
// 请求参数
{
// 账户密码、手机短信验证码以及扫码登录模式的原请求参数内容
...
// 请求模式
// 1: 短时效模式
// 2: 长时效模式（默认）
"sessionMode": number
}
会话时效模式的默认模式（不传递 sessionMode 参数）为长时效模式，以下会应用场景示例
// 默认模式，不传递 sessionMode 参数
{
登录请求参数
}
// 显式设置为短时效模式
{
登录请求参数,
"sessionMode": 1
}
// 显式设置为长时效模式
{
登录请求参数,
"sessionMode": 2
}
# API 接口
系统功能模块 API 接口，内容仅为请求成功后返回的数据格式，完整数据交换格式请参考：数据交互格式标准
# 用户名密码登录模式
使用用户名、密码与图形验证码进行验证的身份认证模式
# 图形验证码初始化
根据返回的数据初始化图形验证码插件
接口路径：GET /auth/captcha-init
// 请求参数
无
// 响应数据
{
"code": 0,
"msg": "ok",
// 该内容格式为极验插件的标准数据格式
"data": {
"success": number,
"gt": string,
"challenge": string,
"newCaptcha": boolean
}
}
# 图形验证码相关文档
图形验证码使用的是极验图形验证码，相关的前端、App 以及服务端的相关开发文档请访问以下位置
GEETest 文档中心 (opens new window)
# 用户名密码登录
使用 用户名 和 密码 进行登录
接口路径：POST /auth/login/pwd
// 请求参数
{
"username": string, // 用户名
"password": string, // 密码，使用 SHA1 加密
// 图形验证码操作成功的识别字段，服务端需使用图形验证插件（geetest）提供的验证模块
// 对相应数据进行验证，用以确定该次请求为用户手动操作的正确行为
"captchaChallenge": string,
"captchaValidate": string,
"captchaSeccode": string,
// 会话模式，非必要参数
"sessionMode": number
}
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
"access": {
"accessToken": string,
"refreshToken": string,
"expiresIn": number
}
}
}
sessionMode 请求参数为指定用户登录会话模式，详细内容请参考 会话时效模式请求参数
# 手机短信验证码登录模式
使用手机号码与通过手机短信获取的验证码进行身份认证的模式
# 获取手机短信验证码
使用 手机号 获得验证码用于系统登录，成功访问接口后，相应手机号的手机将收到包含验证码的短信
接口路径：POST /auth/sms-code
// 请求参数
{
"phone": string // 手机号
}
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
}
}
# 手机短信验证码登录
使用 手机号 和 验证码 进行登录
接口路径：POST /auth/login/sms
// 请求参数
{
"phone": string, // 手机号
"code": string // 短信验证码,
// 会话模式，非必要参数
"sessionMode": number
}
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
"access": {
"accessToken": string,
"refreshToken": string,
"expiresIn": number
}
}
}
sessionMode 请求参数为指定用户登录会话模式，详细内容请参考 会话时效模式请求参数
# 手机客户端扫描二维码授权模式
通过网站 / 管理平台显示二维码并使用手机客户端扫描的身份认证模式，基础功能包含以下内容
- 网站/管理平台生成并显示二维码，该二维码有效时间为
5 分钟 - 二维码需配套刷新功能（重新获取数据，并重新生成二维码）
- 扫描二维码功能通过识别码
key来保证网站、手机客户端与应用服务等多个环节流转的事务一致性 - 手机客户端应在完成身份认证后才有入口进行扫描授权登录操作
- 手机客户端确认授权后，应用服务将手机客户端中通过令牌传递的用户身份、组织等相关信息应用于网站 / 管理平台登录
流程示意图
# 网站/管理平台初始化二维码
获得二维码登录模块实际访问路径，用于将位置生成二维码提供手机客户端扫描
二维码时效
二维码在获取并生成后，有效时间为 5 分钟，在超出时效后，手机客户端扫描二维码，身份认证服务应提示
二维码已失效，请重新获取并再次扫码登录
用户需在网站/管理平台的二维码界面中操作更新二维码，并再次使用手机客户端扫码进行登录操作
接口路径：GET /auth/qrcode-init
// 请求参数
无
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
"result": string
}
}
数据接口返回的 result 内容是通过 AES 模式加密后的字符串，程序直接使用该内容进行生成二维码
生成二维码后，需要通过密钥解密后获得如下内容
https://api.fjmaimaimai.com/app/auth/login/qrcode?key=abcd123
并从该内容中解析出 key 参数所对应的值，该字段内容作为保证两端一致性的识别码，手机客户端在授权登录时，需要使用该编码发送至授权认证服务的相关登录接口
# 轮询检查二维码是否完成登录
在完成 网站/管理平台初始化二维码 接口请求并将内容展示为二维码后，登录界面立即开始 每 3 秒 一次的轮询检查事务，当检查到用户已使用手机客户端扫描二维码并完成登录后，接口返回相关令牌数据
接口路径：POST /auth/login/qrcode
// 请求参数
{
// 通过 SHA1 加密后传递
"key": string,
// 会话模式，非必要参数
"sessionMode": number
}
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
// 当前二维码授权状态
// 1：未授权
// 2：已授权
"result": number,
// 授权完成后生成的相关令牌
// 未授权时（"result": 1）不生成该节点
"access": {
"accessToken": string,
"refreshToken": string,
"expiresIn": number
}
}
}
请求参数中的 key 字段是 网站/管理平台初始化二维码 接口中响应的数据字段，并使用 SHA1 进行加密
sessionMode 请求参数为指定用户登录会话模式，详细内容请参考 会话时效模式请求参数
# 手机客户端扫描二维码登录
手机客户端登录状态下，扫描网站/管理平台的二维码，获得二维码中内容，并通过 AES 模式与密钥进行解密后得到登录位置以及识别码内容 url，示例如下
https://api.fjmaimaimai.com/app/auth/login/qrcode?key=abcd123
获得链接后，需要解析成两个部分
- 登录授权接口目标 url 位置：
https://api.fjmaimaimai.com/app/auth/login/qrcode - 单次事务识别码（key）：
'abcd123'
其中，url 为数据接口请求的目标位置，key 作为请求参数中对应字段的数据
若二维码内容解密失败或是链接内容解析格式不正确，均可认定为非法二维码，则手机客户端提示
您扫描的二维码无效，请确认后重新扫描
解密成功且提取识别码成功的情况下，应用界面跳转至 确认授权 界面，用户在点击确认授权的按钮后，发起相关数据请求（POST）
// 请求参数
{
// 通过 SHA1 加密后传递
"key": string
}
// 响应数据
// 手机客户端在确认授权登录后，无后续操作，返回空数据体即可
{
"code": 0,
"msg": "ok",
"data": {}
}
// 验证失败
{
// code 码仅为样例，请以实际情况输出编码为准
"code": 962,
"msg": "用户组织不存在",
"data": {}
}
请求参数中的 key 字段是 网站/管理平台初始化二维码 模块生成的二维码解析后的携带参数，并使用 SHA1 进行加密
# 刷新/交换 token
根据 会话管理机制 定义的模式，在访问令牌 access token 失效后，需要使用刷新令牌 refresh token 来更新访问令牌，并在更新后使用该令牌替换已失效的令牌进行请求业务数据
接口路径：POST /auth/refresh-token
// 请求参数
{
"refreshToken": string
}
// 响应数据
{
"code": 0,
"msg": "ok",
"data": {
"access": {
"accessToken": string,
"refreshToken": string,
"expiresIn": number
}
}
}
# 验证会话是否有效
在 会话管理机制 - 令牌有效时间 中描述的 网站/管理平台 自动登录模式（长时效模式），在用户登录成功后，部分用户信息及身份令牌将存储于本地环境，并在下次访问时，进行携带访问。为防止用户在授权使用期间的身份、状态以及角色等变更，应在用户进入系统前对该用户的身份令牌、时效以及授权相关信息进行确认用户是否可以继续以当前状态使用
接口路径：POST /auth/verify-access
// 请求参数
{
"refreshToken": string
}
// 响应数据
// 验证身份有效
{
"code": 0,
"msg": "ok",
"data": {}
}
// 验证身份无效
{
"code": 4567,
"msg": "身份认证失败，您当前角色未被授权访问系统",
"data": {}
}
# 不使用 authCode 交换 token
用户使用账户密码、手机短信验证码或手机客户端扫码任意一种模式完成身份认证后，不再生成 authCode 来交换用户身份令牌，而是直接分发用户身份令牌 token
← API 交互规范