3 SAML

Overview

SAML 2.0 authentication can be used to sign in to Zabbix.

If only SAML sign-in is configured, then the user must also exist in Zabbix, however, its Zabbix password will not be used. If authentication is successful, then Zabbix will match a local username with the username attribute returned by SAML.

User provisioning

It is possible to configure JIT (just-in-time) user provisioning for SAML users. In this case, it is not required that a user already exists in Zabbix. The user account can be created when the user logs into Zabbix for the first time.

On top of JIT provisioning it is also possible to enable and configure SCIM (System for Cross-domain Identity Management) provisioning - continuous user account management for those users that have been created by user provisioning. SCIM provisioning requires a Zabbix API token (with Super admin permissions) for authentication into Zabbix.

For example, if a user is moved from one SAML group to another, the user will also be moved from one group to another in Zabbix; if a user is removed from a SAML group, the user will also be removed from the group in Zabbix and, if not belonging to any other group, added to the user group for deprovisioned users.

If SCIM is enabled and configured, a SAML user will be provisioned at the moment the user logs into Zabbix and continuously updated based on changes in SAML. Already existing SAML users will not be provisioned, and only provisioned users will be updated. Note that only valid media will be added to a user when the user is provisioned or updated.

If SCIM is not enabled, a SAML user will be provisioned (and later updated) at the moment the user logs into Zabbix.

Setting up identity provider

In order to work with Zabbix, a SAML identity provider (onelogin.com, auth0.com, okta.com, etc.) needs to be configured in the following way:

• Assertion Consumer URL should be set to <path_to_zabbix_ui>/index_sso.php?acs
• Single Logout URL should be set to <path_to_zabbix_ui>/index_sso.php?sls

<path_to_zabbix_ui> examples: https://example.com/zabbix/ui, http://another.example.com/zabbix, http://<any_public_ip_address>/zabbix

Setting up Zabbix

To use SAML authentication Zabbix should be configured in the following way:

1. Private key and certificate should be stored in the ui/conf/certs/, unless custom paths are provided in zabbix.conf.php.

By default, Zabbix will look in the following locations:

• ui/conf/certs/sp.key - SP private key file
• ui/conf/certs/sp.crt - SP cert file
• ui/conf/certs/idp.crt - IDP cert file

2. All of the most important settings can be configured in the Zabbix frontend. However, it is possible to specify additional settings in the configuration file.

Configuration parameters, available in the Zabbix frontend:

See examples of configuring SAML identity providers for sign-in and user provisioning into Zabbix with:

• Microsoft Azure AD
• Okta
• Onelogin

Notes on SCIM provisioning

For SCIM provisioning specify the path to the Zabbix frontend and append api_scim.php to it, on the identity provider side, i.e.:

https://<path-to-zabbix-ui>/api_scim.php

User attributes that are used in Zabbix (username, user name, user lastname and media attributes) need to be added as custom attributes and, if necessary, external namespace should be the same as user schema: urn:ietf:params:scim:schemas:core:2.0:User.

Advanced settings

Additional SAML parameters can be configured in the Zabbix frontend configuration file (zabbix.conf.php):

• $SSO['SP_KEY'] = '<path to the SP private key file>';
• $SSO['SP_CERT'] = '<path to the SP cert file>';
• $SSO['IDP_CERT'] = '<path to the IDP cert file>';
• $SSO['SETTINGS']

Only the following options can be set as part of $SSO['SETTINGS']:

• strict
• baseurl
• compress
• contactPerson
• organization
• sp (only options specified in this list)
  • attributeConsumingService
  • x509certNew
• idp (only options specified in this list)
  • singleLogoutService (only one option)
    • responseUrl
  • certFingerprint
  • certFingerprintAlgorithm
  • x509certMulti
• security (only options specified in this list)
  • signMetadata
  • wantNameId
  • requestedAuthnContext
  • requestedAuthnContextComparison
  • wantXMLValidation
  • relaxDestinationValidation
  • destinationStrictlyMatches
  • rejectUnsolicitedResponsesWithInResponseTo
  • signatureAlgorithm
  • digestAlgorithm
  • lowercaseUrlencoding

All other options will be taken from the database and cannot be overridden. The debug option will be ignored.

In addition, if Zabbix UI is behind a proxy or a load balancer, the custom use_proxy_headers option can be used:

• false (default) - ignore the option;
• true - use X-Forwarded-* HTTP headers for building the base URL.

If using a load balancer to connect to Zabbix instance, where the load balancer uses TLS/SSL and Zabbix does not, you must indicate 'baseurl', 'strict' and 'use_proxy_headers' parameters as follows:

$SSO['SETTINGS']=['strict' => false, 'baseurl' => "https://zabbix.example.com/zabbix/", 'use_proxy_headers' => true]

Configuration example:

$SSO['SETTINGS'] = [
           'security' => [
               'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
               'digestAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#sha384',
               // ...
           ],
           // ...
       ];