OIDC

OpenID Connect (OIDC) / SSO

Vantyr can delegate dashboard login to an external OpenID Connect provider (Authentik, Keycloak, Authelia, Okta, Entra ID, Google, etc.) using the Authorization Code flow. When OIDC is configured, the login screen offers an SSO option alongside local username/password login - the two coexist.

See also Security, Configuration, Environment-template, and Deployment.

---

Environment variables

Set these on the vantyr-server process/container.

Note: OIDC settings are read from the plain OIDC_* environment variables only. Unlike most server secrets, the OIDC loader does not consult OIDC_*_FILE (Docker-secret) variants - supply OIDC_CLIENT_SECRET directly (e.g. via your orchestrator's secret-injection into the environment).

Variable	Example	Required	Description
OIDC_ISSUER_URL	https://auth.example.com/application/o/vantyr/	✅	Issuer URL used for OIDC discovery (must equal the provider's iss).
OIDC_CLIENT_ID	vantyr-dashboard	✅	Client ID registered with the provider.
OIDC_CLIENT_SECRET	...	✅	Client secret registered with the provider. Plain env only (no _FILE).
OIDC_REDIRECT_URL	https://monitor.example.com/api/auth/oidc/callback	✅	Exact redirect/callback URL to register with the provider - must match byte-for-byte.
OIDC_SCOPES	openid profile email	❌	Space-separated scopes. Default: openid profile email.
OIDC_ADMIN_GROUP	VantyrAdmins	❌	If the token's groups claim contains this value, the user is provisioned as admin.
OIDC_OPERATOR_GROUP	VantyrOperators	❌	If groups contains this value (and not the admin group), the user is provisioned as operator.
OIDC_ALLOWED_GROUPS	VantyrUsers,Contractors	❌	Provisioning allowlist. When non-empty, a first-time login is only created if the token's groups intersect this set. Empty = open provisioning.

OIDC is considered enabled only when OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_REDIRECT_URL are all set and non-empty.

---

Group → role mapping

Vantyr reads a groups claim (a JSON array of strings) from the validated ID token and maps it to a dashboard role:

Token groups contain…	Resulting role
OIDC_ADMIN_GROUP	admin
OIDC_OPERATOR_GROUP (and not admin)	operator
neither	viewer

• Matching is exact string comparison; admin takes precedence over operator.
• If your provider exposes groups under a different claim name, configure a mapper so the ID token includes a claim literally named groups.
• See Security for what each role can do (viewers cannot remote-control endpoints).

Provisioning allowlist (OIDC_ALLOWED_GROUPS)

This gates who is allowed to get a dashboard account at all, separately from role mapping:

• Empty (default): open provisioning - any successful IdP login creates a local user. The server logs a startup warning in this mode.
• Non-empty: a first-time login is only provisioned when the token's groups intersect the allowlist. Otherwise the callback returns 403 and writes an oidc_provisioning_denied audit event.
• The allowlist only governs first-time provisioning. Existing users are not re-checked against it on subsequent logins.

Recommended: always set OIDC_ALLOWED_GROUPS in production so a valid IdP account in an unrelated group can't silently create a Vantyr user.

---

Endpoints & callback flow

Route	Purpose
GET /api/auth/oidc/login	Redirects to the provider's authorization endpoint; sets short-lived oidc_state, oidc_nonce, and oidc_return_to cookies (HttpOnly, 10-min).
GET /api/auth/oidc/callback	The redirect/callback URL. Validates state + nonce, exchanges the code for tokens, validates the ID token, applies the allowlist, provisions/looks up the user, and issues a dashboard session cookie.
GET /api/auth/config	Tells the SPA whether OIDC and/or local login are enabled.

Hardening notes:

• The discovery/token HTTP client disables redirects (SSRF hardening).
• The callback validates both state and nonce; return_to is sanitized to reject open redirects (only same-site relative paths).
• The session cookie issued after SSO uses the same HttpOnly / Secure / SameSite rules as local login - see Security.

OIDC_REDIRECT_URL must exactly equal the callback path, e.g. https://<your-host>/api/auth/oidc/callback, and be registered verbatim in the provider.

---

How local and SSO login coexist

• Local username/password login remains available even when OIDC is enabled; the login screen shows both options.
• An OIDC-provisioned user gets a random local password at creation, so local password login is effectively disabled for that account unless an admin resets it.
• Roles are assigned from groups on first provision only. Vantyr does not overwrite roles on every login - admins can manage roles in-app afterward without the IdP forcing them back.
• Identity is keyed on (issuer, subject); the user's preferred_username, email, and name claims are recorded/updated.

---

Example provider config (Authentik)

1. Create an OAuth2/OpenID Provider, Authorization Code flow.
2. Set the redirect URI to exactly: https://monitor.example.com/api/auth/oidc/callback
3. Note the client ID and client secret.
4. Ensure the ID token includes a groups claim (array of group names) - add a scope/property mapper if needed.
5. Configure Vantyr:

OIDC_ISSUER_URL=https://auth.example.com/application/o/vantyr/
OIDC_CLIENT_ID=vantyr-dashboard
OIDC_CLIENT_SECRET=<secret>
OIDC_REDIRECT_URL=https://monitor.example.com/api/auth/oidc/callback
OIDC_SCOPES=openid profile email
OIDC_ADMIN_GROUP=VantyrAdmins
OIDC_OPERATOR_GROUP=VantyrOperators
OIDC_ALLOWED_GROUPS=VantyrUsers,VantyrAdmins,VantyrOperators

The same shape works for Keycloak, Authelia, Okta, Entra ID, etc. - adjust the issuer URL and make sure a groups claim is present in the ID token.

---

Reverse proxy / HTTPS

OIDC login and the resulting session cookies depend on HTTPS detection:

• HTTPS is enforced by default (ENFORCE_HTTPS=true).
• Behind a reverse proxy, forward X-Forwarded-Proto: https (and wss for WebSocket upgrades) so cookies are marked Secure. Wrong proxy headers will break login.
• For local plain-HTTP testing, set ENFORCE_HTTPS=false and use an OIDC_REDIRECT_URL your provider permits for non-TLS dev.

See Security for the full TLS, cookie, and trusted-proxy details.