OIDC协议对接及配置说明-阿里云帮助中心

本文为您介绍OIDC的鉴权服务器的标准协议及配置说明。

说明

仅独立部署版本支持对接OIDC协议，可自行完成对接。若需要紧急支持或专家指导，请联系Quick BI运营负责人。

背景信息

OpenID Connect（OIDC）是建立在 OAuth 2.0 协议之上的身份认证和授权协议，是OAuth2.0的扩展，属于比较主流的登录协议。对于已有支持OIDC的鉴权服务器的租户，需要在原有基础上针对外部系统进行接入，从而实现单点登录以及打通企业内部员工基础信息的需求。

本文为您介绍OIDC的鉴权服务器的标准协议以及如何与Quick BI进行SSO登录集成对接，对接说明请参见协议对接说明。

应用场景

支持授权码模式的 OIDC 标准协议（须满足相关 endpoint 及其参数定义）。
支持使用配置化的方式对Quick BI进行接入。
仅用于登录对接，Quick BI为SP服务提供方，以下涉及的对接配置需要IDP方（租户侧）提供。

快速开始

1. 接入前准备

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

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

配置项	是否必填	说明
client ID	是	颁布给 Quick BI 用于标识身份的客户端ID。
client secret	否	颁布给 Quick BI 用于身份校验的客户端Secret。
callback url	是	在获取授权码后回调 Quick BI 的地址，格式上为：Quick BI 域名 + /login/oidc/callback 例如，租户侧部署的 Quick BI 域名为 https://a.quickbi.com，则该回调地址为：https://a.quickbi.com/login/oidc/callback

1.2 网络要求

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

2. 在Quick BI进行对接配置

2.1 开启OIDC登录

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

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

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

2.2 OIDC登录对接配置

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

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

步骤二：添加登录策略

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

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

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

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

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

步骤五：配置OIDC三方登录

重要

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

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

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

配置项	是否必填	说明	填写规范/参考值	提供方
授权服务器登录地址	是	用于获取授权码（code）的URL。通常来说是三方的登录地址，根据实际情况需要带入Quick BI的颁布信息。	https://github.com/login/oauth/authorize?client_id=fc9cxxxxxxxxxxaxxxxf&scope=read	由租户侧鉴权服务器（IDP）提供
授权服务器登出地址	否	授权服务器登出时的URL地址。	填写规范： Quick BI调用接口的请求方式为GET，请求时的token会放入Header中： addHeader("Authorization", "Authorization Header类型"+ " " + "token的值"); 参考值：https://github.com/logout	由租户侧鉴权服务器（IDP）提供
系统名称	是	对接的系统名称，用于在登录项的按钮组标题显示。	三方账户OIDC	由租户侧自定义
系统ICON	否	对接的系统图标，用于在登录项中的显示图标，最大32K。（icon注意对齐一下）		由租户侧自定义
client ID	是	由 OIDC 鉴权服务器颁发给应用的 ID。	fc9cxxxxxxxxxxaxxxxf	由租户侧鉴权服务器（IDP）提供
client secret	是	由 OIDC 鉴权服务器颁发给应用的密钥。	c711xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5	由租户侧鉴权服务器（IDP）提供
请求token地址	是	OIDC 鉴权服务器请求token的地址。	https://eiam-api-cn-hangzhou.aliyuncs.com/v2/idaas_mayjwcaw6huncj2nk3rgqqvd7m/app_mzutlrgucmvgjgpmowq5qyhflm/oauth2/token	由租户侧鉴权服务器（IDP）提供
请求token额外参数	否	请求access token时需要添加的额外静态参数。	{"redirect_uri":"http://{quickbi服务器地址}/login/ram/oauth2/callback","grant_type":"authorization_code"}	由租户侧鉴权服务器（IDP）提供
请求用户信息地址	是	OIDC鉴权服务器请求用户信息的地址。	https://api.github.com/user	由租户侧鉴权服务器（IDP）提供
验证id_token签名的加密算法公钥	否	用于解密OIDC签名算法的公钥。	填写规范：为JSON格式。 "kty" (key type): 表示密钥的类型。在这里，它是"RSA"，意味着这是一个RSA类型的公钥。 "e": RSA算法的指数部分，通常是一个固定的小数值，这里是"AQAB"，这实际上是数字65537的Base64url编码形式。 "use": 密钥的预期用途。这里的"sig"表示该密钥用于签名验证。 "kid" (key ID): 是用来标识密钥的唯一ID。这对于管理多组密钥非常有用，特别是在密钥轮换的情况下。 "n": RSA算法的模数部分，是公钥的核心组成部分。这里显示的是一个很长的数字，经过Base64url编码。 `{ "keys": [ { "kty": "RSA", "e": "AQAB", "use": "sig", "kid": "KEY8MWJoYCsQehRMSxknckYMPJ94k6Z2VMoW", "n": "" } ] }`	由租户侧鉴权服务器（IDP）提供
用户账户ID映射	是	从获取的用户信息中得到账户ID所在的字段映射。	sub	由租户侧鉴权服务器（IDP）提供
用户账户名称映射	是	从获取的用户信息中得到账户名称所在的字段映射。	$.preferred_username preferred_username	由租户侧鉴权服务器（IDP）提供
用户昵称映射	是	从获取的用户信息中得到昵称所在的字段映射。	nick	由租户侧鉴权服务器（IDP）提供
Session 失效时间（秒）	是	指定登录态Session的失效时间，失效后，重新发起登录校验。单位为秒，推荐值为86400。	86400	由租户侧自定义
Cookie 失效时间（秒）	是	Cookie的失效时间，单位为秒，失效后需重新登录。若值为-1，表示随浏览器关闭失效；若值大于 0，则按指定值失效，推荐值为86400。	86400	由租户侧自定义

步骤六：保存并发布策略

重要

保存发布后立即生效，请慎重操作。
推荐新建无痕模式窗口或者打开其他浏览器测试登录配置是否成功，以防退出登录后由于登录配置错误导致无法登录。

3. 登录验证

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

说明

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

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

协议对接说明

1. 登录流程

三方用户访问Quick BI页面，未登录跳转到登录策略中配置的[授权服务器登录地址]
OIDC服务器认证登录后通过自身系统中配置的callback_url重定向到Quick BI页面返回授权码code
Quick BI接收到请求后，提取请求中的所有参数包括code，加上登录策略中配置的[client ID]，[client secret]，[请求OIDC_token额外参数]调用[请求 OIDC_token 地址]获取OIDC令牌
Quick BI拿到OIDC后调用登录策略中配置的RSA验签公钥验证OIDC签名，验签成功后解析OIDC获取登录用户的信息
Quick BI拿到返回值后，通过登录策略中配置的JSONPATH规则解析得到三方账户ID，账户名，昵称并写入session登录，保存Quick BI的登录cookie

2. 三方用户信息映射

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

用户在 OIDC 服务器上的内部ID（对应Quick BI的AccountId）
用户在OIDC 服务器上的账户名称（对应Quick BI的账号）
用户在 OIDC 服务器上的昵称（对应Quick BI的昵称）

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

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

配置项	是否必选	说明
用户账户 ID 映射	是	id：标识获取ID字段。
用户账户名称映射	是	account_name：标识获取account_name字段。
用户昵称解析映射	是	nick_name：标识获取nick_name字段。