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

# Single sign-on (SSO) in Default

> How admins set up single sign-on (SSO) for a Default workspace: verify email domains and connect an identity provider such as Okta or Microsoft Entra through the WorkOS Admin Portal.

Single sign-on (SSO) in Default lets your team sign in through your identity provider. On the
**Single Sign-On (SSO)** page, workspace admins configure domain verification and SSO
connections.

> [!NOTE]
>
> Select **Settings** in the sidebar, then **Single Sign-On (SSO)** under
> **Workspace Settings**.
>
> This page is visible to admins only.

You manage both domains and SSO connections through the **Admin Portal**, a hosted WorkOS
interface that Default opens for you. Each time you select **Add domain** or **Set up SSO**,
Default generates a fresh, intent-scoped portal link that opens in that same tab.

Portal links are single-use and expire in about 5 minutes. For this reason, Default
never pre-generates them.

## Domains

The **Domains** section lists every email domain your workspace has registered for SSO
authentication (for example, `acme.com`). Default fetches the current state of each domain
and shows it as a badge.

| State | Badge | What it means |
| - | - | - |
| `verified` | **Healthy** (green) | Domain verification passed. SSO can use this domain. |
| `legacy_verified` | **Healthy** (green) | Verified through an earlier flow. Treated as verified. |
| `pending` | **In progress** (amber) | Verification is underway. Check back shortly. |
| `failed` | **Configure** (grey) | Verification failed. Open the Admin Portal to retry. |

### Add a domain

Select **Add domain** to open the WorkOS Admin Portal. Follow the steps in the portal to
add and verify your domain.

Verification usually involves a DNS TXT record. When verification completes, Default shows
the domain with a **Healthy** badge.

### Remove a domain

To remove a domain, select the trash icon on its row.

Default asks you to type the domain name exactly to confirm, for example `acme.com`. The
removal takes effect only after you confirm.

> [!WARNING]
>
> You cannot remove a domain while any SSO connection is **Active** or **Validating**.
> Remove the SSO connection first.
>
> Then delete the domain.
>
> Members who sign in via SSO with that email domain lose access when you remove the
> domain. You cannot undo this.

## Single Sign-On

The **Single Sign-On** section lists the SSO connections your workspace has configured
through the Admin Portal. Each connection shows a name, the connection type (such as
`Okta SAML`), and its current state as a badge.

| State | Badge | What it means |
| - | - | - |
| `active` | **Active** (green) | SSO is live. Members can sign in through this connection. |
| `validating` | **Validating** (amber) | WorkOS is testing the connection. Setup is nearly complete. |
| `draft` | **Draft** (grey) | Connection was created but not yet configured fully. |
| `inactive` | **Inactive** (red) | Connection exists but is not accepting sign-ins. |

### Set up or manage SSO

Select **Set up SSO** to open the WorkOS Admin Portal. Create your first SSO connection
there.

After a connection exists, the button changes to **Manage SSO**. Use it to edit, test, or
remove connections.

> [!NOTE]
>
> **Set up SSO** is disabled until you have at least 1 verified domain. Default shows
> a prompt ("Verify a domain to enable SSO setup.") until that condition is met.

## Microsoft 365 and Entra accounts

Default's sign-in screen offers a **Microsoft** button. That button is a *personal*
Microsoft account (MSA) login — the kind used for Outlook.com, Xbox, and Skype. It sends you
to `login.live.com`, which does not recognize Office 365 / Entra work accounts. Signing in
there with a work address such as `you@acme.com` fails with "We couldn't find a Microsoft
account".

Office 365 workspaces have two supported paths instead:

| Path | When to use it | What your team sees |
| - | - | - |
| **Microsoft Entra SSO** | Recommended. Set it up once on this page. | Members entering a verified domain address go straight to your Entra sign-in. |
| **Email sign-in code** | Works immediately, no setup. | Members receive a one-time code by email. |

> [!NOTE]
>
> Set up Entra through **Set up SSO** on this page, the same flow as any other identity
> provider — not through the **Microsoft** button on the sign-in screen. The two are
> unrelated: one is a personal-account social login, the other is your organization's
> directory.

Once your domain is verified and an Entra connection is active, Default sends returning
members on that device to your Entra sign-in automatically, so they no longer see the
personal-account button as their first option.

## Example: verify a domain, then connect SSO

**1. Add and verify your domain**

In the **Domains** section, select **Add domain**. The Admin Portal opens.

Enter your domain, for example `acme.com`. Follow the DNS verification steps.

When verification completes, the domain appears with a **Healthy** badge.

**2. Set up your SSO connection**

In the **Single Sign-On** section, select **Set up SSO**. The Admin Portal opens to
the SSO configuration flow.

Choose your identity provider, such as Okta or Microsoft Entra. Complete the setup.

Activate the connection. The connection appears in Default with an **Active** badge.

**3. Confirm your team can sign in**

Ask a team member to sign in with their `acme.com` email. Default routes them through
your identity provider.

After this test succeeds, SSO is live for your workspace.


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