备案控制台
文档
产品文档
输入文档关键字查找
首页

OAuth2.0 协议对接及配置说明

更新时间：
一键部署
产品详情
相关技术圈
我的收藏

本文为您介绍OAuth2.0 的鉴权服务器的标准协议。

说明

仅独立部署版本支持对接OAuth2.0 协议，对接前请联系Quick BI运营负责人。

背景信息

对于已有支持 OAuth2.0 的鉴权服务器的租户，需要在原有基础上针对外部系统进行接入，从而实现单点登录以及打通企业内部员工基础信息的需求。本文为您介绍OAuth2.0 的鉴权服务器的标准协议，如何与Quick BI进行SSO登录集成对接，对接说明请参见协议对接说明。

应用场景

  • 支持授权码模式的 OAuth2.0 标准协议（须满足相关 endpoint 及其参数定义）。

  • 支持使用配置化的方式对Quick BI进行接入。

  • 仅用于登录对接，Quick BI为SP服务提供方，以下涉及的对接配置需要IDP方（租户侧）提供。

快速开始

1. 接入前准备

1.1 租户侧在OAuth 2.0鉴权服务器上配置Quick BI客户端

各个三方OAuth2.0的鉴权服务器配置客户端的方式可能不一致，根据实际情况操作，目的是完成以下Quick BI 接入的配置项，包括：

配置项

是否必填

说明

client ID

是

颁布给 Quick BI 用于标识身份的客户端ID。

client secret

否

颁布给 Quick BI 用于身份校验的客户端Secret。

scope

推荐

用于获取用户信息时的权限范围。

参数内容以实际租户支持的权限范围名称定义而定，该权限范围需要至少覆盖返回用户的：内部id、账户名称、昵称等信息。

callback url

是

在获取授权码后回调 Quick BI 的地址，格式上为：Quick BI 域名 + /login/oauth2/callback

例如，租户侧部署的 Quick BI 域名为 https://a.quickbi.com，则该回调地址为：https://a.quickbi.com/login/oauth2/callback

1.2 网络要求

对接前，请确保您的鉴权服务器地址和Quick BI服务地址的网络连通性！

2. 在Quick BI进行对接配置

2.1 开启OAuth2登录

步骤一：使用登录认证超管账号进入超级管理员后台。

image..png

若账号无权限登录时，会出现以下界面，提示“无权限禁止访问”。请联系Quick BI运维人员添加权限。image.png

步骤二： 选择登录系统管理->登录全局开关，开启/关闭指定的三方登录方式，保存后立即生效image.png

2.2 Oauth2登录对接配置

步骤一：打开登录认证配置页面

在运维中心->登录策略配置或开放平台->登录认证位置打开。两个位置打开的配置效果是一样的，下边以在运维中心打开对应页面为例，页面如下：

image.png

步骤二：添加登录策略

若您已配置过登录策略，则跳过步骤二。

每个登录策略都允许配置一套域名/IP拦截策略，用来指定访问指定域名或IP时Quick BI支持的登录方式。

登录策略配置请参见自定义企业登录门户。

步骤三：选中需要开启Oauth登录的策略，并点击编辑

image.png

步骤四：在「编辑策略」页面，选择基础设置

image.png

步骤五：配置Oauth2三方登录

在您进行Oauth2三方登录配置前，若您未开启Quick BI账号，建议开启，原因为：1）防止三方登录设置错误后，无法登录Quick BI；2）自定义账号配置成功且能正常登录后，可根据需要关闭Quick BI账号。

其中，OAuth2.0 协议相关的配置项及说明如下：

配置项

是否必填

说明

参考值

提供方

授权服务器登录地址

是

授权服务器登录地址。

用于获取 授权码（code） 的URL。通常来说是三方的登录地址，根据实际情况需要带入Quick BI的颁布信息。

例如：http://[鉴权服务器URL]?client_id=b7ff8e66xxxx3ab2xxxxe&scope=read

https://github.com/login/oauth/authorize?client_id=fc9cxxxxxxxxxxaxxxxf&scope=read

由租户侧鉴权服务器（IDP）提供

授权服务器登出地址

否

授权服务器登出地址。

说明

使用此地址需要在登录设置中首先填写认证平台类型。

https://github.com/logout

由租户侧鉴权服务器（IDP）提供

认证平台类型

否

用于记录当前对接的IDP类型，例如keycloak。

github

由租户侧鉴权服务器（IDP）提供

系统名称

是

对接的系统名称，用于在登录项的按钮组标题显示。

三方账户OAuth2

由租户侧自定义

系统ICON

否

对接的系统图标，用于在登录项中的显示图标，最大32K。

由租户侧自定义

client ID

是

由 OAuth2.0 鉴权服务器颁发给应用的 ID。

fc9cxxxxxxxxxxaxxxxf

由租户侧鉴权服务器（IDP）提供

client secret

是

由 OAuth2.0 鉴权服务器颁发给应用的密钥。

c711xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5

由租户侧鉴权服务器（IDP）提供

scope

否

应用OAuth范围。

由租户侧鉴权服务器（IDP）提供

请求access_token地址

说明

请求 access_token 传参形式可选择body或url传参，默认为url，url由租户侧根据鉴权服务器实际情况选择。

是

OAuth2.0 鉴权服务器请求access token的地址。

Quick BI调用接口的请求方式：

  • HttpMethod：POST

  • Content-Type：application/json

  • 传参方式：url传参/body传参可选

  • Charset：UTF-8

  • 参数值：callback_url中的所有参数包括code，client ID，client secret，请求access_token额外参数

  • 返回结果：

{
    "access_token": "",
    "scope": "",
    "token_type": "",
    "expires_in": "",
    "refresh_token": ""
}

https://github.com/login/oauth/access_token

由租户侧鉴权服务器（IDP）提供

请求access_token额外参数

否

请求access token时需要添加的额外静态参数。

填写规范：为json格式。

{"redirect_uri":"https://{quickbi服务器地址}/login/oauth2/callback","grant_type":"authorization_code"}

由租户侧鉴权服务器（IDP）提供

请求用户信息地址

是

OAuth2.0 鉴权服务器请求用户信息的地址。

Quick BI调用接口的请求方式：

  • HttpMethod：GET

  • Content-Type：application/json

  • 传参方式：url传参

  • 参数：请求用户信息额外参数

  • Charset：UTF-8

请求时的token会放入Header中：

addHeader("Authorization", "Authorization Header类型"+ " " + "token的值");

https://api.github.com/user

由租户侧鉴权服务器（IDP）提供

Authorization Header类型

否

Authorization Header类型。

token或者bearer

由租户侧鉴权服务器（IDP）提供

请求用户信息额外参数

否

请求用户信息时需要添加的额外静态参数。

非必填，当请求用户信息接口有特定参数需求时需要配置。

填写规范：json格式的字符串

{
    "aa": 1,
    "bb": 2
}

由租户侧鉴权服务器（IDP）提供

用户账户ID解析

是

从获取的用户信息中得到账户 ID 所在的jsonpath配置，形如：$.accountId，请参见三方用户信息映射。

  • 账户ID必须保持唯一性。

$.id

由租户侧鉴权服务器（IDP）提供

用户账户名称解析

是

从获取的用户信息中得到账户名称所在的 jsonpath 配置，形如：$.accountName，请参见三方用户信息映射。

  • 账户名称必须保持唯一性。

$.login

由租户侧鉴权服务器（IDP）提供

用户昵称解析

是

从获取的用户信息中得到昵称所在的jsonpath配置，形如：$.nickname，请参见三方用户信息映射。

  • 用户昵称必须保持唯一性。

$.login

由租户侧鉴权服务器（IDP）提供

Session 失效时间（秒）

是

指定失效时间，失效后，重新发起校验。

86400

由租户侧自定义

Cookie 失效时间（秒）

是

-1，表示随浏览器关闭失效；

> 0，指定失效时间，失效后重新登录

86400

由租户侧自定义

步骤六： 保存并发布策略

保存发布后立即生效，请慎重操作。

推荐新建无痕模式窗口或者打开其他浏览器测试登录配置是否成功，以防退出登录后由于登录配置错误导致无法登录。

image.png

3. 登录验证

在您完成OAuth登录对接配置后，请访问Quick BI服务地址，并点击OAuth2登录，进行登录验证。

image.png

为了防止其他因素干扰，推荐新建无痕窗口用来测试登录。

需要注意的是所有的无痕窗口共用cookies，通过关闭窗口清空登录态时需要保证所有无痕窗口被关闭。

登录对接成功效果：当您登录后，出现以下页面，则说明已对接成功。 抛错原因是您当前登录的三方账号还未同步到Quick BI组织中，鉴权不通过，此时，您需要进行三方账号同步，请参见独立部署：三方账号同步方案。

image.png

4. 登录常见问题

4.1 AE0580800018 权限不足禁止访问，请联系组织管理员添加到具体组织

无组织用户默认无法访问Quick BI，需要先将三方账号添加到Quick BI，请参见独立部署：三方账号同步方案。

image.png

4.2 三方登录后携带code跳转到Quick BI，Quick BI没有发起token请求

三方认证服务器的回调地址配置错误，请参见1.1 租户侧在OAuth 2.0鉴权服务器上配置Quick BI客户端。

4.3 Quick BI请求三方接口失败，例如获取token或者用户信息失败

请联系运维同学查看日志报错。

协议对接说明

1. 登录流程

  1. 三方用户访问Quick BI页面，未登录跳转到登录策略中配置的[授权服务器登录地址]

  2. OAuth2服务器认证登录后通过自身系统中配置的callback_url重定向到Qucik BI页面返回授权码code

  3. Quick BI接收到请求后，提取请求中的所有参数包括code，加上登录策略中配置的[client ID]，[client secret]，[请求access_token额外参数]调用[请求 access_token 地址]获取token令牌

  4. Quick BI拿到token后调用登录策略中配置的[请求用户信息地址]获取登录用户的信息

  5. Quick BI拿到返回值后，通过登录策略中配置的JSONPATH规则解析得到三方账户ID，账户名，昵称并写入session登录，保存Qucik BI的登录cookie

流程图

2. 三方用户信息映射

Quick BI 通过 OAuth2.0 鉴权完毕后，需要获取租户侧的用户信息注入系统，维护账户信息，其中必要参数有：

  • 用户在 OAuth2.0 服务器上的内部ID（对应Quick BI的AccountId）

  • 用户在 OAuth2.0 服务器上的账户名称（对应Quick BI的账号）

  • 用户在 OAuth2.0 服务器上的昵称（对应Quick BI的昵称）

对于用户信息接口返回，目前仅支持 JSON 格式的接口返回，Quick BI 侧以 JSONPath 的语法解析上述的必要参数，以租户信息接口返回如下为例：

{
 "id": 1,
 "info": {
 "account_name": "xxx",
 "nick_name": "xxx"
 }
}

则相关的配置项为：

配置项

是否必选

说明

用户账户 ID 解析

是

$.id：标识获取到根节点下ID字段。

用户账户名称解析

是

$.info.account_name：标识获取到根节点 > info节点下account_name字段。

用户昵称解析

是

$.info.nick_name：标识获取到根节点 > info节点下nick_name字段。

  • 本页导读 （0）