12 使用 Microsoft Entra ID 设置 SAML

概述

本节提供了相关指南，说明如何使用 SAML 2.0 身份验证，通过 Microsoft Entra ID（原 Microsoft Azure Active Directory）为 Zabbix 配置单点登录和用户预配。

Microsoft Entra ID 配置

创建应用程序

1. 登录 Microsoft Entra ID 中的 Microsoft Entra 管理中心。
出于测试目的，您可以在 Microsoft Entra ID 中创建一个免费试用帐户。

2. 在 Microsoft Entra 管理中心中，选择 Applications -> Enterprise applications -> New application -> Create your own application。

3. 添加应用程序名称，并选择 Integrate any other application... 选项。
之后，单击 Create。

设置单点登录

1. 在您的应用程序页面中，前往 Set up single sign on 并点击 Get started。 然后选择 SAML。

2. 编辑 Basic SAML Configuration：

• 在 Identifier (Entity ID) 中设置一个唯一名称，用于让 Microsoft Entra ID 识别您的应用，例如 zabbix；
• 在 Reply URL (Assertion Consumer Service URL) 中设置 Zabbix 单点登录端点：https://<path-to-zabbix-ui>/index_sso.php?acs：

请注意，必须使用“https”。 为了使其在 Zabbix 中生效，需要在 conf/zabbix.conf.php 中添加以下一行：

$SSO['SETTINGS'] = ['use_proxy_headers' => true];

3. 编辑 Attributes & Claims。 您必须添加所有希望传递给 Zabbix 的属性（user_name、user_lastname、user_email、user_mobile、groups）。

属性名称是任意的。 可以使用不同的属性名称，但要求它们与 Zabbix SAML 设置中相应字段的值一致。

• 点击 Add new claim 以添加属性：

• 点击 Add a group claim 以添加用于将组传递给 Zabbix 的属性：

在此声明中，重要的是通过所选的 Source attribute 将组名（而不是组 ID）传递给 Zabbix。 否则，JIT 用户预配将无法正常工作。

4. 在 SAML Certificates 中，下载 Entra ID 提供的 Base64 证书，并将其放入 Zabbix 前端安装目录的 conf/certs 中。

通过运行以下命令将其权限设置为 644：

chmod 644 entra.cer

5. 使用 Entra ID 中 Set up <your app name> 的值来配置 Zabbix SAML 身份验证（请参见下一节）：

Zabbix 配置

1. 在 Zabbix 中，前往 SAML 设置，并根据 Entra ID 配置填写相应的配置选项：

2. 添加 Entra ID 提供的 Base64 证书。

如果在 zabbix.conf.php 中设置了 $SSO['CERT_STORAGE'] = 'database'，则可以在 SAML 配置期间通过前端粘贴证书文本或上传证书文件——无需在文件系统中提供任何文件。

如果在 zabbix.conf.php 中设置了 $SSO['CERT_STORAGE'] = 'file'，则必须使证书在文件系统中可用（默认位于 ui/conf/certs 或 zabbix.conf.php 中配置的路径），并且前端不会将证书存储在数据库中。
请注意，如果未设置 $SSO['CERT_STORAGE'] 或将其注释掉，则默认使用文件存储，并从 ui/conf/certs 读取证书。

还需要配置用户组映射。
媒体映射是可选的。

3. 按 更新 按钮保存这些设置。

SCIM 用户预配

1. 在您的 Entra ID 应用页面中，从主菜单打开“预配”页面。
点击 开始使用，然后选择自动预配模式：

• 在 Tenant URL 中，设置以下值：https://<path-to-zabbix-ui>/api_scim.php
• 在 Secret token 中，输入一个具有超级管理员权限的 Zabbix API token。
• 点击 测试连接 以查看连接是否已建立。

2. 现在，您可以添加所有将通过 SCIM 传递到 Zabbix 的属性。
为此，点击 Mappings，然后点击 Provision Microsoft Entra ID Users。

在属性映射列表底部，启用 Show advanced options，然后点击 Edit attribute list for customappsso。

在属性列表底部，添加您自己的属性，类型为“String”：

保存该列表。

3. 现在，您可以为已添加的属性添加映射。
在属性映射列表底部，点击 Add New Mapping，并按如下所示创建映射：

添加完所有映射后，保存映射列表。

4. 作为将用户预配到 Zabbix 的前提条件，您必须先在 Entra ID 中配置用户和用户组。

为此，请前往 Microsoft Entra 管理中心，然后分别在“用户”和“组”页面中添加用户/组。

5. 当用户和组已在 Entra ID 中创建后，您可以进入应用的 Users and groups 菜单，并将它们添加到该应用中。

6. 前往应用的 Provisioning 菜单，然后点击 Start provisioning，即可将用户预配到 Zabbix。

请注意，Entra ID 中的 Users PATCH 请求不支持 media 变更。

身份验证请求签名

可以将 Entra ID 配置为验证签名的身份验证请求。

要使其生效，请创建公钥/私钥：

openssl req -x509 -newkey rsa:4096 -keyout /usr/share/zabbix/conf/certs/request-sign.key -out /usr/share/zabbix/conf/certs/request-sign.pem -sha256 -days 1825 -nodes

分配权限：

chown apache /usr/share/zabbix/conf/certs/request-sign.key 
chmod 400 /usr/share/zabbix/conf/certs/request-sign.key

通过添加以下内容来更新 Zabbix 前端配置：

$SSO['SP_KEY'] = 'conf/certs/request-sign.key';
$SSO['SP_CERT'] = 'conf/certs/request-sign.crt';

故障排查

当用户尝试通过 SAML 登录 Zabbix 时，如果该用户已使用 MicroSoft Edge 配置文件登录，则在 MicroSoft Edge 浏览器中可能会出现身份验证问题。 此类问题的一个表现是，用户可能能够在 MicroSoft Edge 的隐私模式下登录 Zabbix。

为避免此情况下的身份验证问题，可能需要在 Zabbix 前端配置文件（zabbix.conf.php）中将 requestedAuthnContext 设置为 "false"。

$SSO['SETTINGS'] = [
    'security' => [
        'requestedAuthnContext' => false
    ]
];