Single Sign-On (SSO)

​

Overview

Xenia’s Single Sign-On is built on WorkOS, which abstracts the IdP protocol — Xenia never talks SAML or OIDC directly. Any IdP WorkOS supports (Okta, Azure AD / Microsoft Entra ID, Google Workspace, OneLogin, and others) works the same way from Xenia’s side.

​

Setting up SSO

An admin with the Configure Single Sign On (SSO) permission configures SSO in Settings → Single Sign-On, in order:

1. Verify Domain — click through to a hosted verification page. You’ll be shown a DNS record to add to your domain (the exact record type is determined by WorkOS’s hosted verification flow). Xenia is notified automatically once your DNS provider propagates it; there’s no “check again” step to run yourself.
2. Configure SSO — connect your identity provider (this step is where you do the actual SAML/OIDC setup on the IdP side, guided by the hosted portal). Disabled until your domain is verified.
3. Set Default Role — pick the role that brand-new users get the first time they sign in via SSO (see just-in-time provisioning below). You can change any individual user’s role afterward — this only sets the starting role for people Xenia has never seen before.

Once all three steps are complete, an Enable SSO switch on the same page turns SSO on for the workspace. It won’t turn on until your domain is verified, your IdP connection is configured, and a default role is selected. Once enabled, a second toggle controls whether users can still sign in with email/password alongside SSO, or must use SSO exclusively (see Login method visibility).

​

How SSO login works

1. A user goes to the sign-in page and enters their email.
2. Xenia looks up the email’s domain against workspaces with that domain verified for SSO (first match wins, if more than one workspace has ever verified the same domain).
3. If found and SSO is enabled for that workspace, the user is shown a “Log in with SSO” link to their identity provider — alongside the password form if password login is also allowed, or as the only option if it isn’t. Either way, the user clicks through; Xenia never auto-redirects them.
4. The user authenticates with their IdP as usual (including any MFA their IdP enforces — Xenia has no visibility into or control over the IdP’s own auth policy).
5. The IdP redirects back through WorkOS to Xenia, which exchanges a one-time authorization code for the user’s verified profile (email, name) and completes the sign-in.

​

Mobile apps

SSO on the Xenia mobile app opens in a system-browser-based sign-in sheet (Safari on iOS, Chrome on Android) rather than an embedded in-app browser — this is required by some identity providers’ security policies. After authenticating, the browser hands control back to the Xenia app automatically; no code or link needs to be copied manually.

​

Just-in-time provisioning

The first time someone signs in via SSO, Xenia checks whether a Xenia account already exists for their email — and if it does, whether that account has a membership in this workspace:

• No Xenia account exists anywhere for that email — Xenia automatically creates one, assigned to the workspace’s default SSO role (set in step 3 above). This new account has no location assignments — someone will need to add locations afterward, either in the web app or via the API.
• A Xenia account already exists with a membership in this workspace (created earlier via the web app, the Provision Users API, or an HRIS sync) — Xenia logs them into that membership as-is. If it was sitting in a Pending state (for example, pre-created by an HRIS sync with a role and locations already assigned), signing in via SSO activates it — the pre-assigned role and locations are left untouched.
• A Xenia account already exists, but with no membership in this workspace (most commonly: they already have an account in a different Xenia workspace) — signing in does not fail, but it also does not grant them access to this workspace. They’re simply logged into whichever other workspace(s) their account already belongs to. If someone reports “I signed in with SSO but I don’t see this workspace,” this is almost always why — see Provisioning users for SSO below to fix it.
• Automatic creation can be turned off. If your workspace requires every user to be provisioned in advance, contact Xenia support to disable just-in-time provisioning for your workspace — there’s no self-service toggle for this yet. Once it’s off, anyone without a pre-existing (or pre-provisioned) account is rejected at sign-in with “No Xenia account found for this identity. Contact your workspace admin.”
• New SSO sign-ins are still subject to your plan’s user-seat limit. If a first-time SSO sign-in would exceed your workspace’s seat count, account creation (or provisioning via the API) fails rather than silently exceeding the limit — free up or add a seat first.

​

Provisioning users for SSO

To avoid new SSO users landing with no location access — or landing in the wrong workspace entirely if they already have a Xenia account elsewhere — provision them ahead of time with the Provision Users API — pass their email, the role you want them to start with, and their location assignments. Need role_id/location_ids values first? See Get Roles and Get Locations. When they later sign in via SSO for the first time, Xenia matches them by email and logs them into the membership you already set up in this workspace, instead of creating a bare account with only the default role (or leaving them without access to this workspace at all).

​

Multiple domains

A single SSO connection can serve more than one verified email domain — useful if your organization sends mail from more than one domain but wants everyone routed through the same identity provider. Verify each additional domain the same way as the first (Settings → Single Sign-On → Add More Domains); they all attach to your existing IdP connection, so there’s no separate IdP setup per domain.

​

Login method visibility

What a user sees on the sign-in page depends on two settings:

• Is SSO enabled at all for their workspace (the master toggle from setup, above).
• Is password login also allowed alongside it — the “Show password login on sign-in screen” toggle. This setting only has an effect while SSO is enabled; if SSO is off, this toggle has no effect (a user still needs a password set to use password login — see the passwordSetupRequired case below). Turning it off while SSO is on hides both password and phone-number login (and the server rejects either if attempted directly) — but it does not disable every other way in: magic-link sign-in and kiosk-mode PIN login are unaffected, so SSO is not literally the only way into the workspace, just the only password-based one.

​

Deactivation and offboarding

Deactivating a user (in the web app, or via the Deactivate User or Set User Status API) works the same regardless of whether they sign in via SSO or password. A couple of things worth knowing:

• Revocation takes effect on the user’s next request, not on a delay — deactivating a user immediately invalidates their server-side session cache, so the very next request they make is denied.
• Disabling a user on your identity provider only blocks future SSO sign-ins. It does not force-end a session that’s already active in Xenia. If you need someone’s access removed immediately, deactivate them directly in Xenia rather than relying on the IdP side alone.

​

Known limitations

• No SCIM support. Sync users via the Provision Users API or an HRIS integration, not a SCIM connector.
• No attribute- or group-based role mapping. Every user Xenia creates automatically on first SSO login gets the same default role, regardless of their IdP groups or attributes. If different users need different roles, provision them ahead of time via the API with the role you want.
• No webhooks. The Xenia API doesn’t currently offer outbound webhooks — to react to a new user being created by SSO, poll the Get Users API.
• No self-service domain reset. If an already-verified SSO domain needs to be cleared or changed, contact Xenia support.

​

Troubleshooting

​

Next Steps