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

# Single sign-on

> Configure SAML or OIDC single sign-on for a Horizon organization through the WorkOS Admin Portal.

export const ssoPlans = "Enterprise";

Single sign-on (SSO) connects a Horizon organization to an identity provider.
After setup, members with email addresses on the verified domain sign in through
the organization's identity provider.

<Note>
  SSO is available on {ssoPlans}. You must be an organization Admin to view or
  change SSO settings. You also need access to the domain's DNS records and
  permission to configure applications in your identity provider.
</Note>

Horizon delegates domain verification and identity provider configuration to
the WorkOS Admin Portal. Each setup action in Horizon opens a one-time WorkOS
portal link. Open the link immediately and complete the task in that browser
tab.

## Configuration boundary

Horizon controls access to the setup workflow and shows its current state.
WorkOS handles the provider-specific configuration.

| Horizon                                                            | WorkOS Admin Portal                                      |
| ------------------------------------------------------------------ | -------------------------------------------------------- |
| Checks the organization's plan and the administrator's permissions | Verifies ownership of the sign-in domain                 |
| Generates one-time portal links                                    | Collects the SAML or OIDC configuration                  |
| Shows domain and connection status                                 | Validates and activates the identity provider connection |
| Deletes configured domains and connections                         | Stores the provider configuration                        |

You enter identity provider certificates, metadata, client credentials, and
secrets in WorkOS. Horizon requests portal links, reads non-secret domain and
connection status, and sends deletion requests to WorkOS. The provider
configuration does not pass through the Horizon API.

## Verify domain

Domain verification proves that the organization controls the email domain
that will use SSO. Horizon requires at least one verified domain before it lets
you configure an identity provider connection.

<Steps>
  <Step title="Open SSO settings">
    In the Horizon organization sidebar, find <b>Govern</b> and select
    <b>Single Sign-on</b>. The page initially shows <b>Domain verification
    required</b>.
  </Step>

  <Step title="Open WorkOS">
    Select <b>Verify domain</b>. Horizon generates a one-time link and opens the
    WorkOS Admin Portal in a new tab.
  </Step>

  <Step title="Complete verification">
    Enter the domain your members use to sign in. Follow the WorkOS instructions
    to add the required record to that domain's DNS configuration. DNS changes
    can take time to propagate, so wait for WorkOS to report that verification
    succeeded before closing the portal.
  </Step>

  <Step title="Confirm the domain">
    Return to Horizon and reload the <b>Single Sign-on</b> page if its status has
    not updated. The domain should show <b>Verified</b>, and the page should move
    to <b>SSO not configured</b>.
  </Step>
</Steps>

## Connect provider

An SSO connection tells WorkOS how to authenticate members with your identity
provider. The WorkOS portal supplies the provider-specific values and prompts.
Horizon does not collect them.

Supported providers follow the
[WorkOS integration catalog](https://workos.com/integrations). The catalog
includes provider-specific SAML and OIDC integrations as well as generic protocol
options for compatible identity providers.

<Steps>
  <Step title="Open connection setup">
    Select <b>Configure SSO</b>. Horizon generates another one-time link and
    opens the WorkOS Admin Portal.
  </Step>

  <Step title="Choose the protocol">
    Select your identity provider and configure the connection as SAML or OIDC.
    For SAML, follow the portal prompts for metadata, sign-in URLs, identifiers,
    and certificates. For OIDC, follow its prompts for issuer or discovery
    details and client credentials.
  </Step>

  <Step title="Activate the connection">
    Complete the provider's setup and validation in WorkOS. Keep the Horizon
    administrator session open while you test the connection so you can return
    to the settings page if the test fails.
  </Step>

  <Step title="Confirm SSO">
    Return to Horizon and reload the page if needed. The page shows <b>SSO
    enabled</b> when it finds both a verified domain and an <b>Active</b>
    connection.
  </Step>
</Steps>

## Verify sign-in

Test with a member whose email address uses the verified domain. Open a private
browser window, go to the Horizon sign-in page, and enter that member's work
email address. WorkOS identifies the domain and sends the member to the
organization's identity provider. After the identity provider authenticates
the member, the browser returns to Horizon.

SSO changes authentication. Use [Directory Sync](/administration/directory-sync)
for identity-provider-managed provisioning and deprovisioning. SSO does not
change organization or server access. The member keeps the permissions assigned
through their [organization and server roles](/roles).

## SSO states

After SSO is available on the organization's plan, Horizon reads the current
domain and connection status from WorkOS and reduces it to one setup state.

| Horizon status               | Meaning                                               | Required action                                    |
| ---------------------------- | ----------------------------------------------------- | -------------------------------------------------- |
| Domain verification required | No configured domain is verified.                     | Complete domain verification in WorkOS.            |
| SSO not configured           | A domain is verified, but no connection is active.    | Configure and activate SAML or OIDC in WorkOS.     |
| SSO enabled                  | A domain is verified and an SSO connection is active. | Test sign-in with a member on the verified domain. |

## Manage SSO

When SSO is enabled, select <b>Manage SSO</b> to generate a new one-time WorkOS
portal link. Use it to review or update the provider configuration.

Organization admins can also delete domains and connections from Horizon.
Deleting the last active connection moves the organization back to <b>SSO not
configured</b>. Deleting its last verified domain moves it back to <b>Domain
verification required</b>. Deletion cannot be undone, so keep the existing
configuration until the replacement domain or connection is ready.