> ## 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)

> Set up domain verification and Single Sign-On (SSO) for your workspace.

The **Single Sign-On (SSO)** page is where workspace admins configure domain verification
and SSO connections, so your team can authenticate through your identity provider.

<Note>
  Open **Settings** from the **Dock** (the app bar at the bottom of the screen), then
  select **Single Sign-On (SSO)** under **Workspace Settings**. This page is visible to
  admins only.
</Note>

Both domains and SSO connections are managed 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 roughly five minutes, so 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 (usually involves adding 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`) before the removal takes effect.

<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 will lose access when the domain is removed. This cannot be
  undone.
</Warning>

## 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 and create your first SSO
connection. Once 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 one verified domain. Default shows
  a prompt ("Verify a domain to enable SSO setup") until that condition is met.
</Note>

## Example: verify a domain, then connect SSO

<Steps>
  <Step title="Add and verify your domain">
    In the **Domains** section, select **Add domain**. The Admin Portal opens. Enter your
    domain (for example, `acme.com`) and follow the DNS verification steps. When
    verification completes, the domain appears with a **Healthy** badge.
  </Step>

  <Step title="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, and activate the connection. The connection appears in
    Default with an **Active** badge.
  </Step>

  <Step title="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. Once confirmed, SSO is live for your workspace.
  </Step>
</Steps>