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.

If JIT provisioning is enabled, a user group for deprovisioned users must be specified in the Authentication tab.

On top of JIT provisioning it is also possible to enable and configure SCIM provisoning - 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.

User provisioning without enabled and configured SCIM is made only for the login action.

Only users created by provisioning will be updated by the SCIM provisioning step; already existing SAML users will not be not provisioned. Only valid media will be added to user on provisioning action.

If SAML authentication is enabled, users will be able to choose between logging in locally or via SAML single sign-on. If JIT provisioning is used, then only single sign-on is possible.

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

It is required to install php-openssl if you want to use SAML authentication in the frontend.

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.

3 SAML - 图1

Configuration parameters, available in the Zabbix frontend:

ParameterDescription
Enable SAML authenticationMark the checkbox to enable SAML authentication.
Enable JIT provisioningMark the checkbox to enable JIT user provisioning.
IDP entity IDThe unique entity identifier within the SAML identity provider.
SSO service URLThe URL users will be redirected to when logging in.
SLO service URLThe URL users will be redirected to when logging out. If left empty, the SLO service will not be used.
Username attributeSAML attribute to be used as a username when logging into Zabbix.
The list of supported values is determined by the identity provider.

Examples:
uid
u,serprincipalname
samaccountname
username
userusername
urn:oid:0.9.2342.19200300.100.1.1
urn:oid:1.3.6.1.4.1.5923.1.1.1.13
urn:oid:0.9.2342.19200300.100.1.44
SP entity IDThe unique service provider identifier (if not matching, the operation will be rejected).
It is possible to specify a URL or any string of data.
SP name ID formatDefines which name identifier format should be used.

Examples:
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
urn:oasis:names:tc:SAML:2.0:nameid-format:entity
SignMark the checkboxes to select entities for which SAML signature should be enabled:
Messages
Assertions
AuthN requests
Logout requests
Logout responses
EncryptMark the checkboxes to select entities for which SAML encryption should be enabled:
Name ID
Assertions
Case-sensitive loginMark the checkbox to enable case-sensitive login (disabled by default) for usernames.
E.g. disable case-sensitive login and log in with, for example, ‘ADMIN’ user even if the Zabbix user is ‘Admin’.
Note that with case-sensitive login disabled the login will be denied if multiple users exist in Zabbix database with similar usernames (e.g. Admin, admin).
Configure JIT provisioningMark this checkbox to show options related to JIT user provisioning.
Group name attributeSpecify the group name attribute for JIT user privisioning.
User name attributeSpecify the user name attribute for JIT user privisioning.
User last name attributeSpecify the user last name attribute for JIT user privisioning.
User group mappingMap a SAML user group pattern to Zabbix user group and user role.
This is required to determine what user group/role the provisioned user will get in Zabbix.
Click on Add to add a mapping.
The SAML group pattern field supports wildcards. The group name must match an existing group.
If a SAML user matches several Zabbix user groups, the user becomes a member of all of them.
If a user matches several Zabbix user roles, the user will get the highest permission level among them.
Media type mappingMap the user’s SAML media attributes (e.g. email) to Zabbix user media for sending notifications.
Enable SCIM provisioningMark this checkbox to enable SCIM 2.0 provisioning.

See example of configuring Okta as SAML identity provider for sign-in and JIT/SCIM user provisioning.

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.:

  1. https://<your-zabbix-url>/zabbix/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.

In OneLogin:

  • It is not possible to pass groups. To use user roles for this purpose instead:
    • Add an attribute whose name matches the group attribute in Zabbix and it needs to receive the user role value from OneLogin;
    • Add a rule where groups are set as role;
    • The role names should not contain ; as OneLogin uses it as a separator when sending an attribute with several roles.
  • For OneLogin SCIM to work, it needs to receive in response a ‘name’ attribute with ‘givenName’ and ‘familyName’, even if it was not required by the service provider. Thus it is necessary to specify this in the schema in the application configuration part;

Note that the Users PATCH request (used by MS Azure) does not support changes in media.

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’]

Zabbix uses OneLogin’s SAML PHP Toolkit library (version 3.4.1). The structure of $SSO[‘SETTINGS’] section should be similar to the structure used by the library. For the description of configuration options, see official library documentation.

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:

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

Configuration example:

  1. $SSO['SETTINGS'] = [
  2. 'security' => [
  3. 'signatureAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha384'
  4. 'digestAlgorithm' => 'http://www.w3.org/2001/04/xmldsig-more#sha384',
  5. // ...
  6. ],
  7. // ...
  8. ];