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:
Navigate to Settings > Customization within the Okta admin portal (Or Customization > Domain Name if you're using an Okta developer account)
Head to the Custom URL Domain and click Edit
Click Get Started
Enter your custom domain name (Note: this must be a subdomain of your primary)
Click Next
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)
Click Verify, if the verification is successful click Next
Enter your SSL Certificate & Private Key
Click Next
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:
Navigate to Security > API within the Okta admin portal
Click + Add Authorization Server
Add a Name, Audience, and Description
Click Save
Click the pencil icon to Edit the newly created Auth Server
Click the Access Policies Tab
Click Add Policy
Add a Name, Description, and Leave "Assign To" set to All Clients
Click Add Rule
Name it Default Auth Rule
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:
Open your Okta Configuration and update the Issuer to your new custom domain
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
Another possible cause of "The issuer [FOO] does not match [BAR]" is that Okta is caching previous values in the 'okta-cache-storage' item of your browser's Local Storage section. That's what happened to me and it took a really long time to discover.