概述

当客户系统有统一登录认证协议，但并未使用标准行业规范（例如：OAuth2/CAS/LDAP等协议），而是使用自建协议。产品提供了灵活易用的可视化配置界面，方便客户快速实现统一登录平台单点登录到Smartbi应用
前置条件：

1、统一登录平台需单点登录到Smartbi，未使用行业标准协议，但提供了自建协议接口：

1.1、必须提供至少一个接口（RESTful API）

1.2、接口返回值是JSON格式字符串

2、建议统一登录平台跟Smartbi用户一致；可参考 用户同步 做用户同步

3、如果用户不一致时，支持使用Smartbi固定账号登录，但一般不建议这么使用。

4、部署自建协议单点登录扩展包，下载扩展包：Smartbi_Special_APISSO，参考 部署扩展包 部署

适用场景：

1、统一登录平台通过连接单点登录到Smartbi首页。

2、统一登录平台通过连接单点登录打开Smartbi集成页面，包括打开资源、创建资源、打开模块等。

3、统一登录平台通过连接单点登录打开Smartbi移动端首页

4、未登录时，浏览器输入Smartbi连接自动跳转到统一登录平台的登录页面。

5、通过Smartbi前端注销则注销整个统一登录平台。

名词解释

统一登录平台：统一登录平台是企业或组织用于集中管理用户身份认证与权限控制的系统，用户通过一次登录即可访问所有授权的内部或外部应用，无需重复输入账号密码。

token：访问用户资源的令牌，一般有较短的有效期。

单点登录流程

单点登录使用限制及主要能力

1、只支持PC端及集成页面单点登录，不支持插件端（电子表格、分析报告）及移动端APP；移动端可通过集成页面实现单点登录。

2、可通过界面配置登录流程中涉及的接口地址及接口参数等，支持自定义灵活配置接口：

2.1、接口包括：前置授权请求（可选）、统一登录接口（必须）、独立获取用户接口（可选）、统一注销地址（可选）。

2.2、其中：前置授权请求，主要解决类似OAuth2协议，请求Smartbi连接后需要重定向到"统一登录平台"获取授权码（code）的场景。

3、支持灵活配置接口入参、并可通过扩展方式支持入参的特殊处理（比如入参特殊加密，加前缀等）

3.1、可配置参数名称、参数设置方式（request/header、cookie等）、参数来源等

4、支持登录用户处理：用户不存在时的处理逻辑可配置，包括新建用户/不允许登录等

5、支持逃生通道设置：允许部分或全部用户使用逃生通道（Smartbi原始登录页面），或者直接禁用逃生通道

6、支持多套统一登录系统单点登录同一套Smartbi应用（多套系统的接口地址及入参不同，可单独配置）

单点登录配置

入口

入口：运维设置/单点登录设置，需要操作权限："运维设置/模块配置与管理"（操作权限参考xx）

使用流程及配置信息说明

1、参考Smartbi"单点登录设置"中的"Smartbi单点登录地址"，在"统一登录平台"中添加Smartbi的访问连接。

1.1、其中"单点登录应用范围"，可以选择应用单点登录的页面，如果不应用，则打开该页面会继续使用Smartbi的账号密码进行登录验证。

1.2、访问连接可基于实际情况选择使用"Smartbi单点登录地址"或者是应用范围中的页面。

1.3、当应用范围中未包含需要单点登录处理的页面时，可通过"自定义"添加，添加到"自定义"中的页面，未登录时，也会正常跳转到"统一登录平台"的登录页面。

2、基于"统一登录平台"的单点登录接口配置文档，在Smartbi中依次配置单点登录接口信息。

依次配置 前置授权请求（可选），统一登录接口（必须）、独立获取用户信息接口（可选）、统一注销接口（可选），如有疑问，可参考后续"自建协议场景配置示例"。

2.1、前置授权请求（可选），主要解决类似OAuth2协议，请求Smartbi连接后需要重定向到"统一登录平台"获取授权码（code）的场景，开启"前置授权请求"设置项后可配置使用。

2.2、大部分自建协议会提供2个接口，一个接口获取token，一个接口基于token获取用户信息，产品默认支持该场景，直接配置即可。

2.3、部分情况下，自建协议只有一个接口，统一登录平台在打开Smartbi的连接中直接携带token，Smartbi通过自建协议接口验证token合法性，并在该接口直接获取登录用户信息

2.4、可选择配置统一注销地址：当点击Smartbi注销按钮，需要同步注销统一登录平台时，可选择配置

2.5、产品提供了灵活的配置设置，可基于实际接口文档自由选择，如有疑问可参考后续实际配置示例章节

• 随意增减参数个数
• 自定义参数名称，基于接口实际参数名称填写
• 选择入参设置方式：可设置到header，request(body)、cookie、session
  • 入参设置方式说明：
    • request/query：查询参数（Query Parameters），附加在URL的?后面，键值对形式，比如。
    • request/body：请求体参数（Body Parameters）：在请求体中传递，常见于POST、PUT等方法，默认是JSON格式。
      • 默认会在请求头中添加：Content-Type:application/json
      • 如果需要键值对格式，需要主动增加请求头参数：Content-Type:application/x-www-form-urlencoded
      • 暂不支持XML格式。
    • request/header：请求头参数（Headers）：在HTTP头部中传递，如Content-Type用于设置请求体参数格式。
    • cookie：Cookie参数：通过Cookie头传递，键值对拼接，如 。
    • session：session参数，通过session传递，键值对拼接。
• 选择参数来源及参数值：
  • 可配置静态值、动态时间戳、或者是上个接口的返回值等
    • "上个接口返回"用来获取上一个接口的返回值，并传递到当前接口中，第一个接口获取token。
    • "Smartbi单点地址"用来获取单点登录Smartbi时使用的Smartbi连接地址，一般在前置请求需要回调url时使用。

3、可选择配置登录用户处理规则：

• 当Smartbi的用户未实时跟统一登录的用户同步时，会出现登录用户在Smartbi中不存在的情况。
• 当遇到不存在的用户时，产品默认会提示：当前用户在Smartbi中不存在，请联系管理员添加。
• 客户可选择自动创建用户，并分配到某个默认组，默认角色，以便用户登录后直接访问有权限的资源。
• 当前只支持分配到固定的用户组或角色，不支持同步动态用户组。

4、可选择配置逃生通道：

• 逃生通道允许用户绕开oauth2登录协议，直接使用Smartbi账号密码登录，主要是解决oauth2服务异常、Smartbi单点登录配置错误等导致无法正常登录Smartbi的异常情况。
• 产品默认开启了逃生通道，用户可基于实际需求灵活配置。
• 注意：在最后一步单点登录验证成功前，不要禁用逃生通道，否则将无法正常登录Smartbi继续调整配置。

5、可选接口入参特殊处理：

• 当接口参数需要额外处理时使用，比如要特殊加密，或者在上一个接口的返回值+前缀后传给下一个接口等。
• 该场景需要额外定制开发，基于实际业务场景，通过java扩展接口实现。
• 产品提供了灵活的扩展接口，通过接口入参的高级配置实现。

6、可选择配置多系统登录Smartbi：

• 当客户的统一登录体系还不完善，有多套统一登录应用需要单点登录同一套Smartbi应用时，可启用该配置。
• 需要先在Smartbi单点登录配置中注册各个统一登录应用的id及名称，并在统一登录应用访问Smartbi的连接中携带应用id；此时各个统一登录应用有自己独立的单点登录配置，使用方式跟单个统一登录平台的使用完全相同。
• 为了减少各个统一登录应用的重复配置，提供了一键复制配置到其它应用的功能。

7、验证单点登录是否成功：有以下几种方式验证

• 通过第二步中添加的Smartbi访问入口，如果能正常单点登录到Smartbi，则成功。
• 打开浏览器独立新窗口，直接在地址栏中输入Smartbi的访问连接（见第二步说明），正常跳转到统一登录平台登录页，输入统一登录的账号密码后，正确跳转回Smartbi，则成功；
• 如果配置了统一注销接口，在Smartbi中点击注销，会调用OAuth2接口登出，并回到统一登录平台登录页
• 如果单点登录不成功，可基于具体的错误提示信息进行调整。

自建协议场景配置示例

场景1：统一登录平台携带token参数跳转到Smartbi，Smartbi回调统一登录平台接口校验并直接获取合法用户信息

原始需求描述：

在统一登录平台中，用户点击BI平台菜单时，前端会携带该 session 跳转到BI平台的 web 端。跳转url格式是:http:{ip}:{port}/bi/index.html?token=sessionId}&tenantId=3849234893
BI平台获取到token后，可以携带这个 sessionId 来调用一体化平台的接口。当 sessionId 有效时，便可以正常获取用户的唯一标识和用户名称。

接口说明：

Smartbi单点登录配置信息：

场景2：金蝶云之家单点登录到Smartbi

适用类似场景：统一登录平台不携带token，需要先通过统一登录接口获取token，再基于token获取合法用户信息

原始需求描述

基于云之家开放平台，添加Smartbi为云之家的轻应用，并实现单点登录。由于云之家轻应用有不同的授权级别，授权级别不同，获取接口的输入参数也是不同的，本示例以授权级别为app为例

配置流程：

1、统一登录获取token接口说明及Smartbi配置

接口定义 ：获取accessToken

smartbi配置：

2、统一登录获取用户接口说明及Smartbi配置

接口定义：基于token获取用户信息

smartbi配置：配置获取用户信息接口及入参等，重点注意几个参数的入参设置方式

场景3：需要使用重定向获取授权码，再基于授权码获取token，最后使用token获取用户信息。

原始需求描述

配置流程：

1、Smartbi单点登录配置：启用前置授权请求

2、统一登录（基于原始需求，后面简称4A）用户授权接口说明及Smartbi配置

接口定义：

smartbi配置：配置前置请求接口及入参相关信息

3、4A获取token接口说明及Smartbi配置

接口定义：

smartbi配置：配置获取token接口及入参、接口返回相关信息

5、4A获取用户信息接口说明及Smartbi配置

接口定义：

smartbi配置：配置获取用户接口及入参、接口返回/登录用户相关信息