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.

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

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 SSO accounts; enforce MFA in Entra/Keycloak where it belongs.
  • 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). 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 whose Vesana username matches the IdP username can sign in (existing local accounts are linked automatically on their first SSO login).
  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. 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).
  • Deleting a provider switches all linked users 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).