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

# Directory Sync

> Provision and deprovision Horizon organization members from an identity provider through WorkOS.

export const directorySyncPlans = "Enterprise";

Directory Sync connects a Horizon organization to an identity provider through
WorkOS. The identity provider remains the source of directory users and group
membership, while WorkOS carries lifecycle changes into Horizon organization
membership.

<Note>
  Directory Sync is available on {directorySyncPlans} and is currently rolling
  out to selected organizations. The setup flow and Team access behavior may
  change during the rollout. You must be an organization Admin to configure it.
  You also need permission to configure applications in your identity provider.
  If the Directory Sync card is not visible, contact Horizon support to confirm
  that it is enabled for your organization.
</Note>

## Provisioning model

Directory Sync separates identity configuration from Horizon access management.
Your identity provider decides which people and groups belong in the directory.
WorkOS hosts the provider-specific SCIM connection and sends user and membership
changes to Horizon. Horizon reflects the WorkOS organization membership and
shows the connection state.

| System              | Responsibility                                                                   |
| ------------------- | -------------------------------------------------------------------------------- |
| Identity provider   | Controls directory users, their active state, and group membership.              |
| WorkOS Admin Portal | Configures and validates the provider's SCIM connection.                         |
| Horizon             | Reflects organization membership, directory-backed Teams, and connection status. |

Directory groups and their membership synchronize into directory-backed Horizon
Teams. A group member can appear as pending until WorkOS has also provisioned
that person's Horizon account. When Teams is enabled, you can review these
groups and their members under <b>Govern</b> > <b>Teams</b>.

## Connect directory

Horizon generates the setup link, while the identity provider connection is
configured in the WorkOS Admin Portal. Each setup action creates a one-time
portal link. Open it immediately and complete the task in that browser tab.

<Steps>
  <Step title="Open Directory Sync">
    In the Horizon organization sidebar, find <b>Govern</b> and select <b>Single
    Sign-on</b>. The <b>Directory Sync</b> card appears below the SSO settings.
  </Step>

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

  <Step title="Configure the provider">
    Choose your identity provider and follow its instructions in the linked
    portal. The portal supplies the SCIM values and configuration steps for
    Okta, Microsoft Entra ID, and other supported providers.
  </Step>

  <Step title="Activate the directory">
    Complete the connection validation in WorkOS. Return to Horizon and reload
    the page if needed. The Directory Sync card shows <b>Connected</b> when
    WorkOS reports that the directory is connected.
  </Step>
</Steps>

## Verify provisioning

Test the connection with a person whose membership you can safely change in the
identity provider.

<Steps>
  <Step title="Provision a person">
    Assign the person to the Horizon application in your identity provider using
    the provider's normal provisioning workflow.
  </Step>

  <Step title="Check directory counts">
    Return to the Directory Sync card. Its <b>Members</b>, <b>Active</b>, and
    <b>Inactive</b> values are live counts from the WorkOS directory. Reload the
    page if the new directory user has not appeared yet.
  </Step>

  <Step title="Complete first sign-in">
    Ask the person to sign in to Horizon with their work email address. WorkOS
    activates the pending organization membership during the first sign-in.
    Horizon grants organization access only after that membership is active.
  </Step>

  <Step title="Confirm membership">
    Open <b>Govern</b> > <b>Members</b> and confirm that the person belongs to the
    organization. If Teams is enabled, open the corresponding directory-backed
    Team to verify its group membership.
  </Step>
</Steps>

The card's <b>Connected</b> time records when the directory connection was
created. It is not the time of the latest successful synchronization.

## Roles and access

Connecting a directory provisions organization membership. It does not by
itself grant access to a server.

WorkOS IdP Role Assignment can map identity provider groups to the Horizon
organization roles Admin and Member. That organization-role configuration lives
in WorkOS and is separate from the Directory Sync connection.

Server roles are assigned separately in Horizon. Explicit server grants and
server default roles remain available for provisioned members. Directory groups
also become Teams, and Team grants are enforced where team access is enabled.
Directory Sync never creates, changes, or removes those grants. Admins manage
Team grants from a server's **Access** > **Members** page and review a Team's
saved grants from its **Servers** tab.

See [Roles](/roles) for how organization roles, explicit grants, team grants,
and server default roles combine.

## Deprovisioning

Deprovision a person through the identity provider so that WorkOS remains the
source of their lifecycle. When Horizon receives an inactive or deleted
organization membership from WorkOS, it removes the person's organization
membership and their explicit server grants in that organization. Their personal
API keys no longer provide access to that organization, although the keys are
not globally revoked.

If the same person is provisioned again later, prior explicit server grants are
not restored automatically. Assign any required server access again after
confirming the new membership on the [Members](/members) page.

<Warning>
  In Okta, suspending a person does not deprovision them through SCIM. Deactivate
  or delete the directory user instead, then verify the inactive directory count
  and Horizon membership removal.
</Warning>

A temporary disconnection freezes provisioning until the directory is
reconnected.

<Warning>
  Deleting a directory marks its directory-backed Teams as missing and removes
  their memberships. Existing team grants remain saved, but they stop granting
  server access because those Teams no longer have members.
</Warning>

Use the provider's deprovisioning action while the connection is active rather
than disconnecting or deleting the directory to remove an individual member.

## Connection states

Horizon reads directory state and provider metadata from WorkOS whenever the
settings page loads.

| Horizon status | Meaning                                                                                           | Required action                                           |
| -------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Not configured | WorkOS has no directory for the organization.                                                     | Configure a directory through the one-time portal link.   |
| Connecting     | WorkOS is establishing or validating the connection.                                              | Finish the provider setup and wait for validation.        |
| Connected      | The directory is connected and provisioning changes can flow to Horizon.                          | Verify user and membership changes.                       |
| Disconnected   | The directory is disconnected, being deleted, or has invalid credentials. Provisioning is frozen. | Select **Reconnect** and repair the connection in WorkOS. |

For a connected directory, select <b>Manage</b> to generate a new one-time WorkOS
portal link. Use it to review or update the provider configuration.