Zabbix 7.4 + Keycloak (SAML 2.0): End-to-End Setup with JIT Provisioning

By /

This guide connects Zabbix 7.4 at https://zabbix.maksonlee.com to Keycloak at https://keycloak.maksonlee.com (realm maksonlee.com) using SAML 2.0, and enables Just-in-Time (JIT) provisioning so users are created automatically on first login.

You’ll configure:

  • Keycloak: a SAML client + clean mappers via a dedicated client scope (username, email, groups)
  • Zabbix: SAML authentication + JIT provisioning (default role/groups)
  • Optional hardening: sign Zabbix AuthnRequests and require client signatures in Keycloak
  • File permissions hardening: keep private keys readable by Zabbix, but not writable by the web user

What we’ll build

  • Sign-in to Zabbix via Keycloak (SAML 2.0)
  • JIT user creation: on first login, Zabbix creates a normal user and assigns role + groups
  • Clean attribute delivery from Keycloak:
    • username
    • email
    • group list as multi-valued member
  • Optional security:
    • Zabbix signs AuthnRequests / Logout requests
    • Keycloak requires client signatures

Prerequisites

  • Zabbix 7.4 web frontend: https://zabbix.maksonlee.com
Install Zabbix on Ubuntu 24.04

  • Keycloak realm: maksonlee.com at https://keycloak.maksonlee.com
Install Keycloak with MariaDB and NGINX Reverse Proxy (SSL Termination)
  • Admin access to both
  • Shell access to the Zabbix server

Default SAML certificate paths (Zabbix frontend)

Unless overridden in ui/conf/zabbix.conf.php, Zabbix reads SAML material from:

  • ui/conf/certs/sp.key — SP private key (used when Zabbix signs AuthnRequest / Logout)
  • ui/conf/certs/sp.crt — SP certificate (public; import into Keycloak if you require client signatures)
  • ui/conf/certs/idp.crt — IdP certificate (Keycloak realm signing cert used to verify assertions)

On Ubuntu/Debian, that resolves to:

  • /usr/share/zabbix/ui/conf/certs/
  1. Keycloak — create the SAML client

Clients → Create client

Settings:

  • Name ID format: transient
  • Sign Assertions: On
  • Force POST binding: Off

Advanced:

  • Logout Service Redirect Binding URL: https://zabbix.maksonlee.com/index_sso.php?sls
  1. Keycloak — add mappers via a dedicated client scope

Clients → zabbix → Client scopes

  • Create a scope (e.g. zabbix-dedicated) and assign it as Default to the zabbix client.
  • Inside that scope: Mappers → Add mapper — add these:
    • username
      • Mapper type: User Property
      • User Property: username
      • SAML Attribute Name: username
      • Include in assertions: On
    • email
      • Mapper type: User Property
      • User Property: email
      • SAML Attribute Name: email
      • Include in assertions: On
    • groups
      • Name: groups
      • Mapper type: Group list
      • Group attribute name: member

Client scopes → role_list → Mappers → role list

  • Single Role Attribute: On
  1. Zabbix — install the IdP signing certificate

Zabbix should verify Keycloak’s signed assertions with the realm’s signing cert.

  • In Keycloak: Realm settings → Keys → Active → (RS256) → copy the Certificate (X.509 public).
  • On the Zabbix host:
sudo tee /usr/share/zabbix/ui/conf/certs/idp.crt >/dev/null <<'CRT'
-----BEGIN CERTIFICATE-----
# paste Keycloak realm signing certificate here
-----END CERTIFICATE-----
CRT
sudo chown -R www-data:www-data /usr/share/zabbix/ui/conf/certs
sudo chmod 644 /usr/share/zabbix/ui/conf/certs/idp.crt
  1. Zabbix — configure SAML

In Administration → Users → Authentication (top tab), set a Deprovisioned users group when JIT is enabled.

  1. Sign Zabbix AuthnRequests
  • Create the SP keypair at the default locations:
sudo openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /usr/share/zabbix/ui/conf/certs/sp.key \
  -out   /usr/share/zabbix/ui/conf/certs/sp.crt \
  -days 3650 -subj "/CN=zabbix.maksonlee.com"

sudo chown www-data:www-data /usr/share/zabbix/ui/conf/certs/sp.key /usr/share/zabbix/ui/conf/certs/sp.crt
sudo chmod 640 /usr/share/zabbix/ui/conf/certs/sp.key
sudo chmod 644 /usr/share/zabbix/ui/conf/certs/sp.crt
  • Keycloak → Clients → zabbix → Keys / Certificate: Import sp.crt
  1. Test SSO
  • Log out of Zabbix
  • Visit https://zabbix.maksonlee.com
  • Click Sign in with Single Sign-On (SAML)
  • Authenticate at https://keycloak.maksonlee.com
  • On first login:
    • Zabbix auto-creates the user
    • assigns User role
    • assigns default groups + mapped groups (if enabled)
  • On later logins:
    • the same Zabbix account is reused
    • JIT does not “reset” an existing user

Did this guide save you time?

Support this site

4 thoughts on “Zabbix 7.4 + Keycloak (SAML 2.0): End-to-End Setup with JIT Provisioning”

  1. Other

    Nice tutorial, thank you very much. I have one question, if I want to use keycloak to make calls to zabbix API, is this possible. Best regards.

    Reply
    1. Makson Lee

      If you want Keycloak itself to trigger Zabbix API calls (for example, right after a user logs in to Zabbix), you’d need to write a Keycloak Event Listener SPI that listens for LOGIN events and then calls the Zabbix API in the background

      Reply
  2. Christos Roustemi

    Hello there,

    Very nice documentation. Almost works fro my setup.
    I am struggling with Step5 though.

    Did you upload the sp.crt file to both “Signing keys config” and “Encryption keys config” in the Keys tab of the Client configuration?
    Would mind adding the complete screenshots of the Client configuration?

    Thanks in advance,
    Chris

    P.S Again very nice and well documented process

    Reply
    1. Makson Lee

      Thanks! You only import sp.crt under Keys → Signing keys config when Client signature required = ON. You don’t put it in Encryption keys config unless you also enable Encrypt assertions (which I keep OFF). I’ve added the screenshot of the Keys tab to the post.

      Reply

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top