SSO

By default the gateway uses its own password login, with accounts managed on the Users page. If you have an IdP, switch to docker-compose.sso.yml: accounts come from the IdP and the gateway stores no passwords. The two modes are exclusive, and RST_USER_DB_URL has no effect once SSO is on.

SSO is an Enterprise feature. If the activated license does not include it, the gateway ignores the SSO settings, falls back to its own login, and logs sso_oidc_not_entitled.

Identity chain

oauth2-proxy is an OIDC reverse proxy. It redirects unauthenticated requests to the IdP and, after login, passes the verified identity to the gateway in request headers. The gateway has no login of its own and trusts only those headers.

That trust rests on two conditions. The gateway is reachable only inside the proxy chain, because every /api/* request must carry RST_GATEWAY_SHARED_SECRET. oauth2-proxy overwrites the identity headers from its own session, so a client cannot forge them.

The chain does not depend on the protocol. Any front proxy that injects identity headers can replace oauth2-proxy, which is how SAML and LDAP are supported.

Connect an IdP

Prerequisites

• An Enterprise license.
• An IdP that supports OIDC.

Steps

1. In the IdP, register a confidential client with the callback URI https://<hostname>/oauth2/callback. Note the client ID, client secret and issuer URL.

2. Set the IdP and proxy values in .env:

   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=<openssl rand -base64 32>
   OAUTH2_PROXY_REDIRECT_URL=https://<hostname>/oauth2/callback
   OAUTH2_PROXY_COOKIE_SECURE=true
   OAUTH2_PROXY_REVERSE_PROXY=true
   CADDY_SITE_ADDRESS=<hostname>
   RST_GATEWAY_SHARED_SECRET=<openssl rand -hex 32>
   RST_SSO_ENABLED=true
   RST_SSO_ENFORCE=true

3. Map IdP groups to roles in .env:

   RST_RBAC_ADMIN_GROUPS=soc-admins
   RST_RBAC_ANALYST_GROUPS=soc-l1,soc-l2
   RST_RBAC_VIEWER_GROUPS=auditors

4. Run sudo ./deploy.sh and choose authentication mode 2, or run docker compose -f docker-compose.sso.yml up -d.

Opening https://<hostname> now redirects to the IdP. After sign-in, the current user appears in the top right.

The IdP's groups claim travels with the identity. A user in several groups gets the highest role. A user in no mapped group has no role and can write but not administer. To make a group read-only, list it in RST_RBAC_VIEWER_GROUPS.

Connect an AD domain

For AD or LDAP accounts, configure user federation in Keycloak. Keycloak binds to the directory at login and issues OIDC to oauth2-proxy.

Key settings for Microsoft AD, with a service account as bindDn:

vendor=ad
connectionUrl=ldaps://dc.corp.local:636
usernameLDAPAttribute=sAMAccountName
uuidLDAPAttribute=objectGUID
userObjectClasses=person, organizationalPerson, user

Add a group-ldap-mapper to map AD security groups into the groups claim for role mapping.

The --profile bundled-idp in docker-compose.sso.yml (Keycloak and OpenLDAP) is a test environment. Do not use it in production.

Accounts under SSO

• Audit events record the SSO identity in user.
• Sign-out goes through /oauth2/sign_out.
• The Account page offers no password change; the IdP manages passwords.

Variables