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

# Single sign-on with Microsoft Entra

> Federate your organization's Microsoft Entra tenant so staff sign in to Encore OS with their work account at /settings/security/sso.

Single sign-on (SSO) lets staff sign in to Encore OS with their organization's Microsoft Entra account instead of an Encore password. Org admins enable SSO from `/settings/security/sso`, either by toggling on Microsoft sign-in through the shared Entra app or by federating a bring-your-own SAML IdP. Entra handles multi-factor authentication, and only employees who already have a matching record in your organization can sign in.

## Overview

The SSO settings page (`SsoSettingsPage`) is the entry point for org admins to enable staff sign-in. It offers two paths:

* **Microsoft sign-in (recommended).** A single toggle that lets staff sign in with the shared Entra app you already connected at `/settings/integrations/entra`. Encore uses the verified email domains Microsoft Graph reports for your tenant to route federated logins — no DNS verification or SAML metadata needed. This is the right choice for almost everyone.
* **Advanced: bring your own SAML IdP.** A guided wizard (`SsoSetupWizard`) for organizations that must federate through a SAML 2.0 identity provider other than the shared Entra app. Adds your domain, verifies DNS ownership, and registers SAML metadata.

Once either path is active, users at a verified email domain see a **Sign in with SSO** option on the Encore sign-in page. Users whose domain is not federated continue to use email and password as before.

SSO is distinct from the Entra ID provisioning integration at `/settings/integrations/entra`, which syncs directory, calendar, SharePoint, and Teams data. SSO is the login path; the Entra integration is the machine-to-machine connection.

## Who it's for

* Org admins with the `pf.sso.manage` permission can set up, update, or remove an SSO provider.
* All staff with a work email at a verified domain can sign in with SSO once the provider is active.

## Before you start

* Confirm you have the `pf.sso.manage` permission. Without it, the SSO page shows a permission notice and neither the toggle nor the SAML wizard can be launched.
* Only employees that already exist in your organization's `hr_employees` records can sign in via SSO. Add staff records first.
* **For Microsoft sign-in:** complete [Entra ID guided setup](/pf/entra-id#guided-setup) first so admin consent is granted and verified domains are cached.
* **For the SAML path only:** you need DNS edit access for the email domain you want to federate (to publish a TXT verification record), plus your SAML metadata URL and Entity ID from your IdP.

## Enable Microsoft sign-in (recommended)

Use this path when the same Entra tenant that powers provisioning should also power staff login.

<Steps>
  <Step title="Connect Entra ID first">
    Run [Entra ID guided setup](/pf/entra-id#guided-setup) at `/settings/integrations/entra`. The integration must be **Connected** (green health badge) before the SSO toggle becomes available.
  </Step>

  <Step title="Open the SSO settings page">
    Navigate to `/settings/security/sso`. The **Microsoft sign-in (recommended)** section lists the verified domains Encore has cached from Microsoft Graph.
  </Step>

  <Step title="Verify domains (if prompted)">
    If no verified domains are cached yet, select **Verify domains now**. Encore acquires a Graph token for your tenant and caches the verified-domain list from Microsoft. Repeat this any time you add or remove a domain in Entra.
  </Step>

  <Step title="Toggle Microsoft sign-in on">
    Flip **Staff sign in with Microsoft**. The toggle only becomes interactive once the tenant is connected and at least one verified domain is cached.
  </Step>

  <Step title="Test sign-in">
    From an incognito window, select **Sign in with SSO** and enter a work email at a verified domain. You should be routed to Microsoft, complete MFA there, and return signed in.
  </Step>
</Steps>

<Warning>
  If the Microsoft sign-in toggle is on but no verified domains are cached, the SSO settings page surfaces a destructive **Microsoft sign-in is on but not routable** alert. The login page will not offer Microsoft sign-in until you run **Verify domains now**. This usually means admin consent has lapsed or your Entra app no longer has Graph access.
</Warning>

### Supabase Azure provider checklist

The shared Entra app must be configured on Supabase Auth's Azure provider for user sign-in to work. The SSO settings page includes a collapsible **Supabase Azure provider checklist** with the same items:

| Item                                | Where                                                                                                                                                                        |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Redirect URI registered             | Supabase Dashboard → **Authentication → Providers → Azure** and on the Entra app's **Authentication → Redirect URIs**: `https://<project-ref>.supabase.co/auth/v1/callback`. |
| Optional claims in the app manifest | `xms_edov` and `email` on both `idToken` and `accessToken`. Required for the OIDC verified-email gate (`pf_sso_match_current_user` rejects identities without `xms_edov`).   |
| Delegated scopes admin-consented    | `openid`, `profile`, `email` on the Entra app. Application permissions alone (client-credentials) do **not** cover user OAuth sign-in.                                       |

If Encore platform operators manage the shared Entra app for you, these are already in place — you only need to grant tenant-wide consent during Entra setup.

### Failed-sign-in audit markers

Failed OIDC sign-ins are written to the PF-04 audit log with no detail surfaced to the user. Operators can search the audit log for these actions:

| Audit action                | Cause                                                                            |
| --------------------------- | -------------------------------------------------------------------------------- |
| `pf.sso.tid_mismatch`       | The Microsoft token's tenant doesn't match the org's `entra_tenant_id`.          |
| `pf.sso.xms_edov_missing`   | The `xms_edov` claim is absent — the optional-claims manifest is not configured. |
| `pf.sso.employee_not_found` | No matching `hr_employees` row for the signing-in email.                         |

## Advanced: SAML SSO (bring your own IdP)

Use this path only if you need to federate through a non-shared SAML IdP — for example, a strict tenant-isolation policy or a non-Entra identity provider.

<Steps>
  <Step title="Open the SAML wizard">
    Navigate to `/settings/security/sso` and select **Set up SAML SSO** under the **Advanced** section. The `SsoSetupWizard` opens.
  </Step>

  <Step title="Add your domain">
    On **Add Domain**, enter the email domain your staff use (for example, `acme.com`). The wizard creates a pending `pf_sso_domain_claims` row and a draft `pf_org_sso_providers` row, then issues a DNS TXT verification token.
  </Step>

  <Step title="Verify ownership">
    On **Verify Ownership**, copy the TXT host and value and publish them in your DNS. Select **Verify now** to call `sso-domain-verify`. The wizard polls the claim status; it will not advance until the claim flips to `verified`.
  </Step>

  <Step title="Paste IdP metadata">
    On **IdP Metadata**, paste the Entra SAML **metadata URL** and **Entity ID** from your Enterprise Application. The wizard calls `sso-provider-update` to attach the metadata to the draft provider.
  </Step>

  <Step title="Review and activate">
    On **Review & Activate**, confirm the domain, metadata URL, and entity ID. Select **Activate** to call `sso-provider-register`, which registers the SAML provider with Supabase and sets its status to `active`. The wizard then emits a PF-04 audit event. Run a test sign-in from an incognito window to confirm the round-trip.
  </Step>
</Steps>

## Sign in with SSO

Once a provider is active, federated users sign in from the standard Encore sign-in screen:

1. On the sign-in page, select **Sign in with SSO**.
2. Enter your work email. The client derives the domain and calls `supabase.auth.signInWithSSO({ domain })`.
3. You are redirected to your organization's Entra login, complete MFA there, and return to Encore authenticated.
4. A PF-49 session record is created. The Encore MFA challenge (PF-79) is skipped because the IdP has already asserted MFA.

If the email domain is not federated, the page falls back to email and password without error.

## Key concepts

<AccordionGroup>
  <Accordion title="Domain ownership verification">
    Before SSO activates, you must prove you own the email domain by publishing a DNS TXT record containing the wizard-issued `verification_token`. This prevents another tenant from registering your domain and hijacking sign-ins. A domain claim must be in the `verified` state before its provider can be activated.
  </Accordion>

  <Accordion title="Known-employees-only sign-in">
    SSO sign-in is restricted to people who already exist in your organization. When a federated identity returns from Entra, the platform matches the SAML `email` claim against `hr_employees` for the resolved org. If no employee matches, sign-in is blocked, no auth user is created, and the user sees a clear error. Add staff records (or use the Entra ID directory sync at `/settings/integrations/entra`) before inviting users to sign in.
  </Accordion>

  <Accordion title="MFA delegation">
    When SSO is used, multi-factor authentication is enforced by Entra rather than by Encore. The Encore MFA challenge is skipped on successful federated sign-in. Configure Conditional Access and MFA policies in Entra to match your security requirements.
  </Accordion>

  <Accordion title="One active provider per domain">
    A domain string can map to at most one active SSO provider across the platform. Re-adding a domain that is already verified to another provider is rejected. To move a domain to a new IdP, delete or disable the existing provider first.
  </Accordion>

  <Accordion title="Audit trail">
    The platform writes provider register, update, delete, and domain verification events to the PF-04 audit log. Successful SSO sign-ins create a PF-49 session record visible in **Sessions & devices**.
  </Accordion>
</AccordionGroup>

## Update or remove a provider

Use the same wizard surface for ongoing changes:

* **Update metadata or domains** — re-run the wizard to call `sso-provider-update` with new SAML metadata or an additional verified domain.
* **Disable or delete** — call `sso-provider-delete` to remove the Supabase provider and clear the registry. Users at affected domains revert to email and password sign-in.

Both actions require `pf.sso.manage` and emit PF-04 audit events.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Domain verification stays pending">
    DNS changes can take time to propagate. Confirm the TXT host and value match the wizard exactly (no quotes, no trailing dot mismatch) and re-run **Verify now**. The wizard backs off automatically while polling.
  </Accordion>

  <Accordion title="Test sign-in returns 'no matching employee'">
    The federated email did not match an active `hr_employees` row in this organization. Create the staff record (or sync from Entra) and retry. SSO never creates new employees on the fly.
  </Accordion>

  <Accordion title="Activation rejected with 'domain not verified'">
    `sso-provider-register` blocks activation while any selected domain is still in `pending` or `failed` state. Return to the verification step until every domain is `verified`.
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Entra ID integration" icon="plug" href="/pf/entra-id">
    Directory sync, calendar, SharePoint, and Teams configuration.
  </Card>

  <Card title="Sessions & devices" icon="laptop" href="/pf/sessions-devices">
    Review active sessions, including those created by SSO sign-ins.
  </Card>

  <Card title="Staff security settings" icon="shield-halved" href="/pf/security">
    MFA, passkeys, and app-lock for staff not signing in via SSO.
  </Card>

  <Card title="Audit logs" icon="clipboard-list" href="/pf/audit-logs">
    Review provider lifecycle and sign-in events.
  </Card>
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/platform/settings/pages/SsoSettingsPage.tsx
  * src/platform/auth/sso/SsoSetupWizard.tsx
  * src/platform/auth/sso/useSsoSetup.ts
  * src/platform/auth/sso/useSsoLogin.ts
  * src/platform/auth/Auth.tsx
  * src/routes/platform.tsx
  * supabase/functions/sso-domain-verify
  * supabase/functions/sso-provider-register
  * supabase/functions/sso-provider-update
  * supabase/functions/sso-provider-delete
  * supabase/functions/sso-revoke-unmatched
</Accordion>