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登录

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

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

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

2.2 Oauth2登录对接配置

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

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

步骤二：添加登录策略

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

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

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

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

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

步骤五：配置Oauth2三方登录

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

Quick BI账号配置页面如下（相关配置项请参见内置账号配置说明）：
开启OAuth2登录
在弹出窗口填写OAuth2的配置信息。

其中，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/x-www-form-urlencoded 传参方式：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）提供
请求access_token额外 header 信息	否	请求access_token时http header中要附加的额外信息，以JSON形式保存, 一般无需填写。	{"Content-Encoding":"identity"}	由租户侧鉴权服务器（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，具体请参见本文协议对接说明部分的第2点：三方用户信息映射。账户ID必须保持唯一性。	$.id	由租户侧鉴权服务器（IDP）提供
用户账户名称解析	是	从获取的用户信息中得到账户名称所在的 jsonpath 配置，形如：$.accountName，具体请参见本文协议对接说明部分的第2点：三方用户信息映射。账户名称必须保持唯一性。	$.login	由租户侧鉴权服务器（IDP）提供
用户昵称解析	是	从获取的用户信息中得到昵称所在的jsonpath配置，形如：$.nickname，具体请参见本文协议对接说明部分的第2点：三方用户信息映射。用户昵称必须保持唯一性。	$.login	由租户侧鉴权服务器（IDP）提供
Session 失效时间（秒）	是	指定失效时间，失效后，重新发起校验。	86400	由租户侧自定义
Cookie 失效时间（秒）	是	-1，表示随浏览器关闭失效； > 0，指定失效时间，失效后重新登录	86400	由租户侧自定义

步骤六：保存并发布策略

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

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

3. 登录验证

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

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

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

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

4. 登录常见问题

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

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

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

三方认证服务器的回调地址配置错误，请参见本文快速开始部分1.1的内容。

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

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

协议对接说明

1. 登录流程

三方用户访问Quick BI页面，未登录跳转到登录策略中配置的[授权服务器登录地址]
OAuth2服务器认证登录后通过自身系统中配置的callback_url重定向到Qucik BI页面返回授权码code
Quick BI接收到请求后，提取请求中的所有参数包括code，加上登录策略中配置的[client ID]，[client secret]，[请求access_token额外参数]调用[请求 access_token 地址]获取token令牌
Quick BI拿到token后调用登录策略中配置的[请求用户信息地址]获取登录用户的信息
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字段。