Configuring Okta single sign-on

This guide walks you through setting up Single Sign-On (SSO) with Okta for DX. DX supports two SSO protocols with Okta: SAML and OIDC (OpenID Connect). You only need to configure one.

  • SAML is the traditional enterprise SSO protocol. Use this if your organization already uses SAML with Okta, or if you want to use the pre-built DX Okta application.
  • OIDC is a modern, lightweight alternative. Use this if you prefer a simpler setup with just a client ID, client secret, and issuer URL.

Option A: SAML setup

Follow the instructions below to set up Okta single sign-on using the official DX Okta application.

Step 1 - Get SAML info

In DX, navigate to Administration > SSO. Make sure SAML is selected as the SSO protocol. Expand Show DX service provider details to obtain:

  • Single Sign-On URL (ACS URL)
  • Audience URI (SP Entity ID)

Only copy the final portion of the ACS URL and Entity ID to use in the next step.

Step 2 - Add DX Okta app

Log in to your Okta Identity provider account then:

  1. Navigate to Applications.
  2. Search for the application named “DX”.
  3. Assign the users or groups that should be able to log in.
  4. Click Add Integration.

Step 3 - Configure Okta settings

In Okta, go to the DX application’s General tab:

  1. Paste the ACS ID and Entity ID obtained in Step 1 (only the last portions, as noted earlier).
  2. Save or continue to the next step.

Step 4 - Configure DX settings

In Okta, go to the Sign On tab of the DX application.

  1. Copy the Metadata URL.
  2. In DX, navigate to the Administration > SSO page and enter the metadata URL (or upload the metadata XML file).
  3. Optionally, enable Require SAML SSO authentication to enforce SAML for all users.
  4. Click Update settings to apply the changes.

Option B: OIDC setup

Follow the instructions below to set up Okta single sign-on using OIDC.

Step 1 - Create an Okta application

Log in to your Okta admin dashboard then:

  1. Navigate to Applications > Applications.
  2. Click Create App Integration.
  3. Select OIDC - OpenID Connect as the sign-in method.
  4. Select Web Application as the application type.
  5. Click Next.

Step 2 - Get the callback URL from DX

In DX, navigate to Administration > SSO. Select OIDC as the SSO protocol. Expand Show DX OIDC details and copy the Callback URL.

The callback URL contains a unique identifier for your account and will look like:
https://app.getdx.com/oidc/callback/AbCdEfGhIjKlMnOpQrStUvWxYz1234
or
https://<your_company>.getdx.io/oidc/callback/AbCdEfGhIjKlMnOxYz1234 if you’re on a dedicated installation.

Step 3 - Configure the Okta application

In the Okta application setup:

  1. Give the application a name (e.g., “DX”).
  2. Under Sign-in redirect URIs, paste the exact Callback URL from Step 2. Okta does not support wildcards in redirect URIs, so the full URL must match exactly.
  3. Under Sign-out redirect URIs, enter your DX sign-in page URL (e.g., https://app.getdx.com/signin).
  4. Under Assignments, choose which users or groups should have access.
  5. Click Save.

Step 4 - Copy Okta credentials

After saving, Okta will display the application credentials. You will need:

  • Client ID — found on the application’s General tab.
  • Client Secret — found on the application’s General tab. Click the copy icon or eye icon to reveal it.
  • Issuer URL — this is your Okta domain URL, without the -admin suffix. For example, use https://your-domain.okta.com, not https://your-domain-admin.okta.com. You can verify the correct issuer by navigating to Security > API > Authorization Servers in your Okta admin dashboard and copying the Issuer URI.

Common mistake: Using the Okta admin URL (with -admin in the domain) as the issuer URL will cause an issuer mismatch error. Always use the non-admin domain.

Step 5 - Configure DX settings

In DX, on the Administration > SSO page with OIDC selected:

  1. Enter the Issuer URL from Okta.
  2. Enter the Client ID from Okta.
  3. Enter the Client Secret from Okta.
  4. Optionally, enable Require OIDC SSO authentication to enforce OIDC for all users.
  5. Click Update settings to apply the changes.

Enforcing SSO

Regardless of which protocol you choose, you can toggle the Require SSO authentication option on the SSO admin page. When enabled, all other authentication methods (email, Slack, Microsoft) are disabled, and users are redirected to your Okta login page automatically.