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

SAML协议对接及配置说明

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

本文为您介绍SAML协议的对接及配置说明。

说明

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

背景信息

SAML（Security Assertion Markup Language）协议是一种基于XML的安全认证协议，它主要用于在不同的安全域之间传递身份验证和授权信息。SAML协议的主要目的是为了实现单点登录和跨域身份验证，本文介绍如何使用SAML协议与Qucik BI进行登录对接。

应用场景

  • SAML标准定义了身份提供者IDP(identity provider)和服务提供者SP(service provider)，这两者分别对应认证系统和Quick BI。

  • 在与Quick BI进行登录对接时，身份提供者就是指三方使用的认证系统如微软Azure，它会向用户提供身份验证服务，并生成SAML断言。服务提供者则是指Quick BI系统，它会接收到SAML断言，并根据其中的信息对用户进行身份验证，从而实现登录对接。

快速开始

1. 前置准备

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

各个三方SAML的鉴权服务器（IDP）配置客户端的方式可能不一致，根据实际情况操作，目的是获取IDP方的联合元数据文件，即IDP MetaData元数据文件。以对接微软Azure为例说明如何获取IDP MetaData元数据文件：

步骤一：在微软Azure中搭建Quick BI SAML应用。

设置SP标识符（唯一标识）和回复URL（登录成功后跳转地址，格式为：http(s)://{Quick BI访问地址}/login/saml/callback）。

image..png

步骤二：下载 IDP MetaData元数据文件

不同的平台下载页面不一样，此处参考微软Azure的SAML登录的元数据XML下载，每个文档下载后一定是xml文件，且包含标签 IDPSSODescriptor

image..png

2. 在Quick BI进行对接配置

2.1 开启SAML登录

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

image..png

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

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

2.2 SAML登录对接配置

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

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

image.png

步骤二：添加登录策略

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

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

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

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

image.png

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

image.png

步骤五：配置SAML三方登录

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

image.png

  • 开启SAML登录

image.png

  • 在弹出窗口填写SAML的配置信息。

    image.png

其中，标准SAML账号相关的配置项及说明。

配置项

说明

参考值

提供方

系统名称

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

三方SAML

由租户侧自定义

系统icon

说明

配置项为“认证平台类型”，说明为“用于记录当前对接的IDP类型，包括但不限于azure、ad-fs、ascm等”，参考值为空。提供方为“由租户侧鉴权服务器（IDP）提供”。

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

由租户侧自定义

认证平台数据

由外部身份提供商（IdP）提供的元数据文档，它包括 IdP 的登录服务地址以及 X.509 公钥证书（用于验证 IdP 所颁发的 SAML Assertion 的有效性）。

https://login.microsoftonline.com/9eXXXXXf-XXXX-XXXX-XXXX-XXXXXXXXXXX5/samlX

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

认证凭条证书

由元数据文档上传自动填入，不可编辑。

-----BEGIN CERTIFICATE-----XXXXXXXXXXXXXXXXXX-----END CERTIFICATE-----

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

登录有效期

说明

  • 配置项为“通信绑定方式”，说明为“用于标注与IDP通信时的通信绑定方式，不填默认为urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect，可选值为urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST”，参考值为空。提供方为“由租户侧鉴权服务器（IDP）提供”。

  • 配置项为“身份提供项名称”，说明为“由外部身份提供商IDP提供的身份提供项名称或ID，某些IDP通信时身份认证会需求此项，请查阅IDP平台说明”，参考值为空，提供方为“由租户侧鉴权服务器（IDP）提供”.

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

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

-1

由租户侧自定义

步骤六： 保存并发布策略

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

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

image.png

3. 登录验证

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

image.png

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

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

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

4. 登录常见问题

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

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

image.png

协议说明

1.登录流程

Quick BI作为SAML协议中的SP角色，用户请求登录Quick BI，SP生成SAML请求，IDP接收并解析SAML请求并进行用户认证后返回SAML响应，SP接收并解析SAML响应后，提取断言Assertion中的用户信息用于登录Quick BI。

以微软Azure为例：

  1. 用户访问Quick BI，点击已配置好的SAML登录渠道。image

  2. Quick BI根据IDP Meta元数据文件，构造请求体（SAMLRequest）并跳转到IDP的登录地址

    image.png

  3. IDP登录成功后会自动跳转回在IDP配置的回复（回调）地址：http(s)://{Quick BI访问地址}/login/saml/callback

    image.png

  4. 接收到IDP登录成功的信息后解析返回体（SAMLResponse），根据IDP Meta元数据文件对x509证书验签

    image.png

  5. 解析SAMLResponse中的用户数据用于Quick BI登录

    image.png

最佳实践-对接微软Azure的SAML应用

1. 资源准备

1.1. 在IDP（Azure AD）中搭建Quick BI SAML应用

该流程使用微软的Azure平台作为IDP，在使用期间需要对微软的账号进行服务订阅（账号订阅Azure Active Directory）。

  • 选择 Azure Active Directory。

    image.png

  • 选择企业应用程序。

    image.png

  • 创建你自己的应用程序。

    image.png

  • 选择集成未在库中找到的任何其他应用程序（非库）,假设名称是saml-test，并点击创建。

    image.png

  • 设置单一登录->开始。

    image.png

  • 选择单一登录方法-SAML。

    image.png

  • 上传元数据文件或手动进行SAML配置。

    image.png

  • 若选择上传元数据文件，即SP MetaData

示例SP MetaData元数据文件，里面的${domain}需要替换成配置的域名。其中，X509Data证书需要与IDP MetaData中的保持一致，证书内容可以替换，以下为示例。

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${domain}">
    <md:SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIIDdzCCAl+gAwIBAgIEcLh01DANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdVbmtub3duMRAw
                        DgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYDVQQKEwdVbmtub3duMRAwDgYD
                        VQQLEwdVbmtub3duMRAwDgYDVQQDEwdVbmtub3duMB4XDTE0MDUxMzE0MTEwMVoXDTE0MDgxMTE0
                        MTEwMVowbDEQMA4GA1UEBhMHVW5rbm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5r
                        bm93bjEQMA4GA1UEChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjEQMA4GA1UEAxMHVW5rbm93
                        bjCCASIwDQYJKcccsad23QEBBQADggEPADCCAQoCggEBAM7Z3B24Js7QFGqsQALG2PorXMrUEGdT
                        +mmnGeNYeZ0b7faUFUVc7xyGAoAdaRKqUsMYMcTInk1iC6KxpGNiemnpgwApB9S3sZOP2lxl42bI
                        relsrhZ+dWGvE6tbszOCGJGCB2/P+qydAbYHOsRxElIxDiiygbPzYZdGmpQXHl2qmegymWHss9+f
                        1W3+2+wCCr3wdTsyeXFQp/Z4uFJtHrUaN1FgCsL3MWepJEaaWegElu5XnN40/3vT216L0Ye89uYp
                        GNF5bvDNufbOVnA90xDVFGBI+gJeUk3/akVQmopCcQ+cgUs2HCsqSXHbjkafgSQanMeWZJNSllP0
                        JVo8RjECAwEAAaMhMB8wHQYDVR0OBBYEFEeaJ0sRg9qf6cRLDdZbi4SiAGucMA0GCSqGSIb3DQEB
                        CwUAA4IBAQAUKVZRkNm4lR1uCogyrSnSObfg/aayrRb5/CT1bYFQCJYC53VJHKlllKg/L9jMaVRI
                        gmX5NJyCsuCOG4ievW91PSzPMAizgLA87VZxOddInuXeDenPAy60gUmu2ab2mnUWi0KLB/gBYGVV
                        HK5E9Veb3ZwKS+LCvAhy4jjes2vaM6tMWISmQtkilPS1a3wh9AY6YRCGgG6np/RNpVPYiqtWw3Zs
                        Jm9U8s/MOMeS/i7BC77rRVQLXaiFjPbcGU/b/SygT9kEDSgEmxXbxqWAw6DJB3b2pUR6LFuiLbRX
                        wrb4lOubv8GAqYt6GYxGnkAZ6OicftZbiLb0KpywDA/vOWsH</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://${domain}/login/saml/callback" index="0" isDefault="true"/>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

  • 若选择手动配置，需要设置好标识符、回复URL。

    image.png回复URL作为登录成功后跳转的SP地址。

  • 下载Azure对应的元数据文件。

    image.png该元数据XML内的包含了公钥x509证书，即IDP MetaData。

1.2 在Azure AD中分配用户

  • 在Azure AD中选择用户->创建新用户。

    image.png

    image.png

  • 新建用户后，到企业应用程序并选择进入刚刚创建的企业程序saml-test应用中，点击概述->分配用户和组。

    image.png

  • 添加用户/组。

    image.png

  • 在用户和组下边新增的用户访问saml-test的权限

2. SP服务提供方（Quick BI）

Quick BI作为SP方，会提取IDP联合元数据XML的信息，即读取IDP MetaData元数据文件，详见1.1步骤中的「下载联合元数据文件」。

x509证书

登录地址，IDP门户的登录地址

image.png

IDPSSODescriptor是作为SAML协议中IDP方的描述内容存在

3. 在Quick BI中进行SAML协议的登录认证

配置详情请参见配置说明。

image.png

配置完成之后，访问Quick BI，即可选择saml跳转登录

image.png

  • 本页导读 （0）