vika维格云-单点登录与账号同步接口规范文档

1 、简要概述

该文档将阐述通过维格云OAuth认证协议，接入自身的IAS（身份认证系统），根据IAS系统定义的标准JSON数据格式接口规范与IAS系统做数据交互。该文档定义了机构、账号、权限、组等对象增、删、查、改的抽象方法，下游应用系统根据集成范围做对应的业务实现。

下文将以账号和组织机构对象做示例讲解，其它对象处理方式与账号一致，不再赘述。

2 、术语与缩写解释

同步接口资源清单

3 、通过OAuth认证协议实现单点登录

3.1 OAuth介绍

OAuth是一个关于授权的开放的网络协议，在第三方应用与服务提供商之间设置一个授权层。第三方应用不能直接登录服务提供商，只能登录授权层，以此将用户与客户端区分开来。第三方应用登录授权层所用的令牌，与用户的密码不同。用户可以在登录授权的时候，指定授权层令牌的权限范围和有效期。第三方应用登录授权层以后，服务提供商根据令牌的权限范围和有效期，向第三方应用开放用户资源。

3.2 OAuth认证流程

流程介绍：上图主要是第三方子系统和认证中心集成过程，第一步获取AuthonrizeCode对应接口规范里面的授权接口，显示登陆页面，用户输入用户名、密码，验证完身份之后，生成AuthonrizeCode，子系统根据AuthonrizeCode获取AccessToken对应接口规范里面的获取Token，子系统根据返回的AccessToken可以获取认证的用户信息对应接口规范里面的获取认证用户。

3.3 OAuth集成流程

集成分工

IAS平台

l 提供应用系统基本信息；

l 开发Oauth 认证接口 (见3.4.1，3.4.2，3.4.3，3.4.4)

l 联调测试

应用系统

l 提供应用系统基本信息；

l 提供单点登录接口 (3.4.5 和 3.4.6)；

l 联调测试

3.4 OAuth接口规范

以下OAuth接口地址的{host}和{port}替换成下命的域名和端口

IAS示例地址（以自身单点登录系统为准，仅供参考）：https://bim.example.com/idp

维格专有云示例地址（以实际专有云地址为准）：https://vk.example.com

3.4.1 授权接口

接口说明：应用系统调用认证接口获取code（不能用postman测，可以在浏览器测）

3.4.2 获取Token

3.4.3 刷新Token（可选）

​​

3.4.4 获取认证用户

​​

3.4.5 维格单点登录入口地址

​​

3.4.6 维格单点登录回调地址

​

​​

4 、账号与组织机构数据同步集成规范

集成分工

IAS平台

• 注册应用、提供应用注册后的信息；

• 开发对接人员组织管理接口；

• 联调测试。

应用系统

• 提供应用系统基本信息；

• 提供人员组织管理接口，见数据供应接口；

• 联调测试。

IAS平台与下游集成应用系统，数据交互分为”推送”

​

4.1 数据供应

IAS平台请求下游集成应用系统的API接口服务，请求调用接口定义的接口方法。

下游集成应用在UserCreateService、UserUpdateService、UserDeleteService方法体内实现对本应用系统账号数据的增、改、删操作。

下游集成应用在OrgCreateService、OrgUpdateService、OrgDeleteService方法体内实现对本应用系统组织机构数据的增、改、删操作。

​

​​

4.2 接口列表

Ø 接口接收请求方式为http post方式。

Ø 接口地址后端的方法名需要按照上面表格定义实现。

Ø 对于在与身份认证系统集成前，已经有账号并希望纳入身份管理的应用系统，必须要实现接口4.4.1，4.4.2，4.4.3和4.4.4接口。

Ø 对于有组织机构管理和同步需求的应用系统，需要实现4.5.1，4.5.2，4.5.3和4.5.4的接口。

​

4.3 身份验证

在调用接口时，为了防止非法调用，需要在每次请求中添加授权信息（如账号名、密码）。第三方应用服务端为IAS系统分配接口调用的授权账号和密码。

IAS每次调用接口时，提供授权账号和密码，报文字段详见接口实现指导。

第三方应用服务端收到请求，校验授权账号和密码，校验通过则执行请求，校验不通过则返回错误提示。

4.3.1 数据示例

请求示例如下：选择raw和text（如下图所示）

4.3.2 数据同步输入使用AES加密

通过数据同步接口与下游集成系统数据交互时，需对所有数据进行加解密处理，使用AES加密算法。

示例代码:

4.4 接口功能列表

4.4.1 SchemaService接口

SchemaService的功能是获取第三方目标系统中“账号”等对象全部属性信息，包括属性名称、类型、是否必填字段、是否多值。

1）请求示例

{
  "bimRequestId": "9e928d12ec8a4c1bb75283b8df71308d",
  "bimRemotePwd": "password",
  "bimRemoteUser": "spcxxxxx"
}

2) 报文字段说明：

Ø bimRequestId ：IAS每次调用生成的随机ID，应用系统每次响应返回此ID，String类型。

Ø bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写，String类型。

Ø bimRemotePwd ：IAS调用三方应用接口的密码，由应用分配给IAS系统，String类型。

3）响应报文示例 ，organization 和 account返回字段类型固定

{
    "bimRequestId":"07423ca93c544a6c9073150d49578267",
    "organization":[
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"orgId"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"orgName"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"parentOrgId"
        } ,
        {
            "multivalued":false,
            "type":"string",
            "required": false,
            "name":"orgCode"
        }
    ],
    "account":[
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"oneId"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"mobile"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"email"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"loginName"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"fullName"
        },
        {
            "multivalued":false,
            "type":"string",
            "required":true,
            "name":"orgId"
        }
    ]
}

4) 响应报文字段说明：

Ø bimRequestId :IAS每次调用接口发送的请求ID，字段为String类型。

Ø account/organization :此接口定义的对象类型，可选值为account（账号）、organization（组织机构）、group（用户组），如果只做账号管理，organization等其它对象可以不用定义。字段为数组类型。

Ø name ：定义对象的属性字段名称。字段为String类型。

Ø type ：定义对象的属性字段类型，可选值为String、int、double、float、long、byte、boolean。字段为String类型(建议默认为String)。

Ø required : 定义对象的属性字段在创建时是否为必填字段。可选值true或者false。字段为boolean类型。

Ø multivalued ：定义对象的属性字段是否为多值。可选值true或者false。字段为boolean类型。

4.4.2 UserCreateService接口

UserCreateService接口是应用系统的账号创建方法

1) 报文示例：

{
    "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
    "bimRemoteUser": "spcxxxxx",
    "bimRemotePwd": "password",
    "loginName": "zhangsan",
    "orgId": "0000011",   (可选，无部门时留空)
    "fullName": "张三",
    "oneId": "0e1b6fcc-76ff-4972-b299-6b9e14495fde"（唯一主键，下游必存字段）
}

2) 报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø loginName：三方应用系统账号字段属性,唯一ID。

Ø fullName ：三方应用系统SchemaService接口中定义的账号字段属性。

Ø orgId: 创建Org 时, 维格则返回的 orgId

Ø oneId ：此id为用户自然人ID。此ID来自IAS系统。字段为String类型，必传字段。

3) 报文示例：

成功：

{
    "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
    "uid": "89746776",（交互主键id，参数名不能变）
    "resultCode": "0",
    "message": "success"
}

失败:

{
    "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
    "resultCode": "500",
    "message": "字段不全，账号创建失败"
}

4) 报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø uid ：应用系统账号创建后，形成的全局唯一ID，此ID不能被修改，建议为数据库表主键。此ID返回至IAS系统，此后账号的修改和删除都以此ID为主键。字段为String类型，必传字段。

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId :IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.3 UserUpdateService接口

UserUpdateService接口是应用系统的账号修改方法，如果有数据更新会对增量数据进行更新（请求报文只传修改的字段和交互主键id，不用传所有字段）。

1) 请求报文示例：

{
    "bimRequestId": "22928d12ec8a4c1bb75283b8df71308d",
    "bimRemoteUser": "spcxxxxx",
    "bimRemotePwd": "password",
    "bimUid": "89746776",（交互主键id，参数名不能变）
    "loginName": "lisi",
    "fullName": "李四"，
    "orgId":"0000011",    (可选，无部门时留空)
    "oneId": "0e1b6fcc-76ff-4972-b299-6b9e14495fde"
}

2) 报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimUid: 三方应用系统账号创建时，返回给IAS应用系统的账号主键uid。必传字段。

Ø loginName/ fullName ：需要修改的账号字段属性。

Ø oneId ：需要修改的账号自然人ID。

3) 响应报文示例：

{
    "bimRequestId": "22928d12ec8a4c1bb75283b8df71308d",
    "resultCode": "0",
    "message": "success"
}

4) 报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId :IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.4 UserDeleteService接口

UserDeleteService接口是应用系统的账号删除方法。

1) 请求报文示例：

{
    "bimRequestId": "33928d12ec8a4c1bb75283b8df71308d",
    "bimRemoteUser": "spcxxxxx",
    "bimRemotePwd": "password",
    "bimUid": "89746776"（交互主键id，参数名不能变）
}

2) 请求报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimUid: 三方应用系统账号创建时，返回给IAS应用系统的账号主键uid。必传字段。

3) 响应报文示例：

{
    "bimRequestId": "33928d12ec8a4c1bb75283b8df71308d",
    "resultCode": "0",
    "message": "success"
}

4) 响应报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId ：IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.5 OrgCreateService接口

OrgCreateService接口是应用系统的组织机构创建方法。字段可以根据参考示例增减

1) 请求报文示例：

{
        "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
        "bimRemoteUser": "spcxxxxx",
        "bimRemotePwd": "password",
        "orgName": "集团信息中心",
        "orgId": "ORG0001",（唯一主键，下游必存字段）
        "parentOrgId": "000001".
}

2) 请求报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø OrgId/orgName / parentOrgId：三方应用系统SchemaService接口中定义的组织机构字段属性。parentOrgId上级组织id一般必传，是组织机构树建立的依据。

3) 响应报文示例：

成功:

{
        "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
        "uid": "0000011",（交互主键id，参数名不能变）
        "resultCode": "0",
        "message": "success"
}

失败:

{
        "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
        "resultCode": "500",
        "message": "字段不全，组织机构创建失败"
}

4) 响应报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø uid：应用系统组织机构创建后，形成的全局唯一ID，此ID不能被修改，建议为数据库表主键。此ID返回至BIM系统，此后组织机构的修改和删除都以此ID为主键。字段为String类型，必传字段。

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId ：IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.6 OrgUpdateService 接口

OrgUpdateService接口是应用系统的组织机构修改方法，如果有数据更新会对增量数据进行更新（请求报文只传修改的字段和交互主键id，不会传所有字段）。

1) 请求报文示例：

{
        "bimRequestId": "22928d12ec8a4c1bb75283b8df71308d",
        "bimRemoteUser": "spcxxxxx",
        "bimRemotePwd": "password",
        "bimOrgId": "0000011",（交互主键id，参数名不能变）
        "orgName": "集团信息中心-改",
        "parentOrgId": "000002", (IAS侧父节点Id)
}

2) 请求报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimOrgId : 三方应用系统组织机构创建时，返回给IAS应用系统的组织机构主键orgId。必传字段。

Ø orgName / parentOrgId：需要修改的组织机构字段属性。

3) 响应报文示例：

{
        "bimRequestId": "22928d12ec8a4c1bb75283b8df71308d",
        "resultCode": "0",
        "message": "success"
}

4) 响应报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId : IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.7 OrgDeleteService 接口

OrgDeleteService接口是应用系统的组织机构删除方法。

1) 请求报文示例：

{
    "bimRequestId": "33928d12ec8a4c1bb75283b8df71308d",
    "bimRemoteUser": "spcxxxxx",
    "bimRemotePwd": "password",
    "bimOrgId": "000011"（交互主键id，参数名不能变）
}

2) 请求报文字段说明：

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimOrgId: 三方应用系统组织机构创建时，IAS应用系统的返回主键orgID。必传字段。

3) 响应报文示例：

{
        "bimRequestId": "22928d12ec8a4c1bb75283b8df71308d",
        "resultCode": "0",
        "message": "success"
}

4) 响应报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId : IAS每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.8 QueryUserByIdService 接口

根据4.4.2接口查询返回的账号ID，查询账号的详细信息。

1) 请求报文示例：

{
        "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
        "bimRemoteUser": "spcxxxxx",
        "bimRemotePwd": "password",
        "bimUid": "89746776", //（交互主键id，必传，找不到值时可传0）
        "oneId": "0e1b6fcc-76ff-4972-b299-6b9e14495fde" //(选填，uid和 oneId 都传时，优先使用oneId)
}

2) 报文字段说明

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimUid: 4.4.5接口查询返回的账号ID。必传字段。

3) 响应报文示例

{
        "account": {
                "orgId": "0000011",
                "loginName": "zhangsan",
                "fullName": "zhangsanFull",
                "uid": "D00001"
        },
        "resultCode": "0",
        "message": "success",
        "bimRequestId": "55528d12ec8a4c1bb75283b8df71308d "
}

4) 报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø account ：应用返回的账号json对象。必传字段。

Ø orgId/loginName/fullName : 三方应用系统SchemaService接口中定义的账号字段属性。

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

Ø bimRequestId :BIM每次调用接口发送的请求ID，字段为String类型，必传字段。

4.4.9 QueryOrgByIdService 接口

根据4.4.5接口查询返回的组织机构ID，查询组织机构的详细信息。

1) 请求报文示例：

{
        "bimRequestId": "11928d12ec8a4c1bb75283b8df71308d",
         "bimRemoteUser": "spcxxxxx",
        "bimRemotePwd": "password",
        "bimOrgId": "0000011", //（交互主键id，参数名不能变）
        "openOrgId": "ORG0001", //(选填，bimOrgId和 openOrgId 都传时，优先使用openOrgId)
}

2) 报文字段说明

Ø bimRequestId/bimRemotePwd/bimRemoteUser ：组织架构和账号将同步推送到此spaceId的空间站，务必认真填写该字段，说明见SchemaService。

Ø bimUid: 4.4.5 接口查询返回的组织机构ID。必传字段。

3) 响应报文示例

{
        "account": {
                "orgId": "0000011",
                "loginName": "zhangsan",
                "fullName": "zhangsanFull",
                "uid": "D00001"
        },
        "resultCode": "0",
        "message": "success",
        "bimRequestId": "55528d12ec8a4c1bb75283b8df71308d "
}

4) 报文字段说明：响应报文字段名需按文档定义，不允许自定义

Ø organization：应用返回的账号json对象。必传字段。

Ø orgName / parOrgId / orgId: 三方应用系统SchemaService接口中定义的组织机构字段属性。

Ø resultCode ：接口调用处理的结果码，0为正常处理，其它值由应用系统定义。字段为String类型，必传字段。

Ø message ：接口调用处理的信息。字段为String类型。

5、返回码