# 外部系统自主调用SSO模式登录七巧应用平台协议
# 单点登录过程
整个单点登录过程如下,重点在于客户端单点免密登录接口的设计。
# 免密登录接口参数
该免密登录接口详细参数见接口协议,请求参数主要包含以下三种类型的参数:
- 登录参数(LP)
identity
:用户标识;identityType
:用户标识类型 WX_USER_ID(企业微信账号) , USER_ID(道一用户账号) ;corpId
:道一机构 id;- 随机盐(SP)
- 加密结果(AR)
# 协议加密过程(请联系技术支持人员了解详情)
# 登录验证过程
单点登录加密验证过程如下: 外部系统
- 客户端通过企业微信获取
LP
参数; - 客户端通过
LP
、SP
参计算AR
; - 客户端拼接参数,重定向到七巧的应用平台,参数为
LP
、SP
、AR
;
七巧平台
- 计算验证
AR
: A . 七巧服务端通过LP
、SP
计算ER
; B. 七巧服务端对比ER
、AR
: 结果不一致,返回校验失败响应; 结果一致,继续验证过程; - 回调验证 A. 向请求参数 callbackUrl 指向的外部服务器发起访问,携带登录信息; B. 获取外部服务器验证成功结果继续,失败结果返回相应的失败响应;
- 执行系统内部登录(session写入),响应跳转到客户端请求参数的
redirectUrl
;
# 接口协议
# 七巧单点免密登录跳转路径
重定向路径 : {七巧应用平台域名地址}/#/sso
示例URL(生产环境)
https://qy.do1.com.cn/qiqiao2/runtime/#/sso?type=outside&corpId=ww4852f35d45307a6f&identity=liuyan&identityType=WX_USER_ID&seed=768917×tamp=1634721733382&authCode=1dd6c632ff41599ba0edf5a9fc8c52d0
参数 | 类型 | 是否必须 | 含义 | 示例 |
---|---|---|---|---|
type | string | 是 | 外部登录类型(固定参数) | outside |
identity | string | 是 | 用户标识(企业微信账号,道一用户账号) | liuyan |
identityType | string | 是 | 标识类型:企业微信账号(WX_USER_ID),道一用户账号(USER_ID) | WX_USER_ID |
corpId | string | 是 | 道一机构 corpId | ww4852f35d45307a6f |
redirectUrl | string | 否 | 客户端调转 URL(默认首页,需要进行一次url编码) | https%3A%2F%2Fqy.do1.com.cn%2Fqiqiao2%2Fruntime%2F%23%2Findex%2Fapplication%2FapplicationList |
timestamp | long | 是 | 当前时间戳,长度 13 位 | 1634721733382 |
seed | int | 是 | 随机 Int 类型正整数,长度为 6 位 | 768917 |
authCode | string | 是 | 加密结果,长度 32 位 | 1dd6c632ff41599ba0edf5a9fc8c52d0 |
callbackUrl | string | 否 | 二次验证回调地址,可选(需要进行一次url编码) | https%3A%2F%2Fwww.sample.com%2Fcallback |
※ 当 callbackUrl 值不为空,在请求该登录接口时,会向该参数指向的地址进行登录验证回调,目的在于进一步提高登录的安全性,也可以选择不实现。
※ 参数中的redirectUrl、callbackUrl都需要进行一次url编码,可以使用在线编码网站进行编码(https://www.bejson.com/enc/urlencode/)
响应参数:
- 登录成功:直接跳转到
redirectUrl
指向的页面; - 登录失败:错误返回
json
响应报文如下格式;
{
"code": "6000002",
"desc": "租户未开启普通外部登录模式",
"data": {}
}
错误响应对照表如下:
code | desc |
---|---|
6000002 | 租户未开启普通外部登录模式 |
6000003 | 接口返回内容解析错误 |
6000004 | 解析用户标识失败 |
6000005 | 加密校验不通过 |
6000006 | callbackUrl不在机构IP白名单范围内 |
6000007 | 用户唯一标识获取用户失败 |
6000008 | 登录回调验证失败 |
# 道一登录验证回调
接口路由 :由道一单点免密登录接口 callbackUrl
参数指定
请求方法: GET
请求参数:
参数 | 类型 | 是否必有 | 含义 | 示例 |
---|---|---|---|---|
identity | string | 是 | 用户标识(企业微信账号,道一用户账号) | liuyan |
identityType | string | 是 | 标识类型:企业微信账号(WX_USER_ID),道一用户账号(USER_ID) | WX_USER_ID |
corpId | string | 是 | 道一机构 corpId | ww4852f35d45307a6f |
timestamp | long | 是 | 当前时间戳,长度 13 位 | 1634721733382 |
seed | int | 是 | 随机 Int 类型正整数,长度为 6 位 | 768917 |
authCode | string | 是 | 加密结果,长度 32 位 | 1dd6c632ff41599ba0edf5a9fc8c52d0 |
※ 此处请求参数是客户端传入的参数,外部系统在响应该请求,可以自行验证登录信息的安全。 客户端返回参数:
{
"data": {
//true则回调成功
"result":true
}
}
# 外部系统基于OAuth2.0的SSO模式登录七巧应用平台
# 单点登录过程
整个单点登录过程如下,基于OAuth2.0模式
# 配置步骤
# 1.开启基于OAuth2.0的SSO模式
管理平台-> 基础设置 -> SSO单点登录集成 -> 基于OAuth2.0的SSO模式 -> 开启
# 2.Step1:统一认证接口配置
- 接口地址:外部系统统一认证的获取授权码请求地址
- 参数设置:外部系统所需的其他参数
- 重定向地址参数:外部系统接收重定向地址的key,内部系统通过此参数传递跳转地址给外部
- 返回路由参数内容解析:外部系统登录重定向回来七巧平台之后,路径上带的授权码的key,前端通过此参数获取对应的授权码值进行登录。
# 3.Step2:Token获取接口配置
- 接口地址:授权码获取token地址
- 请求类型:支持
GET
、POST
、PUT
请求方式 - 请求内容编码:支持
application/json
、application/x-www-form-urlencoded; charset=UTF-8
- 参数设置:外部系统请求所需的其他参数
- 授权码请求参数:外部系统接收授权码的key,内部系统通过此参数传递授权码给外部
- 返回路由参数内容解析:对返回的结果进行解析,为Step3获取用户信息接口准备参数,内容解析方式为JSONPath读取,配置值为JSONPath的表达式。JSONPath的使用可以参考官方文档:https://goessner.net/articles/JsonPath/
# 4.Step4:获取用户信息接口配置
- 接口地址:token获取用户信息地址
- 请求类型:支持
GET
、POST
、PUT
请求方式 - 请求内容编码:支持
application/json
、application/x-www-form-urlencoded; charset=UTF-8
- 参数设置:外部系统请求所需的其他参数
- Token请求参数:外部系统接收Token的key,内部系统通过此参数传递Token给外部
- 返回路由参数内容解析:对返回的结果进行解析,获取用户的唯一标识,解析方式为JSONPath读取,配置值为JSONPath的表达式。JSONPath的使用可以参考官方文档:https://goessner.net/articles/JsonPath/
- 人员唯一标识映射配置:配置外部系统返回的用户标识的类型,key要跟返回内容解析中人员唯一标识的key一致,值有三种类型,分别是企业微信人员账号(wxuserid)、本平台人员账号(userid)、用户电话号码(后续更新支持)
# 应用平台跳转路径
重定向路径 : {七巧应用平台域名地址}/#/sso
示例URL(生产环境)
https://qy.do1.com.cn/qiqiao2/runtime/#/sso?type=oauth2&corpId=ww4852f35d45307a6f&redirectUrl=
参数 | 类型 | 是否必须 | 含义 | 示例 |
---|---|---|---|---|
type | string | 是 | 外部登录类型(固定参数) | oauth2 |
corpId | string | 是 | 道一机构 corpId | ww4852f35d45307a6f |
redirectUrl | string | 否 | 客户端调转 URL(默认首页,需要进行一次url编码) | https%3A%2F%2Fqy.do1.com.cn%2Fqiqiao2%2Fruntime%2F%23%2Findex%2Fapplication%2FapplicationList |
# 外部系统基于AAD域的SSO模式登录七巧应用平台
# 单点登录过程
整个单点登录过程如下,基于微软AAD域账号体系模式;
# 配置步骤
# 1、获取AAD门户信息
1)使用微软账户,登录https://portal.azure.com/#home (opens new window);
2)注册应用,路径进入门户主页-默认目录-注册应用程序,填写应用信息;
3)注册应用成功后、查看当前应用信息,获取CLIENT_ID(客户端ID)、CLIENT_SECRET(值)、Azure AD 租户(租户ID)
注意事项
- 应用程序CLIENT_SECRET(值) 仅在注册成功后,首次查看时,能够查看到完整的值,后续将以加密形式存在,需提前保存;
# 2、配置信息
1)进入系统管理-基础设置,将第一步获取到的信息,Azure AD租户 、CLIENT_ID(客户端ID)、CLIENT_SECRET(值)将信息配置完善;
2)配置身份验证重定向地址,进入AAD门户-应用详情-选择重定向URL,填写以下地址: https://authpre.do1.com.cn/uniauth/aad/callback (opens new window)
3)配置AAD信息成功后,可将按照应用平台跳转路径AAD域认证模式地址,生成重定向路径地址,将地址配置在用户内部第三方系统中,可通过用户内部第三方系统中单点至道一云plus;
注意事项:
- 需当前单点登录的用户,在通讯录中邮箱字段配置为微软邮箱账号;
# 应用平台跳转路径
重定向路径: {七巧应用平台域名地址}/#/sso
示例URL(生产环境)
https://qy.do1.com.cn/qiqiao2/runtime/#/sso?type=oauth2&corpId=ww4852f35d45307a6f&redirectUrl=
参数 | 类型 | 是否必须 | 含义 | 示例 |
---|---|---|---|---|
type | string | 是 | 外部登录类型(固定参数)oauth2认证、AAD域认证 | oauth2、aad |
corpId | string | 是 | 道一机构 corpId | ww4852f35d45307a6f |
redirectUrl | string | 否 | 客户端调转 URL(默认首页,需要进行一次url编码) | https%3A%2F%2Fqy.do1.com.cn%2Fqiqiao2%2Fruntime%2F%23%2Findex%2Fapplication%2FapplicationList |