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运维人员添加权限。

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

2.2 SAML登录对接配置

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

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

步骤二：添加登录策略

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

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

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

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

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

步骤五：配置SAML三方登录

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

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

其中，标准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	由租户侧自定义

步骤六：保存并发布策略

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

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

3. 登录验证

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

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

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

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

4. 登录常见问题

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

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

协议说明

1.登录流程

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

以微软Azure为例：

用户访问Quick BI，点击已配置好的SAML登录渠道。
Quick BI根据IDP Meta元数据文件，构造请求体（SAMLRequest）并跳转到IDP的登录地址
IDP登录成功后会自动跳转回在IDP配置的回复（回调）地址：http(s)://{Quick BI访问地址}/login/saml/callback
接收到IDP登录成功的信息后解析返回体（SAMLResponse），根据IDP Meta元数据文件对x509证书验签
解析SAMLResponse中的用户数据用于Quick BI登录

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

1. 资源准备

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

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

选择 Azure Active Directory。
选择企业应用程序。
创建你自己的应用程序。
选择集成未在库中找到的任何其他应用程序（非库）,假设名称是saml-test，并点击创建。
设置单一登录->开始。
选择单一登录方法-SAML。
上传元数据文件或手动进行SAML配置。
若选择上传元数据文件，即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>