> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On (SSO)

> How Xenia SSO works — setup, login flow, and just-in-time user provisioning

## Overview

Xenia's Single Sign-On is built on [WorkOS](https://workos.com), 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.

<Note>
  SSO is a paid add-on. If it isn't enabled on your plan, every SSO management action in the web app
  returns an upgrade prompt, and the API-level equivalent is a `403` with
  `Workspace doesn't have "SSO" feature activated.`
</Note>

<Warning>
  SSO **setup and configuration** (connecting an IdP, verifying a domain, choosing the default role) is
  done entirely through the Xenia web app — **Settings → Single Sign-On**. There is currently no public
  API for configuring SSO. Once SSO is enabled, the [Provision Users API](/api-reference/endpoints/users/provision-users)
  and the standard login flow work with it automatically — see [Provisioning users for SSO](#provisioning-users-for-sso) below.
</Warning>

## 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](#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](#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.

<Note>
  Each SSO sign-in requests fresh IdP authentication rather than silently reusing an existing IdP session —
  so a user who is already logged into their IdP in the browser still confirms that session before
  landing in Xenia. (Whether the IdP actually honors this is ultimately up to the IdP.)
</Note>

### 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](/api-reference/endpoints/users/provision-users), 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](#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](/api-reference/endpoints/users/provision-users) — 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](/api-reference/endpoints/roles/get) and [Get Locations](/api-reference/endpoints/locations/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.

<Warning>
  This is separate from what happens when a workspace **turns SSO off**: if a user's account was SSO-only
  and they never set a password, they are **not** locked out — they're routed to a self-service "set your
  password" flow instead.
</Warning>

## Deactivation and offboarding

Deactivating a user (in the web app, or via the [Deactivate User](/guides/workflows/user-lifecycle#deactivate-user)
or [Set User Status](/guides/workflows/user-lifecycle#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](/api-reference/endpoints/users/provision-users)
  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-reference/endpoints/users/get-users) API.
* **No self-service domain reset.** If an already-verified SSO domain needs to be cleared or changed,
  contact Xenia support.

## Troubleshooting

| You see                                                                                              | What it means                                                                              | What to do                                                                                               |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| "No Xenia account found for this identity. Contact your workspace admin."                            | Just-in-time provisioning is off and no account exists for that email yet                  | [Provision the user](/api-reference/endpoints/users/provision-users) first, then have them sign in again |
| "Your identity provider signed you in as X. Sign out of that account, then try again."               | The browser already had a different IdP session active                                     | Fully sign out at the identity provider, close the tab, and retry                                        |
| "Single Sign-On is required for your workspace. Email/password and phone number login are disabled." | The workspace has password/phone login turned off                                          | Use the SSO sign-in link, or magic-link/kiosk PIN if available, rather than password or phone login      |
| `Workspace doesn't have "SSO" feature activated.`                                                    | SSO isn't included on your current plan                                                    | Contact your Xenia representative                                                                        |
| "Please select a role" / "Sso Configuration not configured for this workspace"                       | Setup is incomplete — no default role chosen, or the domain/IdP step isn't finished        | Finish all setup steps in **Settings → Single Sign-On** before enabling                                  |
| Sign-in bounces back to the sign-in page with no error shown                                         | The web app redirects to `/sign-in` on any SSO exchange failure without surfacing a reason | Contact Xenia support with the email and approximate time so we can check the server-side error          |
| New user can't sign in via SSO even though JIT provisioning is on                                    | The workspace's user-seat limit has been reached                                           | Free up or add a seat, then have them try again                                                          |

## Next Steps

<CardGroup cols={2}>
  <Card title="Provision Users API" icon="user-plus" href="/api-reference/endpoints/users/provision-users">
    Pre-create SSO users with the role and locations you want
  </Card>

  <Card title="User Lifecycle guide" icon="users" href="/guides/workflows/user-lifecycle">
    Manage users, roles, and status via the API
  </Card>
</CardGroup>