Single sign-on
Connect your identity provider over OIDC and map IdP groups to the admin, operator and viewer roles. Needs an Enterprise license.
Single sign-on needs an Enterprise license. Without SSO, the gateway manages accounts itself; see Users. Use one or the other, never both.
How it fits together
An SSO deployment uses docker-compose.sso.yml: Caddy hands requests to oauth2-proxy, which completes the OIDC sign-in and then forwards to the gateway. The SSO stack also bundles pgvector/pgvector:pg16 and uses the same RST_DB_URL. Keycloak can federate LDAP or AD.
Setup
- Register an OIDC client in your IdP with the callback URL
https://<address>/oauth2/callback. - Run
deploy.sh, choose authentication 2, and enter the issuer, client id and client secret. The script fills in:
| Variable | Meaning |
|---|---|
OIDC_ISSUER_URL | The IdP's issuer URL |
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | The client from step 1 |
OAUTH2_PROXY_REDIRECT_URL | https://<address>/oauth2/callback |
OAUTH2_PROXY_COOKIE_SECRET | Generate with openssl rand -base64 32 |
OAUTH2_PROXY_COOKIE_SECURE | true |
OAUTH2_PROXY_REVERSE_PROXY | true |
OAUTH2_PROXY_SKIP_OIDC_DISCOVERY | false |
Role mapping
Roles come from IdP groups:
RST_RBAC_ADMIN_GROUPS=netops-admins
RST_RBAC_OPERATOR_GROUPS=netops-l1,netops-l2
RST_RBAC_VIEWER_GROUPS=auditorsSomeone in several groups gets the highest of their roles. For what each role can do, see Users.
Every SSO user also accepts the end user license agreement on first sign-in.
--profile bundled-idp in the compose file (Keycloak plus OpenLDAP) is a demo and test fixture only. It listens on 127.0.0.1 only, and KEYCLOAK_ADMIN_PASSWORD must be set in .env before it starts. Do not enable it in production.
Data sources
Preparing Prometheus, Alertmanager, Grafana and snmp_exporter: read-only accounts, label conventions, vendor recognition, the inventory scrape job and rule write-back.
Upgrades, rollback and backups
Upgrading with a new bundle, online updates with automatic rollback, content-pack updates, and backup and restore.