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

# Single sign-on

> Route sign-in for your company's email domains through your own identity provider with enterprise SAML SSO.

Single sign-on delegates Alforse authentication to a SAML 2.0 identity provider, such as Okta, Entra ID, or Google Workspace. After you verify an email domain through DNS, Alforse routes ERP and MES users on that domain to the identity provider automatically. Magic link and other sign-in methods remain available until you enable [Require SAML SSO](#requiring-sso). The **Single Sign-On** section appears on **Settings → Security** only when SSO is enabled for your account.

## Connect your identity provider

Everything lives on one screen: **Settings → Security**, under **"Single Sign-On"** (saving needs `settings` update).

Alforse screenshot**Settings → Security, Single Sign-On section with an active connection: Service Provider Details, Identity Provider card with Require SAML SSO switch, and the Email Domains card**

The whole SSO exchange happens on one settings screen.

**Copy Alforse's service provider details.** The **"Service Provider Details"** card shows the **"ACS URL"** and **"SP Metadata URL"** with copy buttons.

**Register Alforse in your IdP** as a SAML application using those two URLs. The assertion must include an **email attribute**; the email is how Alforse matches each sign-in to a person and a company.

**Paste the IdP metadata back into Alforse.** In the **"Identity Provider"** card, provide the **"IdP Metadata URL"** *or* the raw **"IdP Metadata XML"** (exactly one), then **"Connect"** (later edits use **"Save changes"**). The card gaining a **"Require SAML SSO"** switch and a **"Deactivate"** button is the sign the connection is active.

**Verify your email domains.** The **"Email Domains"** card appears once the connection exists. Add each domain your people sign in with, publish the DNS record it shows, and click **"Verify"**. Only verified domains route SSO sign-ins.

## Verifying a domain

Each added domain starts **Pending** with a unique TXT challenge shown on the card:

| Record | Value |
| - | - |
| **Host** | `_alforse-challenge.example.com` |
| **Type** | `TXT` |
| **Value** | `alforse-domain-verification=<your unique token>` |

Publish the record at your DNS host, click **"Verify"**, and on a match the domain flips to **Verified**. Verification is one-time; the TXT record can be deleted afterwards. A Pending domain has no effect anywhere, so adding one is always safe.

HEADS UP

**Verified claims are exclusive**

Only one company can hold a domain verified, first to prove DNS control wins, and the claim survives even if DNS control later changes hands. The clean handover is for the holding company to **Remove** the domain, which frees it for the new owner to verify.

## How sign-in works

On the email-first login page, selecting **"Continue"** either redirects the user to the domain's active IdP or continues to the standard magic-link flow. Before creating a session, Alforse requires the asserted email domain to match a **verified** domain on the connection.

SSO provisioning is **invite-first**; it does not support self-service signup. An existing member's first SSO login links the SAML identity to their account. A pending invite is accepted during the first SSO login and applies its assigned role. Alforse rejects all other users without provisioning an account. Create their invite in the [employees directory](/docs/reference/people.md), then retry.

## Requiring SSO

The **"Require SAML SSO"** switch makes the IdP the only permitted authentication method for verified domains. Alforse refuses magic links, Google, and passkeys for those users. The switch appears only for an active connection, allowing you to verify sign-in before enforcement. Turning it off restores other methods. **"Deactivate"** deletes the connection, releases its domain claims, and also restores other methods.

SSO sessions bypass Alforse's [two-factor challenge](/docs/reference/two-factor.md), including in controlled deployments, because the IdP enforces its own MFA policy. Magic-link logins still use Alforse's challenge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.