Before proceeding with enabling Okta directory sync, please read Should I set up directory sync? to ensuyre that you have a valid use case. SCIM-based directory sync has two purposes in DX:
Instructions
To enable Directory Sync feature in DX, please first contact your DX account representative to turn on the feature in your account.
Step 1 - Backup your user data
Before getting started, we recommend exporting your DX user data so that you have a backup in the event that Directory Sync is mis-configured. To export your user data, go to the User CSV admin page and click Export CSV in the top right-hand corner.
Step 2 - Create Okta App
Go to the Directory Sync admin page in DX and click Enable.
You will be taken to the WorkOS portal—choose Okta as your directory provider and follow the instructions to create your Okta App for DX.
Step 3 - Map attributes
When you get to the Set up Attribute Mapping step, you will need to configure your Okta App profile with custom attributes.
1. There are some default attributes that should be left as-is. The following attributes should be left unedited so DX can correctly identify users via email and keep user names up-to-date.
2. To sync start dates, manager emails, GitHub usernames, and GitLab usernames, create custom attributes by clicking "Go to Profile Editor" from the "Provisioning" tab in the Okta App.
3. 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:Userto adhere to SCIM conventions.Provide the "External name" value to DX for mapping, not the "Variable name" value (although these can be the same).
Start dates must be formatted as YYYY-MM-DD or YYYY/MM/DD.
4. To sync custom user attributes, 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).
5. Once your attributes are added, click "Mappings" from the Profile Editor to configure how the values are populated. After this, you can continue through the rest of the WorkOS steps.
Step 4 - Enable provisioning actions
Currently, user provisioning is not supported - DX only updates existing user attributes. At this point, your Okta App's Attribute Mappings should look something like this.
Step 5 - 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 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.
Custom field is not syncing
If a custom 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.
