SAML

Security 插件支持通过 SAML 单点登录进行用户身份验证。Security 插件实现了 SAML 2.0 协议的 Web 浏览器 SSO 配置文件。

此配置文件适用于 Web 浏览器。它不是针对 Security 插件验证用户的通用方法，因此其主要用例是支持 UDB-SX Dashboards 单点登录。

激活 SAML

要使用 SAML 进行身份验证，需要在 config/udbsx-security/config.yml 的 authc 部分配置相应的身份验证域。因为 SAML 仅在 HTTP 层工作，所以不需要任何 authentication_backend，可以将其设置为 noop。将本章中所有 SAML 特定的配置选项放在 SAML HTTP 认证器的 config 部分：

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    authc:
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_file: okta.xml
              ...
        authentication_backend:
          type: noop

在 config.yml 中配置 SAML 后，还必须在 UDB-SX Dashboards 中激活它。

运行多个身份验证域

我们建议至少添加另一个身份验证域，例如 LDAP 或内部用户数据库，以支持不带 SAML 的 UDB-SX API 访问。对于 UDB-SX Dashboards 和内部 UDB-SX Dashboards 服务器用户，还必须添加另一个支持基本身份验证的身份验证域。此身份验证域应放在链的第一个位置，并且必须将 challenge 标志设置为 false：

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    authc:
      basic_internal_auth_domain:
        http_enabled: true
        transport_enabled: true
        order: 0
        http_authenticator:
          type: basic
          challenge: false
        authentication_backend:
          type: internal
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            ...
        authentication_backend:
          type: noop

身份提供者元数据

SAML 身份提供者 (IdP) 提供一个 SAML 2.0 元数据文件，描述 IdP 的功能和配置。Security 插件可以从 URL 或文件读取 IdP 元数据。您的选择取决于您的 IdP 和偏好。SAML 2.0 元数据文件是必需的。

名称	描述
idp.metadata_file	您的 IdP 的 SAML 2.0 元数据文件的路径。将元数据文件放在 UDB-SX 的 config 目录中。路径必须相对于 config 目录指定。如果未设置 idp.metadata_url，则为必需。
idp.metadata_url	您的 IdP 的 SAML 2.0 元数据 URL。如果未设置 idp.metadata_file，则为必需。

IdP 和服务提供者实体 ID

实体 ID 是 SAML 实体（IdP 或服务提供者 (SP)）的全局唯一名称。IdP 实体 ID 通常由您的 IdP 提供。SP 实体 ID 是您的 IdP 中配置的应用程序或客户端的名称。我们建议为 UDB-SX Dashboards 添加一个新应用程序，并将 UDB-SX Dashboards 安装的 URL 用作 SP 实体 ID。

名称	描述
idp.entity_id	您的 IdP 的实体 ID。必需。
sp.entity_id	服务提供者的实体 ID。必需。

JWT 验证的时间差异补偿

有时您可能会发现身份验证服务器和 UDB-SX 节点之间的时钟时间没有完全同步。在这种情况下，即使只有几秒钟的差异，签发或接收 JSON Web 令牌 (JWT) 的系统可能会尝试验证 nbf（不早于）和 exp（过期）声明，并因时间差异而无法验证用户。

默认情况下，UDB-SX Security 允许有 30 秒的窗口来补偿服务器时钟时间之间可能的错位。要为该功能设置自定义值并覆盖默认值，可以将 jwt_clock_skew_tolerance_seconds 设置添加到 config.yml。

http_authenticator:
  type: saml
  challenge: true
  config:
    idp:
      metadata_file: okta.xml
    jwt_clock_skew_tolerance_seconds: 20

UDB-SX Dashboards 设置

Web 浏览器 SSO 配置文件通过 HTTP GET 或 POST 交换信息。例如，登录到 IdP 后，它会向 UDB-SX Dashboards 发送一个包含 SAML 响应的 HTTP POST。必须配置 UDB-SX Dashboards 安装的基本 URL，HTTP 请求将发送到该 URL。

名称	描述
kibana_url	UDB-SX Dashboards 基本 URL。必需。

用户名和角色属性

主体（例如，用户名）通常存储在 SAML 响应的 NameID 元素中：

<saml2:Subject>
  <saml2:NameID>admin</saml2:NameID>
  ...
</saml2:Subject>

如果您的 IdP 符合 SAML 2.0 规范，则无需设置任何特殊内容。如果您的 IdP 使用不同的元素名称，也可以显式指定其名称。

角色属性是可选的。但是，大多数 IdP 也可以配置为在 SAML 断言中添加角色。如果存在，可以在角色映射中使用这些角色：

<saml2:Attribute Name='Role'>
  <saml2:AttributeValue >Everyone</saml2:AttributeValue>
  <saml2:AttributeValue >Admins</saml2:AttributeValue>
</saml2:Attribute>

如果要从 SAML 响应中提取角色，需要指定包含角色的元素名称。

名称	描述
subject_key	SAML 响应中存储主体的属性。可选。如果未配置，则使用 NameID 属性。
roles_key	SAML 响应中存储角色的属性。可选。如果未配置，则不使用任何角色。

请求签名

从 Security 插件到 IdP 的请求可以选择性地进行签名。使用以下设置配置请求签名。

名称	描述
sp.signature_private_key	用于签名请求或解码加密断言的私钥。可选。当设置了 private_key_filepath 时不能使用。
sp.signature_private_key_password	私钥的密码（如果有）。
sp.signature_private_key_filepath	私钥的路径。文件必须放在 UDB-SX config 目录下，路径必须相对于同一目录指定。
sp.signature_algorithm	用于签名请求的算法。参见下表了解可能的值。

私钥必须为 PKCS#8 格式。如果要使用加密密钥，必须使用兼容 PKCS#12 的算法 (3DES) 进行加密。

Security 插件支持以下签名算法。

算法	值
DSA_SHA1	http://www.w3.org/2000/09/xmldsig#dsa-sha1;
RSA_SHA1	http://www.w3.org/2000/09/xmldsig#rsa-sha1;
RSA_SHA256	http://www.w3.org/2001/04/xmldsig-more#rsa-sha256;
RSA_SHA384	http://www.w3.org/2001/04/xmldsig-more#rsa-sha384;
RSA_SHA512	http://www.w3.org/2001/04/xmldsig-more#rsa-sha512;

注销

通常，IdP 在其 SAML 2.0 元数据中提供有关其单独注销 URL 的信息。如果是这种情况，Security 插件会使用它们在 UDB-SX Dashboards 中呈现正确的注销链接。如果您的 IdP 不支持显式注销，则可以在用户再次访问 UDB-SX Dashboards 时强制重新登录。

名称	描述
sp.forceAuthn	即使用户在 IdP 有活动会话，也强制重新登录。

目前，Security 插件仅支持 HTTP-Redirect 注销绑定。请确保在您的 IdP 中正确配置。

交换密钥设置

与其他协议不同，SAML 不用于在每个请求中交换用户凭据。Security 插件将 SAML 响应交换为一个轻量级的 JWT，该 JWT 存储经过验证的用户属性。此令牌由您选择的交换密钥签名。请注意，更改此密钥时，所有使用它签名的令牌立即失效。

名称	描述
exchange_key	用于签名令牌的密钥。算法是 HMACSHA512，因此我们建议使用 64 个字符，例如 9a2h8ajasdfhsdiydfn7dtd6d5ashsd89a2h8ajasdHhsdiyLfn7dtd6d5ashsdI。确保输入 exchange_key 的值，否则会返回错误。

TLS 设置

如果从 URL 加载 IdP 元数据，建议使用 SSL/TLS。如果使用像 Okta 或 Auth0 这样使用受信任证书的外部 IdP，通常无需配置任何内容。如果自己托管 IdP 并使用自己的根 CA，可以按如下方式自定义 TLS 设置。这些设置仅用于通过 HTTPS 加载 SAML 元数据。

名称	描述
idp.enable_ssl	是否启用自定义 TLS 配置。默认为 false（使用 JDK 设置）。
idp.verify_hostnames	是否验证服务器 TLS 证书的主机名。

示例：

authc:
  saml_auth_domain:
    http_enabled: true
    transport_enabled: false
    order: 1
    http_authenticator:
      type: saml
      challenge: true
      config:
        idp:
          enable_ssl: true
          verify_hostnames: true
          ...
    authentication_backend:
      type: noop

证书验证

通过设置以下配置选项之一来配置用于验证 IdP TLS 证书的根 CA：

config:
  idp:
    pemtrustedcas_filepath: path/to/trusted_cas.pem

config:
  idp:
    pemtrustedcas_content: |-
      -----BEGIN CERTIFICATE-----
      MIID/jCCAuagAwIBAgIBATANBgkqhkiG9w0BAQUFADCBjzETMBEGCgmSJomT8ixk
      ARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxGTAXBgNVBAoMEEV4YW1w
      bGUgQ29tIEluYy4xITAfBgNVBAsMGEV4YW1wbGUgQ29tIEluYy4gUm9vdCBDQTEh
      ...
      -----END CERTIFICATE-----

名称	描述
idp.pemtrustedcas_filepath	包含 IdP 根 CA 的 PEM 文件的路径。文件必须放在 UDB-SX config 目录下，并且必须相对于同一目录指定路径。
idp.pemtrustedcas_content	IdP 服务器的根 CA 内容。当设置了 pemtrustedcas_filepath 时不能使用。

客户端身份验证

Security 插件在获取 IdP 元数据时可以使用 TLS 客户端身份验证。如果启用，Security 插件会向 IdP 发送 TLS 客户端证书以进行每个元数据请求。使用以下键配置客户端身份验证。

名称	描述
idp.enable_ssl_client_auth	是否向 IdP 服务器发送客户端证书。默认为 false。
idp.pemcert_filepath	包含客户端证书的 PEM 文件的路径。文件必须放在 UDB-SX config 目录下，路径必须相对于 config 目录指定。
idp.pemcert_content	客户端证书的内容。当设置了 pemcert_filepath 时不能使用。
idp.pemkey_filepath	客户端证书私钥的路径。文件必须放在 UDB-SX config 目录下，路径必须相对于 config 目录指定。
idp.pemkey_content	证书私钥的内容。当设置了 pemkey_filepath 时不能使用。
idp.pemkey_password	私钥的密码（如果有）。

启用的密码套件和协议

可以限制 IdP 连接允许的密码套件和 TLS 协议。例如，可以仅启用强密码套件并将 TLS 版本限制为最新版本。

名称	描述
idp.enabled_ssl_ciphers	启用的 TLS 密码套件数组。仅支持 Java 格式。
idp.enabled_ssl_protocols	启用的 TLS 协议数组。仅支持 Java 格式。

最小配置示例

以下示例显示了最小配置：

_meta:
  type: "config"
  config_version: 2

config:
  dynamic:
    authc:
      saml_auth_domain:
        http_enabled: true
        transport_enabled: false
        order: 1
        http_authenticator:
          type: saml
          challenge: true
          config:
            idp:
              metadata_file: metadata.xml
              entity_id: http://idp.example.com/
            sp:
              entity_id: https://UDB-SX-dashboards.example.com
            kibana_url: https://UDB-SX-dashboards.example.com:6601/
            roles_key: Role
            exchange_key: 'peuvgOLrjzuhXf ...'
        authentication_backend:
          type: noop

UDB-SX Dashboards 配置

因为大多数 SAML 特定配置是在 Security 插件中完成的，只需在 udbsx_dashboards.yml 中通过添加以下内容激活 SAML：

udbsx_security.auth.type: "saml"

此外，必须将用于验证 SAML 断言的 UDB-SX Dashboards 端点添加到允许列表中：

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs"]

如果使用注销 POST 绑定，还需要将注销端点添加到允许列表中：

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"]

使用额外 Cookie 的会话管理

为了改进会话管理——特别是对于分配了多个角色的用户——Dashboards 提供了一个选项，将 Cookie 有效载荷拆分为多个 Cookie，然后在接收时重新组合有效载荷。这有助于防止较大的 SAML 断言超出每个 Cookie 的大小限制。以下示例中的两个设置允许您为额外的 Cookie 设置前缀名称并指定其数量。它们被添加到 udbsx_dashboards.yml 文件中。额外 Cookie 的默认数量为三个：

udbsx_security.saml.extra_storage.cookie_prefix: security_authentication_saml
udbsx_security.saml.extra_storage.additional_cookies: 3

请注意，减少额外 Cookie 的数量可能会导致更改前使用的一些 Cookie 停止工作。我们建议建立一个固定数量的额外 Cookie，之后不再更改配置。

如果来自 IdP 的 ID 令牌特别大，UDB-SX 可能会抛出服务器日志身份验证错误，指示 HTTP 头部太大。在这种情况下，可以增加 UDB-SX.yml 文件中 http.max_header_size 设置的值。

IdP 发起的 SSO

要使用 IdP 发起的 SSO，请将 IdP 的断言消费者服务端点设置为：

/_opendistro/_security/saml/acs/idpinitiated

然后将此端点添加到 udbsx_dashboards.yml 中的 server.xsrf.allowlist：

server.xsrf.allowlist: ["/_opendistro/_security/saml/acs/idpinitiated", "/_opendistro/_security/saml/acs", "/_opendistro/_security/saml/logout"]