12 使用 Microsoft Entra ID 设置 SAML

概述

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

Microsoft Entra ID 配置

创建应用程序

1. 登录 Microsoft Entra 管理中心，访问 Microsoft Entra ID。 为了测试，您可以在 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. 单击 Update 按钮以保存这些设置。

SCIM 用户预配

1. 在你的 Entra ID 应用页面中，从主菜单打开 Provisioning 页面。
点击 Get started，然后选择 Automatic provisioning mode：

• 在 Tenant URL 中，设置以下值：https://<path-to-zabbix-ui>/api_scim.php
• 在 Secret token 中，输入具有 Super admin 权限的 Zabbix API token。
• 点击 Test connection，查看连接是否已建立。

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

在 Attribute Mapping 列表底部，启用 Show advanced options，然后点击 Edit attribute list for customappsso。

在属性列表底部，添加你自己的属性，类型为 'String'：

保存该列表。

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

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

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

为此，转到 Microsoft Entra admin center，然后在相应的 Users 和 Groups 页面中添加用户/组。

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

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

请注意，Entra ID 中的 Users PATCH 请求不支持媒体中的更改。

身份验证请求签名

可以将 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
    ]
];