Skip to main content
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 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.
Use this path when the same Entra tenant that powers provisioning should also power staff login.
1

Connect Entra ID first

Run Entra ID guided setup at /settings/integrations/entra. The integration must be Connected (green health badge) before the SSO toggle becomes available.
2

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.
3

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.
4

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.
5

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.
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.

​
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: 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:

​
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.
1

Open the SAML wizard

Navigate to /settings/security/sso and select Set up SAML SSO under the Advanced section. The SsoSetupWizard opens.
2

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.
3

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.
4

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.
5

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.

​
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

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.
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.
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.
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.
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.

​
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

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.
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.
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.

Entra ID integration

Directory sync, calendar, SharePoint, and Teams configuration.

Sessions & devices

Review active sessions, including those created by SSO sign-ins.

Staff security settings

MFA, passkeys, and app-lock for staff not signing in via SSO.

Audit logs

Review provider lifecycle and sign-in events.
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.
  • 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