外部应用集成

外部应用集成分为三个方面

• 外部应用注册到企业门户中
• 外部应用单点登录
• 企业门户中的组织同步到外部应用中

特别说明

• 企业门户与外部应用调用安全性机制
  • 企业门户调用外部应用的安全性，通过外部应用提供的 apisecret 来实现
  • 外部应用调用企业门户的安全性，通过集成用户登录的方式来实现
• 创建测试租户和正式租户
  • 测试时使用测试租户
  • 生产时使用正式租户

外部应用注册

外部应用

提供服务元信息接口

服务元信息接口（外部应用服务地址/serviceMetaInfo），支持匿名访问，企业门户调用方式如下

url: 外部应用服务地址/serviceMetaInfo?apisecret=$apisecret
method: get
request field:
    apisecret: $apisecret        //注册外部应用时提供的 apisecret
response body(application/json)         //JSON 对象，格式如下
response status: 200表示成功，其它表示失败

按照下面的格式返回外部应用的菜单、角色和权限

• 在 $.serviceInfo.label 中，定义外部应用名称
• 在 $.serviceInfo.name 中，定义外部应用编码
• 在 $.menu 中定义菜单
• 在 $.authorize.permissions 中定义权限
• 在 $.authorize.roles 中定义角色，在 $.authorize.roles.permissions 中定义角色包含的权限，使用权限中的 code 值
• 权限 code 和菜单 url 的关系是：权限 code = *: + 菜单 url # 前面的部分 + :get
  • 例如菜单地址为 https://h5.dev.com/platform/?id=1919&type=ERP#/sso
  • 权限 code 为 *:https://h5.dev.com/platform/?id=1919&type=ERP:get

特别说明

• 系统默认使用？前面的部分鉴权，如果需要使用 url 中的参数进行鉴权，需要通过增加 $pparams 参数指定权限参数
  • 例如菜单地址为 https://h5.dev.com/platform/?id=1919&type=ERP#/sso，id 和 type 参数需要鉴权，增加 $pparams=id,type
  • 增加 $pparams 参数后，菜单地址为 https://h5.dev.com/platform/?id=1919&type=ERP&$pparams=id,type#/sso
  • 权限 code 中不需要写 $pparams，为 *:https://h5.dev.com/platform/?id=1919&type=ERP:get

{
    "serviceInfo":{
        "label":"外部应用",
        "name":"external"
    },
    "menu":{
        "children":[
            {
                "children":[],
                "ext":{},
                "title":"外部应用菜单一",
                "types":["func","mobile","pcx","openPage"],
                "url":"https://h5.dev.com/platform/?id=1919&type=ERP&$pparams=id,type#/sso"
            },{
                "children":[],
                "ext":{},
                "title":"外部应用菜单二",
                "types":["func","mobile","pcx","openPage"],
                "url":"https://h5.dev.com/platform/?id=1919&type=MES&$pparams=id,type#/sso"
            }
        ],
        "ext":{},
        "title":"外部应用一级目录",
        "types":[]
    },
    "authorize":{
        "permissions":[{
            "id" : "menu_001",
            "code" : "*:https://h5.dev.com/platform/?id=1919&type=ERP:get",
            "name" : "外部应用菜单一",
            "type" : "menu"
            },{
            "id" : "menu_002",
            "code" : "*:https://h5.dev.com/platform/?id=1919&type=MES:get",
            "name" : "外部应用菜单二",
            "type" : "menu"
               }],
        "roles":[{
                    "id" :"authc",
                    "code" : "authc",
                    "name" : "注册用户",
                    "permissions" : [ "*:https://h5.dev.com/platform/?id=1919&type=ERP:get",
                      "*:https://h5.dev.com/platform/?id=1919&type=MES:get"]
            }]
    }
}

后续外部应用更新服务元信息接口后，打开“企业门户-系统管理-服务注册”，找到外部应用，点击“刷新”按钮即可更新门户中的菜单、权限和角色

企业门户

注册外部应用

打开“企业门户-系统管理-服务注册”进行手工注册，注册时需要提交以下参数：

• 显示名称：外部应用中文名
• 服务地址：外部应用服务地址，支持两个接口，接收通知（/notice）和服务元信息（/serviceMetaInfo）
• 外部服务秘钥 apisecret：apisecret 是双方协商的一个字符串，企业门户服务调用外部服务时，会带 apisecret 参数，外部服务通过 apisecret 保证调用的安全性

特别说明

• 如果外部应用提供了接收通知接口，注册后，应该打开组织管理或用户管理，点击组织同步，实现第一次的组织同步
• 外部应用更新服务元信息接口后，点击外部应用后面的“刷新”按钮，更新门户中的菜单、权限和角色

注册失败

注册时，提示服务注册失败，大致存在两种问题

无法获取服务元信息

服务地址 + /serviceMetaInfo 无法访问，检查服务地址，如果服务地址无误，进入企业门户终端，通过 curl 测试服务元信息接口

使用租户管理员登录控制台，打开应用/服务管理，点击企业门户右侧的监控按钮，如下图所示，打开监控日志对话框

进入 POD 终端，输入 curl + 服务地址 + /serviceMetaInfo，测试服务元信息接口，下图中第一个 curl 有错，第二个正确。另外当外部应用的服务地址，只能内网访问时，需要保证在企业门户的 POD 中能访问，就在 POD 终端里面使用 curl 测试即可

解析服务元信息失败

检查服务元信息接口返回的是否是 JSON 对象，可打开企业门户日志，查看报错信息

使用租户管理员登录控制台，打开应用/服务管理，点击企业门户右侧的监控按钮，如下图所示，打开监控日志对话框

在 POD 日志页签中，查看 java-runtime 日志，通过右下角的翻页按钮，查找错误日志，在错误输出前会输出服务元信息接口返回的内容，如下图所示

单点登录

企业门户

打开外部应用菜单

外部应用注册后，在门户功能树中，可以看到注册的外部应用的菜单。打开外部应用的菜单时，将以浏览器页的方式打开另一个窗口，同时在 url 上添加一个参数 token

特别说明

• 企业门户使用 https://medialize.github.io/URI.js/ 解析 url，它只会把参数加到 pathname 前面

外部应用

打开外部应用页面

从菜单打开的 url 中获取 token，调用“企业门户域名/entry/uaa/userinfo”接口，获取用户信息。企业门户 /userinfo 接口如下，在 Cookie 中传入 user_session=token

url: 企业门户域名/entry/uaa/userinfo
method: get
request cookie:
    user_session: $token    //企业门户打开外部应用菜单时给的 token
response body(application/json)
    {
        "user_id":"",    //用户标识
        "username":"",    //登录名
        "name":""    //中文名
        "phone_number":"",
        "email":""
    }
response status: 200成功，其它失败

获取用户信息后，使用外部应用的用户登录，跳转相应地址

组织同步

企业门户

添加集成用户

在用户管理中添加用户，或使用已有用户。在按组织授权中，给这个用户分配“系统集成”应用角色，使之成为集成用户

所有外部应用可以共用同一个集成用户，也可以每个外部应用创建一个集成用户

企业门户管理员线下将集成用户名、密码和企业门户地址下发给外部应用维护人员

组织同步配置

在组织同步配置中添加外部应用，并设置“导出组织已分配的角色”选项。

• 选中这个选项，组织增量数据中会包括组织已分配的角色 id，例如：roles: ["","",""]
• 不选中这个选项，则不包括 roles
• 这个选项应该在第一时间确定，因为该选项改变后，会导致已分配角色的组织或用户的镜像发生改变

组织同步

企业门户提供两种方式发送组织变化的通知：自动通知和手动通知。如果组织和用户都没变，则组织镜像 md5 不变

自动通知

设置环境变量实现自动通知。打开应用服务管理，点击企业门户V2的配置，如下图所示

选择环境设置，点击 uaa 的设置参数，如下图所示

设置组织改变后是否自动发送通知，默认不发送

手工通知

在“企业门户-系统管理-组织用户管理-组织管理（或用户管理）”中点击“同步组织”发送组织变化通知。在“企业门户-系统管理-系统配置-组织同步管理”中配置的应用会收到组织变化通知

外部应用

提供接收通知接口

接收通知接口（外部应用服务地址/notice），支持匿名访问，企业门户调用方式如下，企业门户不获取该接口的返回结果

url: 外部应用服务地址/notice?apisecret=$apisecret
method: post
request field:
    apisecret: $apisecret        //注册外部应用时提供的 apisecret
request body(application/json):
    {
        "type": "orgChanged",     //通知类型, 取值范围: 组织变化通知 orgChanged
        "data": {        //通知数据
            "orgDigest": ""    //最新组织镜像的 md5
        }
    }
response status: 200表示成功，其它表示失败

集成用户登录

在接收通知接口中，先使用集成用户登录企业门户，再获取组织增量数据。调用“企业门户域名/login”接口，登录企业门户。企业门户 /login 接口如下，此接口返回 user_session，用于调用“获取组织增量数据”接口

url: 企业门户域名/login
method: post
request header
    Accept: application/json 
    content-type: application/x-www-form-urlencoded
request body(form)
    username: ""            //用户名
    password: ""            //密码
response cookie
    user_session: ""        //后续调用企业门户接口时需要使用
response status: 200成功，其它失败

获取组织增量数据

在接收通知接口中，获取到最新的组织镜像 md5，存起来，下次使用，这次使用上次的组织镜像 md5，获取组织增量和用户增量数据。如果组织和用户都没变，则组织镜像 md5 不变，外部应用自行存储 md5，以便判断新的消息是否处理

调用“企业门户域名/entry/misc/org/getOrgSnapshot?orgDigest=组织镜像md5”接口，获取组织增量数据。企业门户 /getOrgSnapshot 接口如下，此接口调用前必须登录集成用户

url: 企业门户域名/entry/misc/org/getOrgSnapshot?orgDigest=$orgDigest
method: get
request cookie:
    user_session: $user_session        //集成用户登录后返回的 user_session
request field:
    orgDigest: 外部服务当前组织镜像的 md5     //当 orgDigest 为空或给定的 orgDigest 不存在时，将会返回组织最新的全量数据
response body(application/json)
    {
        "success": true,        //状态, 取值范围 true, false
        "msg": "",             //错误消息
        "type": "delta"    ,        //数据格式, 取值范围: 增量(delta), 全量(all),
        "orgDigest": "",        //当前组织镜像的 md5
        "data":{
            "orgs": [{  //组织数据，即包括机构、部门、岗位，也包括人员成员
                active: 启用状态 //1表示启用，0表示禁用
                id: 组织 id
                code: 组织编码
                name: 组织名称
                parentid: 上级组织 id
                                roles: ["", ""] //组织的角色 id 列表
                state: "add",//新增add、修改update、删除delete，增量数据有此列，全量数据无此列
                sequence: 序号
                type: "dpt",//机构是ogn，部门是dpt，岗位是pos，人员成员是psm
            }],
            "users": [{  //用户数据
                active: 用户状态 //1表示有效，0表示无效
                address: 办公地址
                                authorities: 用户类型
                gender: 性别
                givenName: 忽略，兼容保留
                id: 用户 id
                                mainOrg: 用户主组织 id
                name: 用户姓名
                                roles: ["", ""], //用户的角色 id 列表
                state: "add",//新增add、修改update、删除delete，增量数据有此列，全量数据无此列
                type: "org" //org是组织内用户，其它是外部用户
                userName: 用户名（可用来登录企业门户）
                verified: 账号状态 //1表示有效，0表示无效
            }]
        }
    }
response status: 200表示成功，其它表示失败

根据收到的组织增量数据，更新外部应用中的组织和用户

组织增量数据说明

通过几张获取组织增量数据接口的返回值截图说明

• orgs 是组织，包括人员成员，users 是用户。users 中的用户和 orgs 中的人员成员内容不同。例如 users 下有手机号，orgs 下没有。如果一人多岗，orgs 中会有多条记录，users 中只有一条记录

• state 等于 add 表示新增

• 下图是 orgs 中的人员成员信息

• 下图是 users 中的人员信息