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

# Directory sync (SCIM)

> Provision members, map identity provider groups to Odin roles and remove access automatically with SCIM 2.0

Directory sync lets your identity provider manage who belongs to your Odin organisation and with what role, over SCIM 2.0. When someone joins, changes team or leaves in your IdP, Odin follows within seconds.

Set it up from **Organisation Settings → Single Sign-On → Directory synchronisation**. It needs an active [SSO connection](/platform/sso/set-up) first.

## Create the directory

<Steps>
  <Step title="Choose the provider">
    Pick the **Directory provider**: **Okta SCIM 2.0**, **Microsoft Entra ID SCIM 2.0**, **OneLogin SCIM 2.0**, **JumpCloud SCIM 2.0** or **Generic SCIM 2.0**. Optionally rename the **Directory name**.
  </Step>

  <Step title="Choose who manages roles">
    Under **Roles**, leave **Directory manages roles** off to manage roles in Odin, or turn it on and enter the IdP group for each role. See [Roles](#roles). You can change this later.
  </Step>

  <Step title="Create it and copy the credentials">
    Select **Create SCIM directory**. Odin shows the **SCIM endpoint** and **SCIM bearer token** once. Copy both into your IdP's provisioning settings straight away.
  </Step>

  <Step title="Turn on provisioning in your IdP">
    Enable creating users, updating user attributes and deactivating users. If the directory manages roles, also push the mapped groups. The [identity provider guides](/platform/sso/identity-providers) have the exact steps.
  </Step>
</Steps>

<Warning>
  The bearer token cannot be shown again. If you lose it, remove the directory and create a new one, then update your IdP. Treat the token like a password: anyone holding it can provision users into your organisation.
</Warning>

## What directory sync does

| In your IdP | In Odin |
| - | - |
| User assigned or activated | The person is added to your organisation (as **Member** unless a mapped group says otherwise), if a seat is available. See [seats](/platform/sso/overview#how-people-sign-in). |
| Name changed | Their first and last name are updated |
| Added to or removed from a mapped group | Their role changes to match |
| User unassigned, deactivated or deleted | Their membership is removed, their sessions end and SSO into your organisation is blocked |
| User reactivated | Membership is restored and the block is lifted |

Deprovisioning removes access to **your organisation only**. Odin keeps the person's global account, so other organisations they belong to are unaffected.

<Note>
  Directory sync only adds people whose email is on one of the connection's **verified domains**. Other addresses in the directory are ignored. Removals always apply, so access can always be withdrawn.
</Note>

## Access

By default, anyone your IdP lets sign in to Odin joins your organisation the first time they sign in with SSO, even if the directory has not provisioned them yet.

Turn on **Only directory-provisioned people can join** to make the directory the only way in. Odin then refuses an SSO sign-in from anyone who is not already in your organisation, with *"you have not been added yet"*. It also stops automatic joining by email domain.

* People already in your organisation, including people you [invite](/platform/team-management), sign in as before.
* The setting saves as soon as you switch it, and needs a directory. Removing the directory turns it off.
* Use it when IdP app assignment and SCIM provisioning can drift apart, for example when SSO is assigned to everyone but provisioning is scoped to a group.

## Roles

**Directory manages roles** decides who controls roles:

* **Off** (the default): the directory only adds and removes people. New people join as **Members**, and you change roles in [Team Management](/platform/team-management). Directory sync never changes a role.
* **On**: roles follow IdP groups, as described below.

### Role mapping

With **Directory manages roles** on, enter one IdP group name for each Odin role:

* **Odin administrators** → **Admin**
* **Odin members** → **Member**
* **Odin read-only users** → **Read only**

Group names are matched without regard to case. If someone is in several mapped groups, they get the highest role: Admin, then Member, then Read only. People in no mapped group are **Members**.

Directory sync never assigns or changes the **Owner** role. Owners stay under your control in [Team Management](/platform/team-management).

<Warning>
  Role mapping applies to everyone in the directory as soon as you save it. An existing Admin who is not in your mapped admin group becomes a **Member**. Add your admins to that group in the IdP **before** you save. Turning roles on with no groups entered makes every directory user a **Member**.

  Role changes from directory sync take effect immediately and sign the person out, so they sign in again with their new role.
</Warning>

When you select **Save role settings**, Odin first shows who the change affects, with each person's role change, additions and removals, under **Apply role changes?**. Nothing changes until you select **Apply changes**. If nobody's access changes, the settings save straight away.

Odin refuses settings that would remove **your own** admin access, or leave the organisation with no Owner or Admin, and shows why next to the button. Add the right people to your admin group in the IdP, or turn off **Directory manages roles**, then save again.

<Info>
  While **Directory manages roles** is on, a role you change by hand in Team Management for a directory-managed person is overwritten at the next sync. Turning it off keeps everyone's current role.
</Info>

Selecting **Save role settings** saves and immediately re-applies the directory, with names, additions and deactivations, to every user in it. Use it to bring Odin back in line after changing settings or pausing the directory.

## Managing the directory

| Action | What happens |
| - | - |
| **Pause** / **Enable** | Stops applying changes from your IdP, then resumes. While paused, your IdP may report changes as successful even though Odin does not apply them, so **Enable** re-applies the whole directory to catch up. |
| **Rotate webhook secret** | Replaces the internal secret Odin's SSO service uses to deliver directory events to Odin. Your IdP's settings do not change. |
| **Remove SCIM directory** (bin icon) | The SCIM endpoint stops accepting requests. Existing Odin memberships are kept, and directory-based sign-in blocks are lifted. |

Removing the [SSO connection](/platform/sso/set-up#managing-the-connection) also removes its directory.


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