Introduction

DX supports IdP- and SP-initiated Okta SAML 2.0 authentication, as well as SCIM-based Directory Sync.

Okta SAML

Step 1

Before getting started, contact your DX account representative to request three things:

DX icon
Single sign-on URL
Audience URI (SP Entity ID)

Step 2

From the Okta admin portal, create a new SAML 2.0 app integration.

Step 3

In the "General Settings" step, enter "DX" as the App name and upload the DX icon.

Step 4

In the "Configure SAML" step, enter the single sign-on URL and Audience URI provided to you by your DX account representative. In addition, select EmailAddress as your Name ID format.

Step 5

In the final step, mark your integration as an internal app and then provide the IdP Metadata URL to your DX account representative to finish setting up your integration. You may opt to only allow authentication through Okta or still allow other forms of password-less authentication and single sign-on.

Okta Directory Sync

User metadata such as manager, start date, and GitHub/GitLab usernames can be imported via Okta SCIM. To enable this, please contact your DX Account Representative.

Step 1 - Get a user data backup

Before getting started, we highly recommend exporting your current user data in case the directory sync is misconfigured and updates user attributes incorrectly.

Go to the CSV Import page and click "Export CSV" in the upper right-hand corner.

Step 2 - Create the Okta App

1. Go to the directory sync settings page, and click "Enable". This will take you to a WorkOS portal - choose "Okta" as your directory provider.

2. Follow the step-by-step 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 the Okta App's 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 names updated.

2. To create custom attributes for syncing start dates, manager emails, GitHub usernames, and GitLab usernames, click "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 exactly urn:ietf:params:scim:schemas:core:2.0:User to adhere to SCIM conventions.
You must 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 tags, 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 - Complete setup

Follow the rest of the step-by-step instructions to complete the directory sync setup. When you are done, you should see the directory sync marked as connected in DX. The directory sync runs automatically each night. If you'd like to run an immediate directory sync after initial 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.