Skip to content

Single Sign-On (OIDC)

Users sign in through your organization's identity provider (IdP) instead of a Vesana password. Any OpenID Connect capable IdP works — e.g. Microsoft Entra ID, Keycloak, Authentik, Google Workspace, Okta.

Preview feature — off by default

SSO is a preview feature: on a fresh instance it is switched off, the admin tab does not appear and the sign-in page shows no SSO buttons. Enable it under Admin → System → Preview features (super admins only). If you had a provider configured before the update, SSO stays enabled — including with a disabled provider, so that accounts without a password are not locked out.

SSO is configured under Admin → Login & Security → SSO (super admin).

Company with a Windows domain but no identity provider?

Then connect Active Directory directly: Sign-in with Active Directory (LDAP) — sign in with the domain account through the normal sign-in form, without Keycloak/Entra in between.

How it works

  • The login page shows a "Sign in with …" button per enabled provider. Clicking it takes the user to the IdP; after a successful sign-in they land in Vesana fully logged in (a normal browser session, same as password login).
  • Password login always stays available — an IdP outage or misconfiguration never locks anyone out.
  • MFA is the IdP's job. Vesana's 2FA enforcement rules do not apply to sign-in through the identity provider; enforce MFA in Entra/Keycloak where it belongs. If an SSO account signs in with a password (set by an admin) instead, the local 2FA requirement applies.
  • Under the hood: Authorization Code Flow with PKCE; the ID token is verified against the IdP's signing keys (JWKS).

Setup in 4 steps

  1. Register an application at your IdP (web application, confidential). Use the redirect URI Vesana shows on the provider card (https://<vesana-host>/api/v1/auth/sso/<id>/callback). If the instance runs on an HTTPS port other than 443, the port is part of the URI (https://<vesana-host>:8443/…). When creating the provider for the first time, copy the URI from the card after saving and add it at the IdP.
  2. Create the provider in Vesana: discovery URL (…/.well-known/openid-configuration), client ID and client secret. "Test connection" immediately verifies reachability and signing keys.
  3. Choose user mapping:
  4. Without JIT: only users who already have a Vesana account can sign in. An existing local account is linked on its first SSO login only if Link local accounts is on (Vesana username = IdP username; if the IdP explicitly reports the email address as unverified, nothing is linked). The switch is off for new providers; then a login whose username matches a local account ends with a message, and neither a link nor a second account is created. Turn it on only if the IdP verifies usernames and email addresses: where users choose their own name, someone could otherwise take over another account together with its permissions. Local super admins are never linked; accounts that are already linked keep signing in regardless of the switch.
  5. With JIT provisioning: unknown IdP users are created automatically on first login — with the default role or via group mapping (IdP group → Vesana role, first match wins). JIT users see all tenants; the role controls their permissions.
  6. Teams from provider groups (independent of JIT): IdP group → Vesana team. On every login the user joins the teams of their groups and leaves teams whose group is missing. Team memberships set by hand stay untouched.
  7. Test it: sign in via the SSO button in a private window.

Provider examples

Microsoft Entra ID: App registration → Web → add redirect URI → Certificates & secrets → create a client secret. Discovery URL: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration. For group mapping, enable the groups claim in the app registration (groups arrive as object IDs — put those IDs into the mapping).

Keycloak: create a client (OpenID Connect, client authentication on, standard flow on), set the redirect URI, take the secret from the Credentials tab. Discovery URL: https://<keycloak>/realms/<realm>/.well-known/openid-configuration. For group mapping, add a "Group Membership" mapper (claim groups, full path off) to the client.

Authentik/Authelia/Okta: analogous — create an OIDC provider/app, set the redirect URI, use its discovery URL.

Details & limits

  • The username comes from the preferred_username claim (changeable under "Advanced", e.g. to email).
  • SSO accounts have no local password and carry an SSO badge in user management. An admin can set a password at any time — password login then works in addition (break-glass).
  • Disabling or deleting a provider immediately ends all running Vesana sessions of its users. Deleting also switches them back to local login; without a password set, the account stays locked until an admin password reset.
  • Logging out ends the Vesana session; the IdP session remains (no single logout).