SSO

The standard deployment uses the gateway's own password sign-in, with accounts managed on the Users page. Organizations with an IdP use docker-compose.sso.yml instead: the IdP manages the accounts, the gateway stores no passwords, and each person gets a role from their IdP groups. SSO is an Enterprise feature and is included in the trial license.

The chain is browser → Caddy (TLS) → oauth2-proxy → gateway → Zabbix. oauth2-proxy is an OIDC reverse proxy: it redirects unauthenticated requests to the IdP and, after sign-in, passes the identity to the gateway in request headers. The gateway trusts those headers only when three things hold: the license includes SSO; the request carries the RST_GATEWAY_SHARED_SECRET that Caddy injects; and the request comes from an address in RST_TRUSTED_PROXIES. Any front proxy that can inject identity headers can replace oauth2-proxy, which is how SAML or LDAP can be connected.

If the license does not include SSO (no Enterprise license, or it lapsed), the gateway ignores the identity headers and falls back to the product's own username and password sign-in: users sign in with a gateway account after passing oauth2-proxy. So set RST_ADMIN_PASSWORD_HASH in .env on an SSO deployment too; without it admin keeps the factory password and can only sign in on the gateway host itself.

SSO only decides who can sign in to the gateway. The gateway still reads and writes Zabbix with the same API token. On the Zabbix side, acknowledgements, maintenance windows and script runs started from the gateway are recorded under that Zabbix account; the person who did it is recorded in the gateway's Audit log.

Connect your IdP

Prerequisites

• An Enterprise or trial license.
• The oauth2-proxy image quay.io/oauth2-proxy/oauth2-proxy:v7.7.1 on the host. The archive does not include it: on a connected host run docker pull; for an air-gapped host, docker pull and docker save on a connected machine, copy the file over and docker load it.
• The images from the archive are loaded and state/machine-id exists, as described in Installing from the archive. deploy.sh does not configure SSO, so the steps below are manual.

Steps

1. Register a confidential client in the IdP with the redirect URI https://<hostname>/oauth2/callback. Note the client id, the client secret and the issuer URL.

2. In .env in the install directory, set:

   OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant>/v2.0
   OIDC_CLIENT_ID=<client id>
   OIDC_CLIENT_SECRET=<client secret>
   OAUTH2_PROXY_SKIP_OIDC_DISCOVERY=false
   OAUTH2_PROXY_COOKIE_SECRET=<output of openssl rand -base64 32>
   OAUTH2_PROXY_REDIRECT_URL=https://<hostname>/oauth2/callback
   OAUTH2_PROXY_COOKIE_SECURE=true
   OAUTH2_PROXY_REVERSE_PROXY=true
   RST_RBAC_ADMIN_GROUPS=noc-admins

   CADDY_SITE_ADDRESS, RST_GATEWAY_SHARED_SECRET, ZABBIX_URL, ZABBIX_TOKEN, LLM_API_KEY and LLM_MODEL are the same as in the standard deployment.

3. Start the SSO deployment:

   docker compose -f docker-compose.prod.yml down
   docker compose -f docker-compose.sso.yml up -d

   Do not add --profile bundled-idp; that profile is for the demo only. Do not add --build; the archive has no Dockerfile.

4. Open https://<hostname>/v2/, check that you are sent to the IdP sign-in page, and that your user appears in the top-right corner after sign-in.

OAUTH2_PROXY_SKIP_OIDC_DISCOVERY must be false. The compose default true and its default endpoints only fit the demo Keycloak.

docker-compose.sso.yml also publishes oauth2-proxy's port 4180 on host port 18180 (plain HTTP, for the demo). In production, keep 18180 closed in the firewall; users come in through 443 only.

Role mapping

The IdP's groups claim travels with the identity, and the gateway maps it to product roles as below. A user in several mapped groups gets the first match in the order administrator, analyst, auditor, viewer. A user in no mapped group is treated as a viewer, read-only.

See Users for what each role may do.

Settings

Active Directory and SAML

For users who sign in with AD or LDAP domain accounts, set up user federation in Keycloak: Keycloak checks the account with an LDAP bind at sign-in and hands an OIDC identity to oauth2-proxy. The key fields for Microsoft AD are vendor=ad, connectionUrl=ldaps://dc.corp.local:636, usernameLDAPAttribute=sAMAccountName, rdnLDAPAttribute=cn, uuidLDAPAttribute=objectGUID, userObjectClasses=person, organizationalPerson, user, and a service account as bindDn. Add a group-ldap-mapper that maps AD security groups to the groups claim for role mapping.

With an existing SAML 2.0 IdP such as ADFS, add a SAML v2.0 provider under Identity Providers in Keycloak and import the IdP's metadata. In production, turn on signature validation and import the IdP's signing certificate. Keycloak validates the assertion and hands an OIDC identity to oauth2-proxy; the rest of the chain is unchanged.

Demo environment

The bundled-idp profile of docker-compose.sso.yml includes Keycloak and OpenLDAP for demos only; open http://localhost:18180/. The test accounts are analyst / analyst123 (a Keycloak local account), analyst.ldap / Ldap123! (LDAP federation) and saml.user / Saml123! (SAML brokering). The client secret, redirectUris: ["*"] and sslRequired: none there are demo values; switch to your own IdP before production.

What changes after sign-in

• The audit event's user field comes from the SSO identity, and its role field records the role.
• The current user appears in the top-right corner; signing out goes through /oauth2/sign_out.
• Passwords are managed by the IdP; the gateway offers no password change.
• Rate limits count per user instead of per source IP.