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 when no provisioning rule matches them (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. The role and location scope come from your provisioning rules if one matches; if none matches (or you have written none), the account falls back to the workspace’s default SSO role from step 3 with no location assignments, and someone will need to add locations afterward.
• 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 rules

By default every user created on first SSO login lands on one role — the workspace default — with no locations. Provisioning rules replace that with a mapping from what your identity provider sends to the role and location scope a person should get, applied at the moment they first sign in. An admin with the Configure Single Sign On (SSO) permission manages them in Settings → Single Sign-On. Like the rest of SSO configuration, they are web-app only — there is no public API for creating or editing them.

​

How a rule is shaped

Each rule is a set of conditions on assertion attributes, plus the role and location to assign:

When department is Engineering → assign Full User, scoped to Lake City

Conditions combine with All (AND) or Any (OR) and compare case-insensitively using is, is not, contains, does not contain, or starts with.

​

How rules are evaluated

• In priority order, top to bottom — the first match wins. Someone matching two rules gets the higher one’s role, not both.
• Paused rules are skipped. Only active rules are considered.
• No match falls back to the default SSO role from setup step 3, with no location scope. This is also exactly what happens when a workspace has written no rules at all, so enabling rules changes nothing for existing SSO workspaces until a rule is actually added.
• A matched location is expanded to its leaf locations. Scoping a rule to a district grants the stores beneath it, because membership is stored flat and several read paths match a location literally rather than walking the hierarchy.

​

Filling in people who were provisioned before

Users created by the older behaviour — an account with a role but no locations at all — are repaired on their next SSO sign-in: if a rule now covers them, Xenia fills in the missing location scope then. This only applies to members holding zero location memberships. Someone whose scope was deliberately narrowed to a single site is never widened by a rule, and roles of existing members are never changed by a sign-in.

​

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

• Rules read the sign-in assertion, not your whole directory. Provisioning rules can only match on attributes your IdP actually includes in the SAML/OIDC assertion. If your IdP sends identity claims only, no rule can sort people by department or site — ask your IdP administrator to add the claim, or use Directory Sync, which reads the full directory record (groups, department, manager, site) rather than one assertion.
• 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