---
title: "Configuring Okta directory sync"
canonical_url: "https://docs.getdx.com/okta-directory-sync/"
md_url: "https://docs.getdx.com/okta-directory-sync.md"
last_updated: "2026-05-22"
---

# Configuring Okta directory sync
Before proceeding, please read [Should I set up directory sync?](https://docs.getdx.com/knowledgebase/should-i-set-up-directory-sync/) to ensure that you have an appropriate use case. SCIM directory sync has two potential use cases in DX:

1. [Setting user properties](https://docs.getdx.com/user-properties/)
2. [SCIM-based role management](https://docs.getdx.com/scim-role-management/)

## Setup instructions

#### Step 1 - Enable directory sync

To enable the Directory Sync feature in DX, please contact DX support to activate the feature in your account.

#### Step 2 - Backup user data

We recommend backing up your DX user data in case directory sync is mis-configured and pollutes your user data. To export your user data, go to the User CSV admin page and click the Export CSV button.

#### Step 3 - Create Okta App

Browse to the Directory Sync admin page in DX and click **Enable**. You will be taken to the WorkOS portal—choose Okta as your provider and follow the instructions to create a Okta App.

#### Step 4 - Map attributes

When you get to the **Set up Attribute Mapping** step, you will need to configure your Okta App profile with custom attributes.

The following default attributes should be left unedited:

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-1.png){class="max-w-lg"}

To sync [user properties](https://docs.getdx.com/user-properties/), create attributes by clicking **Go to Profile Editor** from the **Provisioning** tab in the Okta App.

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-2.png){class="max-w-lg"}

From the Profile Editor, click **Add Attribute**.


> Attribute mapping will not work unless these requirements are met:
>
> - **External namespace** must be set to urn:ietf:params:scim:schemas:core:2.0:User to adhere to SCIM conventions.
> - Provide the **External name** value to DX for mapping, not the **Variable name** value (these may be the same).
> - Start dates must be formatted as YYYY-MM-DD or YYYY/MM/DD.


![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-3.png){class="max-w-lg"}

Once your attributes are added, click **Mappings** in the Profile Editor to configure how the values are populated. After this, you can continue through the rest of the WorkOS steps.

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-5.png){class="max-w-lg"}

At this point, your Okta Attribute Mappings should look similar to this:

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-6.png){class="max-w-lg"}

#### Step 5 - Add custom attributes (optional)

To sync custom user attributes, click **Add Attribute**. Then, prefix the "External name" value with "tag\_". In the example below, DX would create and sync a new user tag called "Seniority". Use underscores to denote more spaces (e.g. tag_Shirt_Size will become "Shirt Size" in DX).

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/custom-attribute.png){class="max-w-lg"}

#### Step 6 - Finish setup

Follow the rest of the instructions to fully enable Directory Sync. When you are done, you should see Directory Sync marked as connected in DX. The synchronization process runs automatically each night. If you'd like to run an immediate sync after finishing setup, please contact DX support.

## Troubleshooting

#### I'm seeing "No directory users received"

This indicates that there are no groups or users assigned to the Okta app. Go to the "Assignments" tab in Okta and add a group or set of users you want to sync with DX.

#### Field is not syncing

If a field is not syncing, check that the Okta field has its External namespace set to `urn:ietf:params:scim:schemas:core:2.0:User`. Once the field configuration is updated, click the **Force sync** button within Okta.

![](https://docs.getdx.com/assets/images/administration/okta-directory-sync/setup-7.png){class="max-w-lg"}
---

## Sitemap

[Overview of all docs pages](/llms.txt)