Okta Workforce Connection not Using Okta Custom Domain

Knowledge Solutions
, , ,
1

Problem statement

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.

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. Refer to 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

  3. 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.

  4. GET the auth0 connection to patch api/v2/connections/:id.

  5. You will 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.

  6. 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.