Adding A Custom Domain to Your Okta Tenant & React App

For those of you that are using Okta as your Authentication Provider within your React app. You're probably going to want to bind it to a custom domain sooner or later. Within this guide I'll walk you through how to do just that. While my example is going to be specific to React, this will still apply to any front-end that's using Okta for authentication. Let's get started.

It's important to note that some of the steps outlined below may contain navigation paths that differ between an Okta Enterprise & Okta Developer account.

Step 1: Configuring Your Custom Domain Within Okta

The first step you'll need to take is to set up your domain in Okta. Be sure to have your SSL cert and be logged into your registrar:

1. Navigate to Settings > Customization within the Okta admin portal (Or Customization > Domain Name if you're using an Okta developer account)

2. Head to the Custom URL Domain and click Edit

3. Click Get Started

4. Enter your custom domain name (Note: this must be a subdomain of your primary)

5. Click Next

6. Copy the TXT record provided by Okta and add it within your DNS Configuration of your domain (Tip: If you're new to DNS, Okta provides the full URL, you'll just want to add the subdomain of what they provide)

7. Click Verify, if the verification is successful click Next

8. Enter your SSL Certificate & Private Key

9. Click Next

10. Finally, add the CNAME record within your DNS Configuration to point to the URL provided on this page.

Step 2: Configuring A New Authorization Server

After successfully binding your domain within your Okta Tenant, you'll want to:

1. Navigate to Security > API within the Okta admin portal

2. Click + Add Authorization Server

3. Add a Name, Audience, and Description

4. Click Save

5. Click the pencil icon to Edit the newly created Auth Server

6. Click the Access Policies Tab

7. Click Add Policy

8. Add a Name, Description, and Leave "Assign To" set to All Clients

9. Click Add Rule

10. Name it Default Auth Rule

11. Click Create Rule

NOTE: You'll notice we didn't have to set the custom domain. That's correct, by default the custom domain will be used when the new auth server is created.

New Auth Server Example

Step 3: Update Your React App Settings

Now that you have Okta configured, you'll want to head back into your react app's settings and update a one small setting to make sure you're pointed to the right place:

1. Open your Okta Configuration and update the Issuer to your new custom domain

2. After you add the new Authentication Server, copy the Issuer URI that's generated

Example

const CLIENT_ID = process.env.OKTA_CLIENT_ID || '{clientId}';
const ISSUER = 'https://YOURCUSTOMDOMAIN/oauth2/YOURNEWAUTHSERVERID';
const OKTA_TESTING_DISABLEHTTPSCHECK = process.env.OKTA_TESTING_DISABLEHTTPSCHECK || false;
const REDIRECT_URI = `${window.location.origin}/login/callback`;
export const OktaConfig = {
    oidc: {
        clientId: CLIENT_ID,
        issuer: ISSUER,
        redirectUri: REDIRECT_URI,
        scopes: ['openid', 'profile', 'email'],
        pkce: true,
        disableHttpsCheck: OKTA_TESTING_DISABLEHTTPSCHECK,
    },
};

Bonus: Troubleshooting

If you're getting an exception within your console that looks like this:

Uncaught (in promise) AuthSdkError: The issuer [https://YOURDOMAIN.okta.com/oauth2/default] does not match [https://YOURCUSTOMDOMAIN/oauth2/default]

You've forgotten to create the Authorization server and update your React App's settings.

If you're getting an exception returned to your /login/callback url that looks like this:

error_description=Policy+evaluation+failed+for+this+request%2C+please+check+the+policy+configurations.

You've forgotten to add a default policy to your new Authentication Server