一、应用场景
物联云平台提供统一认证服务,用于集中式的身份管理。企业可以通过物联云平台进行一站式的登录认证。通过登录认证的用户即可直接访问第三方应用,而无需再次输入账号密码。
第三方应用需要将物联云平台作为身份认证的服务端,以物联云平台账号信息作为第三方应用登录时候的账号、密码。企业成员输入账号、密码后,由第三方应用的页面发起请求。物联云平台验证通过后,企业成员即可访问平台和各个应用。
企业通过物联云平台作为统一身份,建立各平台间的身份联系。
企业内部应用使用物联云平台进行身份认证。
二、功能说明
物联云平台支持作为单点登录的服务端进行统一的身份认证。在使用物联云平台单点登录服务前,需要先获取物联云平台的AccessToken作为调用凭证、clien_id作为应用系统标识。
调用凭证(AccessToken):需要前往物联云平台管理台【系统设置->平台访问授权】中,创建一个授权。记录已创建授权的AccessKeyId和AccessKeySecret,用于获取AccessToken。
应用系统标识(client_id):需要前往物联云平台管理台【应用中心->应用网关】中,创建一个应用类型的应用,并开启单点登录。
企业成员通过第三方企业应用进行登录时,需要完成三步处理:获取临时授权码(Code)、获取单点登录调用凭证(SsoToken)、注册客户端。
获取临时授权码:企业应用提供登录页需要向应用服务端验证登录状态。在未登录状态下,由企业应用服务端通过物联云平台统一认证地址进行登录验证。物联云平台登录成功后则返回临时授权码(Code)。
获取单点登录调用凭证:应用服务端通过临时授权码(Code)、应用系统标识(client_id)、签名(Signature)换取单点登录调用凭证(SsoToken)。
注册客户端:通过单点登录调用凭证(SsoToken)、应用系统标识(client_id)进行注册客户端。
三、前提条件
1.第三方应用需要将物联云平台作为身份验证的服务端。
2.需要已创建的对应的AccessToken。
3.已创建应用类型的应用,并开启单点登录。
4.第三方应用开发登录页与物联云平台单点服务进行对接。
5.第三方登录页需要以物联云平台身份信息作为登录的账号、密码。
6.需要在物联云平台完成企业成员的创建。
四、关键流程
4.1 客户端对接示例流程
4.1.1 场景说明
以从物联网中台管理台跳转至外部系统管理台为例子,跳转之前物联网中台管理台需要知道外部系统管理台的地址。
4.1.2 场景前提
需要在物联网中台管理台的应用中心处创建应用用以代指 外部系统,并按照需要配置 外部系统管理台着陆页以及外部系统管理台注销回调页。
4.1.3 场景接口
外部系统需要实现以下功能接口:
- 单点登录客户端页面获取认证地址,让 外部系统管理台着陆页 得到 物联网中台认证页 的地址,此接口无固定要求,可缺省。
- 客户端注销单点登录,让 外部系统管理台 使用 外部系统 调用凭证进行单点登录客户端注销,此接口无固定要求,可缺省。
- 注销登录回调,此接口不可缺省,目的是让 物联网中台 通知 外部系统 在物联网中台已注销,格式见 5.2.1。
- 注销登录回调地址校验,此接口不可缺省,目的是 让 物联网中台 校验 外部系统 的有效性,格式见 5.2.2。
4.1.4 流程说明
- 第一,在 物联网中台管理台 点击 外部系统管理台 期望进入外部系统管理台进行工作,点击后进入外部系统管理台着陆页,此页面需要实现后续功能。
- 第二,外部系统管理台着陆页 通过检测浏览器持有变量以确定访问者是否在 外部系统管理台 登录,如已在 外部系统管理台 登录,则可直接使用 外部系统管理台 而不用执行以下操作。
- 第三,外部系统管理台着陆页 检测到访问者未登录至 外部系统管理台,则向 外部系统服务端 发起请求用于获取外部系统在物联网中台的客户端标识clientId以及 物联网中台管理台认证页面,为固定html页面。
- 第四,外部系统管理台着陆页 向 物联网中台管理台认证页面 进行跳转,需要带上客户端标识clientId以及 回调地址callbackUrl,从而进入 物联网中台管理台认证页面。
- 第五, 物联网中台管理台认证页面 通过检测浏览器持有变量以确定访问者是否在 物联网中台管理台 登录,此时分两种情况:
- 未在 物联网中台管理台 登录跳转至 物联网中台管理台登录页,由访问者物联网中台的账号密码进行登录,从而得到物联网中台成员级调用凭证。
- 已在 物联网中台管理台 登录则可以直接得到物联网中台成员级调用凭证。
- 第六, 物联网中台管理台认证页面 在获取到 物联网中台成员级调用凭证 后向 物联网中台 发起获取单点登录临时授权码 请求以得到 临时授权码code 。
- 第七, 物联网中台管理台认证页面 将 临时授权码code和客户端标识clientId作为参数向外部系统回调地址callbackUrl 进行请求,此时进入 外部系统服务端 。
- 第八, 外部系统服务端 接收到 临时授权码code后,配合物联网中台的客户端标识clientId和客户端秘钥clientSecret向物联网中台发起 临时授权码换取单点登录调用凭证 请求,从而得到 单点登录调用凭证 。
- 第九, 外部系统服务端 得到 单点登录调用凭证 ,需要调用 依据单点登录调用凭证注册客户端,此操作目的在于访问者在物联网中台注销后由物联网中台通知 外部系统服务端 注销局部会话。
- 第十, 外部系统服务端 建立外部系统自身的会话信息,重定向至 外部系统管理台 导航页,进行正常功能访问。
- 第十一, 外部系统管理台 如需要得到访问者在 物联网中台 的基础信息则可发起 单点登录凭证换取基本信息 请求。
- 第十二, 外部系统管理台 如需要注销单点登录则可发起 单点登录调用凭证注销登录 ,从而使得 物联网中台 不在维护此客户端的单点登录信息。
- 第十三,访问者在 物联网中台管理台 注销登录,则物联网中台需要遍历此访问者注册上来的所有客户端,并找出客户端对应的 注销回调地址 进行注销通知,外部系统服务端 在接收到注销回调后销毁外部系统的会话标识,至此整个流程结束。
五、API列表
5.1 单点登录
5.1.1 获取单点登录临时授权码
接口描述
前提:第三方应用需要将物联平台当做账号的服务端,以物联平台账号作为登录第三方应用的账号密码;账号已在物联平台登录获得了物联平台的调用凭证,由单点登录服务自己页面发起请求
场景:访问第三方应用发现未登录跳转至物联平台统一页面,此时必须带有参数客户端标识clientId和回调地址redirectUrl
后续:单点登录服务页面在获取到code之后, 应该将code以参数形式添加在redirectUrl, 然后以get方式回调到客户端服务器
请求方式
POST
请求地址
/v3/service/sso/member/code
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 企业成员 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
client_id | body | true | String | SSO应用系统标识 |
请求示例:
{
"client_id":"456saffewf324235dsfsf"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
data.code | true | String | 临时授权码 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"code": "4564dsfe1dsfsdf65446"
}
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
40435001 | 客户端不存在/未启用 |
40035002 | 客户端不是业务系统 |
40035003 | 客户端未启用sso |
5.1.2 临时授权码换取单点登录调用凭证
接口描述
单点登录客户端根据临时授权码, 客户端标识, 签名换取单点登录的调用凭证
请求方式
POST
请求地址
/v3/service/sso/member/token
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Signature | true | String | 请求签名,签名方法为sha1(body + clientId + clientSecret) |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
code | body | true | String | 临时授权码 |
grant_type | body | true | String | 授权类型, 目前只支持authorization_code |
timestamp | body | true | String | 时间戳, 如果和服务器相差5分钟, 则认为非法 |
client_id | body | true | String | SSO应用系统标识 |
请求示例:
{
"client_id":"456saffewf324235dsfsf",
"code":"4564dsfe1dsfsdf65446",
"grant_type":"authorization_code",
"timestamp":"1635131391000"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
data.sso_token | true | String | 单点登录调用凭证 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"sso_token": "45695661fdsfewdf2323"
}
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
40435001 | 客户端不存在/未启用 |
40035002 | 客户端不是业务系统 |
40035003 | 客户端未启用sso |
40035006 | 时间戳不合法 |
40035007 | 授权类型不合法 |
40435002 | 临时授权码不存在 |
40035004 | 客户端标识不相等 |
40335001 | 签名不正确 |
5.1.3 依据单点登录调用凭证注册客户端
接口描述
单点登录客户端根据单点登录调用凭证注册客户端系统
请求方式
POST
请求地址
/v3/service/sso/member/register
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Sso-Token | true | String | 单点登录调用凭证 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
client_id | body | true | String | SSO应用系统标识 |
请求示例:
{
"client_id":"456saffewf324235dsfsf"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {}
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
40435001 | 客户端不存在/未启用 |
40035002 | 客户端不是业务系统 |
40035003 | 客户端未启用sso |
40335002 | 调用凭证已过期 |
40335003 | 调用凭证被刷新 |
5.1.4 成员注销登录
接口描述
企业成员调用凭证注销登录,销毁调用凭证以及刷新凭证,并以消息队列将注销登录事件发送通知给SSO服务进而通知给各个单点登录客户端,该接口由Api-Service和Corp-Service提供
请求方式
PUT
请求地址
/v2/corp/member-logout
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Access-Token | true | String | 调用凭证 企业成员 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
无 | 无 | 无 | 无 | 无 |
请求示例:
{
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": null
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
5.1.5 单点登录调用凭证注销登录
接口描述
单点登录客户端使用单点调用凭证注销单点登录,主要来源与客户端发起,发起该请求之后会根据单点登录调用凭证的MemberId和Resource找出所有注册的客户端,异步通知各个客户端注销局部会话.
请求方式
PUT
请求地址
/v3/service/sso/member/client-logout
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Sso-Token | true | String | 单点登录调用凭证 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
无 | 无 | 无 | 无 | 无 |
请求示例:
{
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": null
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
40335002 | 调用凭证已过期 |
40335003 | 调用凭证被刷新 |
5.1.6 单点登录调用凭证换取基本信息
接口描述
单点登录客户端使用单点调用凭证单点调用凭证获取成员基本信息.
请求方式
GET
请求地址
/v3/service/sso/member/infos
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Sso-Token | true | String | 单点登录调用凭证 |
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
无 | 无 | 无 | 无 | 无 |
请求示例:
{
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
data.id | true | String | 成员标识 |
data.name | true | String | 成员名称 |
data.email | false | String | 成员邮箱 |
data.phone | false | String | 成员手机号 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {
"id":"123sdfwe123sdfe",
"name":"李清华",
"email":"liqinghua@xlink.cn",
"phone":"13838383388"
}
}
错误码:
错误码 | 描述 |
---|---|
40010001 | 请求数据字段验证不通过 |
4001002 | 请求数据必须字段不可为空 |
4031001 | 调用凭证权限被禁止访问 |
4031003 | 无效的调用凭证 |
4031002 | 需要调用凭证 |
4041001 | 接口不存在 |
5031001 | 系统错误 |
40335002 | 调用凭证已过期 |
40335003 | 调用凭证被刷新 |
5.2 外部系统实现接口标准
5.2.1 注销登录回调
接口描述
成员在物联网中台管理台或者某个客户端向物联网中台发起注销客户端时,物联网中台会找出该成员下所有注册的客户端,向对应客户端注销回调地址发起请求,进行注销登录通知。
客户端注销回调地址需要符合以下规范,且由外部系统实现,其中请求地址可自定义,调用成功判断标准为HTTP响应状态码为200。
请求方式
POST
请求地址
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
client_id | body | true | String | SSO应用系统标识 |
sso_token | body | true | String | SSO调用凭证 |
请求示例:
{
"sso_token": "单点登录调用凭证",
"client_id": "客户端标识, 即是应用标识"
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
status | true | Int | HTTP状态码 |
code | true | Int | 业务错误码 |
msg | false | String | 业务错误信息 |
data | true | Object | 业务数据 |
返回示例:
{
"status": 200,
"code": 200,
"msg": "访问成功",
"data": {}
}
错误码:
错误码 | 描述 |
---|---|
—- | —- |
5.2.2 注销登录回调地址校验
接口描述
成员在物联网中台管理台应用中心处创建单点登录的应用时,需要填写单点登录的客户端注销回调接口地址,物联网中台会校验该客户端注销回调接口的有效性。
注销登录回调地址校验需要符合以下规范,且由外部系统实现,其中请求地址可自定义,调用成功判断标准为HTTP响应状态码为200且响应值echo_string需要与请求参数echo_string一致。
请求方式
GET
请求地址
请求头
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
Content-Type | true | String | application/json |
请求参数
名称 | 位置 | 必填 | 类型 | 备注 |
---|---|---|---|---|
signature | Query | true | String | 加密签名,签名方法 1.将timestamp、nonce、app_id、app_secret四个参数进行字典序排序 2. 将四个参数字符串拼接成一个字符串进行sha1加密, 得到 signature |
timestamp | Query | true | String | 时间戳 |
nonce | Query | true | String | 随机数 |
echo_string | Query | true | String | 随机字符串 |
app_id | Query | true | String | 应用标识, 用于找出对应的app_secret |
请求示例:
{
}
返回参数说明
名称 | 必填 | 类型 | 备注 |
---|---|---|---|
echo_string | true | String | 随机字符串 |
返回示例:
{
"echo_string":"随机字符串"
}
错误码:
错误码 | 描述 |
---|---|
—- | —- |