Zabbix SAML Authentication via Nginx Reverse Proxy

Problem:

The customer was running Zabbix 7.4 in a Docker-based environment and attempted to configure SAML authentication using Microsoft Entra ID. Although the SAML integration was partially configured and no critical errors were visible, the customer faced several issues.

• SAML authentication could not be selected as the default authentication method in the Zabbix UI.
• Users were not automatically redirected to Entra ID (SSO) when accessing the Zabbix URL.
• Multiple configuration attempts involving environment variables and Docker volumes caused uncertainty about the system’s current state.

This resulted in prolonged troubleshooting and confusion over whether the issue was related to Zabbix, Docker, SAML configuration, or the reverse proxy layer.

Process:

Step 1 – Initial Analysis

The expert reviewed the full problem description provided by the customer, customer-provided screenshots of various system settings, logs, and configuration files, focusing on:

• The docker-compose.yml file
• Mounted volumes that could override Zabbix or PHP-SAML files
• Environment variables related to SAML

An earlier configuration included a custom mount overriding the Utils.php file from the OneLogin PHP-SAML library. Such overrides can prevent proper SAML initialization, causing SAML options to be hidden in the UI. Although this mount was removed, validating the current runtime state was essential.

Step 2 – Environment Validation

To establish a clean baseline, the expert:

• Verified that the running image was the official Zabbix 7.4 Docker image
• Confirmed SAML-related environment variables were correctly passed
• Checked the integrity of the OneLogin PHP-SAML library
• Verified required PHP extensions (including php-openssl)
• Reviewed container logs for silent PHP or SAML errors

In parallel, a clean reference environment was deployed using the same Zabbix image. In this setup, the SAML tab appeared correctly, confirming that the issue was environment-specific.

Step 3 – Clarifying the Actual Requirement

During follow-up discussions, the customer clarified that the core issue was not the absence of the SAML tab, but the inability to set SAML as the default authentication method.

The expert explained that by design:

• Zabbix does not allow SAML to be set as the default authentication method via the UI
• SAML operates in parallel with internal authentication
• The local login form remains available even with JIT provisioning enabled

Step 4 – Architectural Solution via Nginx

The expert explained that enforcing SAML-only authentication must be done at the web server level. Since the customer was already using a custom nginx configuration, the nginx_ssl.conf file was reviewed.

A simple and effective solution was identified:

• Redirect users accessing the main Zabbix URL to the SAML login endpoint
• Keep the standard login page accessible via a direct URL for emergency access

This approach aligns with common enterprise SSO enforcement practices.

Solution:

The final solution included:

• A minimal change to the custom nginx_ssl.conf file (single redirect rule)
• Automatic redirection to Entra ID when accessing the main Zabbix URL
• Preservation of local login access via a direct URL
• No changes to Zabbix core code or Docker images

After applying the change and reloading the container, the customer confirmed successful SAML redirection and full issue resolution.

Conclusion:

This case demonstrates the importance of distinguishing between application capabilities and infrastructure-level enforcement. While Zabbix supports SAML authentication, enforcing SAML-only access requires configuration at the reverse proxy level.

Key takeaways include:

• Overriding vendor libraries in containers can cause subtle, hard-to-diagnose issues
• Clean reference environments are critical for isolating configuration problems
• SSO enforcement is best handled at the web server or gateway layer
• Clear requirement clarification significantly reduces troubleshooting time

Through careful validation and minimal architectural changes, the issue was resolved cleanly and reliably.