OIDC single sign-on
To enable OpenID Connect (OIDC) single sign-on (SSO) for authentication to DX, you must create an OIDC application in your identity provider (IdP) and configure the credentials in your DX workspace.
OIDC is a modern authentication protocol built on top of OAuth 2.0. It is an alternative to SAML SSO and may be preferred for its simpler configuration. Any identity provider that supports the OIDC authorization code flow can be used with DX. See below for links to documentation for common providers:
| OIDC Provider | Documentation |
|---|---|
| Okta | Link |
| Microsoft Entra | Link |
| Link | |
| OneLogin | Link |
| PingOne | Link |
| Keycloak | Link |
Prerequisites
Before configuring OIDC SSO in DX, you will need to create a Web Application in your identity provider with the following settings:
- Grant type: Authorization Code
- Scopes:
openid,email,profile - Sign-in redirect URI: The Callback URL from your DX SSO settings page
After creating the application, your identity provider will provide you with a Client ID, Client Secret, and Issuer URL (sometimes called the “Discovery URL” or “OpenID Connect metadata URL”).
Enabling OIDC SSO
- In DX, navigate to Administration > SSO and select OIDC as the SSO protocol.
- Expand Show DX OIDC details and copy the Callback URL.
- In your identity provider, create an OIDC web application and paste the Callback URL as the sign-in redirect URI.
- Copy the credentials from your identity provider and enter them in DX:
| Value | Description | Example |
|---|---|---|
| Issuer URL | The base URL of your OIDC provider. DX uses this to discover endpoints via /.well-known/openid-configuration. |
https://dev-123456.okta.com |
| Client ID | The public identifier for your OIDC application. | 0oa1b2c3d4e5f6g7h8i9 |
| Client Secret | The secret used to authenticate your application during the token exchange. This value is stored encrypted in DX. | AbCdEfGhIjKlMnOpQrSt |
| Callback URL | The DX endpoint that your identity provider redirects to after authentication. This is generated automatically for your account and displayed in DX settings. | https://app.getdx.com/oidc/callback/... |
- Click Update settings to save.
The OIDC flow authenticates users by matching the email claim (or preferred_username) from the ID token to a user in DX. If you need email domain mapping similar to SAML domains, please contact DX support.
Requiring OIDC SSO
You can enable OIDC SSO in your organization without requiring all members to use it. Enabling but not requiring OIDC SSO can help smooth adoption. When OIDC SSO is enforced, all other methods of authentication (e.g., passwordless email, Slack OpenID) are disabled.
To enforce OIDC SSO, toggle Require OIDC SSO authentication on the SSO settings page.
Troubleshooting
| Error | Cause |
|---|---|
| Issuer mismatch | The Issuer URL saved in DX does not match the issuer value returned by the provider’s discovery endpoint. Ensure you are using the correct, non-admin domain URL. |
| Invalid redirect URI | The Callback URL configured in your identity provider does not exactly match the one shown in DX. Wildcards are not supported — the full URL must match. |
| No email found in OIDC token claims | The ID token from your provider does not include an email or preferred_username claim. Ensure the email scope is requested and the user has an email set. |
| User not found | The email from the ID token does not match any user in DX. The user must be created in DX first, or JIT provisioning must be enabled. |