外部系统自主调用SSO模式登录七巧应用平台协议

单点登录过程

整个单点登录过程如下，重点在于客户端单点免密登录接口的设计。

免密登录接口参数

该免密登录接口详细参数见接口协议，请求参数主要包含以下三种类型的参数：

• 登录参数（LP）
• identity ：用户标识；
• identityType ：用户标识类型 WX_USER_ID(企业微信账号) , USER_ID(道一用户账号) ；
• corpId ：道一机构 id；
• 随机盐（SP）
• 加密结果（AR）

协议加密过程（请联系技术支持人员了解详情）

登录验证过程

单点登录加密验证过程如下： 外部系统

1. 客户端通过企业微信获取 LP 参数；
2. 客户端通过 LP 、 SP 参计算 AR ；
3. 客户端拼接参数，重定向到七巧的应用平台，参数为 LP 、 SP 、 AR ；

七巧平台

1. 计算验证 AR ： A . 七巧服务端通过 LP 、 SP 计算 ER ； B. 七巧服务端对比 ER 、 AR ： 结果不一致，返回校验失败响应； 结果一致，继续验证过程；
2. 回调验证 A. 向请求参数 callbackUrl 指向的外部服务器发起访问，携带登录信息； B. 获取外部服务器验证成功结果继续，失败结果返回相应的失败响应；
3. 执行系统内部登录（session写入），响应跳转到客户端请求参数的 redirectUrl ；

接口协议

七巧单点免密登录跳转路径

重定向路径 ： {七巧应用平台域名地址}/#/sso

示例URL（生产环境）

https://qy.do1.com.cn/qiqiao2/runtime/#/sso?type=outside&corpId=ww4852f35d45307a6f&identity=liuyan&identityType=WX_USER_ID&seed=768917&timestamp=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/）

响应参数：

1. 登录成功：直接跳转到 redirectUrl 指向的页面；
2. 登录失败：错误返回 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