Okta Workforce Connection Not Using Okta Custom Domain

Knowledge Articles
, ,
1

Last Updated: Sep 19, 2024

Overview

When attempting to configure an Okta Workforce connection to use an Okta Custom Domain, the redirect goes to {okta_canonical_domain}/oauth2/v1/authorize instead of {okta_custom_domain}/oauth2/v1/authorize.

Applies To

  • Okta Workforce connection
  • Okta Custom Domain

Cause

The Okta Workforce connection is hardcoded to use the default authorization server rather than the custom authorization server that would use the Okta Custom Domain. However, there is a way to PATCH the connection with the Management API to reach the custom server instead.

Solution

Here are the steps to have an Okta Workforce connection using a custom domain:

  1. Create the Okta connection, entering only the domain in the auth0 dashboard. This will configure the default or org authorization server in Okta. For more information, refer to the Org Authorization Server.

  2. Configure the Custom Authorization Server in Okta. The custom Auth server ID created for this example is abc123, and the tenant is trial-123456789.okta.com. The general format is:

  • https://${yourOktaDomain}/oauth2/${authorizationServerId}/.well-known/openid-configuration

  1. Using the identifier of the custom authorization server, manually fetch the metadata using the well-known endpoint https://trial-123456789.okta.com/oauth2/abc123/.well-known/openid-configuration in a browser window.

  2. GET the Auth0 Connection to patch api/v2/connections/:id .

  3. PATCH all connection.options returned from the above step as per documentation, but update the values as shown in the table below. Refer to Update a connection.

  4. The following connection.options should be updated in the PATCH:

data element Sample value
connection.options.issuer https://trial-123456789.okta.com/abc123
connection.options.jwks_uri “https://trial-123456789.okta.com/oauth2/abc123/v1/keys”
connection.options.authorization_endpoint https://trial-123456789.okta.com/oauth2/abc123/v1/authorize
connection.options.token_endpoint "https://trial-123456789.okta.com/oauth2/abc123/v1/token
connection.options.userinfo_endpoint “https://trial-123456789.okta.com/oauth2/abc123/v1/userinfo”
connection.options.oidc_metadata the entire metadata response from step # above
connection.options.discovery_url Remove this element from the PATCH request

This should make it so the Okta Custom Domain (custom authorization server) is used by the Workforce Connection.

Related References