OAuth2单点登录

概述

OAuth 2.0是一种开放授权协议，它允许用户授权第三方应用访问他们在另一个服务提供方上的数据，而无需分享他们的凭据（如用户名、密码）。这种协议非常适合用于实现单点登录（SSO），使用户在多个应用之间无缝切换，无需重复登录。OAuth2.0协议定义了四种授权模式，Smartbi主要支持授权码模式（Authorization Code Grant）
前置条件：

1. 统一登录平台使用OAuth 2.0协议的授权码模式，希望单点登录到Smartbi。
2. 统一登录平台跟Smartbi用户一致；可参考 用户同步 做用户同步
3. 部署OAuth2单点登录扩展包，参考：部署扩展包

适用场景：

1. 统一登录平台通过连接单点登录到Smartbi首页。
2. 统一登录平台通过连接单点登录打开Smartbi集成页面，包括打开资源、创建资源、打开模块等。
3. 统一登录平台通过连接单点登录打开Smartbi移动端首页
4. 未登录时，浏览器输入Smartbi连接自动跳转到统一登录平台的登录页面。
5. 通过Smartbi前端注销则注销整个统一登录平台。

名词解释

• 统一登录平台：统一登录平台是企业或组织用于集中管理用户身份认证与权限控制的系统，用户通过一次登录即可访问所有授权的内部或外部应用，无需重复输入账号密码。
• OAuth 2.0： 是统一登录平台实现身份认证与授权流程的核心协议之一，统一登录平台可以使用OAuth 2.0或其它协议。
• Client ID：OAuth 2.0授权服务器颁发的应用ID。
• Client Secret：OAuth 2.0授权服务器颁发的应用密钥。
• Code：在OAuth 2.0授权码模式中，授权服务器生成的短期有效的授权码
• Access Token：访问用户资源的令牌，一般有较短的有效期。

单点登录流程（授权码模式（Authorization Code）)

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

• 只支持PC端及集成页面单点登录，不支持插件端（电子表格、分析报告）及移动端APP；移动端可通过集成页面实现单点登录。
• 可通过界面配置登录流程中涉及的接口地址及接口参数等。
  • 支持自定义配置分配给Smartbi服务器的应用ID（Client ID），应用密钥（Client Secret）
  • 支持自定义灵活配置接口
    • 包括：重定向统一登录地址、用授权码换取Access Token接口地址、用Access Token获取用户接口地址、统一注销地址
    • 支持灵活配置接口入参、并可通过扩展方式支持入参的特殊处理（比如入参特殊加密，加前缀等）
      • 可配置参数名称、参数设置方式（request、header、cookie等）、参数来源等
  • 支持登录用户处理：用户不存在时的处理逻辑可配置，包括新建用户/不允许登录等
  • 支持逃生通道：允许部分或全部用户使用逃生通道，或者直接禁用逃生通道
  • 支持多套统一登录系统单点登录同一套Smartbi应用（多套系统的接口地址及入参不同，可单独配置）

单点登录配置

入口

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

使用流程

1、在"统一身份管理平台"注册Smartbi应用；获取应用ID，应用密钥，并记录备用。

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

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

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

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

3、把第一步申请的应用ID及应用密钥添加到Smartbi单点登录配置中；后续接口调用时可直接引用

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

4.1、依次配置"统一登录/获取授权码"接口、"用授权码换取Token"接口、"用Token获取用户"接口，这3个接口必须依次配置（下图示意其中一个接口）

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

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

1. 1. 随意增减参数个数
   2. 自定义参数名称，基于接口实际参数名称填写
   3. 选择入参设置方式：可设置到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传递，键值对拼接。
   4. 选择参数来源及参数值：
      1. 可配置静态值、动态时间戳、或者是应用ID、应用密钥、上个接口的返回值等
         1. "上个接口返回"用来获取上一个接口的返回值，并传递到当前接口中，第一个接口获取token。
         2. "Smartbi单点地址"用来获取单点登录Smartbi时使用的Smartbi连接地址，一般在前置请求需要回调url时使用。

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

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

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

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

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

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

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

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

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

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

接口配置示例

基于oauth2的授权码模式接口使用流程，由于每个接口在不同项目中的具体配置参数不太一致，示例中会说明依据的接口说明，项目需要根据自己的接口说明做调整。

获取授权码接口

• 接口定义：

• smartbi配置：

用授权码换取Token接口

• 接口定义：

• smartbi配置：

用Token获取用户接口

• 接口定义：

• smartbi配置：