How to set up an Okta custom URL domain

In this post, I will walk through the information and steps required to set up an Okta custom domain. I’ll also reveal the issues that may get in the way and how to address them.

Okta is a leading cloud IAM solution and offers a free developer account. Anyone can register and use its service as long as the active monthly user count doesn’t go over 1000 in the developer’s account. After registration, Okta will assign an URL domain in a format of “https://dev-xxxxxx.okta.com" (xxxxxx is a randomly assigned number), where you can login and manage your own Okta services. If you are a paying customer, then you can choose a custom naming in such way as “https://custom.okta.com".

It’s essential to set up a custom URL domain so that your Okta domain would look like a subdomain of your own such as “https://login.mydomain.com". Setting up a custom domain would allow you:

• • Use of the custom domain as the issuer for the Okta default or custom authorization server so that you can have the authorization process appears as the same domain as your web application
• • Customization of Okta SignIn widget and this cannot be done without a custom domain
• • Not necessarily exposing Okta as your IAM solution vendor

The prerequisites of setting up custom domain for your Okta account are:

• • Ownership of the domain and sub-domain to serve as the Okta custom domain
• • An HTTPS/TLS certificate, private key and chain files that to be applied to your domain and sub-domain. The private key has to be PEM encoded in 2048 bits.

Most of the website management services such as Wordpress or hosting services such as Netlify, GoDaddy would provide the HTTPS out of the box for your site using “Let’s Encrypt”, but they would not allow to download the certificates behind the site. And, neither can you gain shell access to the servers to create and install your own certificates. Then the only option it leaves is to create the certs in your own machine and upload them to the hosting servers, which most of the vendors would be able to provide on their management panel.

ZeroSSL is a free SSL tool just does the HTTPS/TLS certs generation. ZeroSSL offers the online tool to generate certificates and the private key. But the online tool only generates 4096-bit private key and Okta requires the private key to be PEM encoded in 2048 bits. Therefore we will have to download the tool and generate them manually with custom options.

Generate certificates and keys

Here are the steps required to creates HTTPS/TLS certs for your hosting site as well as Okta for a custom URL domain.

1. Download ZeroSSL tool. For simplicity, take the Windows version, as it’s portable and requires no installation at https://github.com/do-know/Crypt-LE/releases.

2. Generate certs and keys using the following command:

.\le64.exe --key account.key --csr mydomain.csr --csr-key 
mydomain.key --crt mydomain.crt --domains 
"login.yourdomain.com,yourdomain.com" --generate-missing --
handle-as dns --legacy --api 2 --live

Explanation:

• • account.key: account private key
• • mydomain.key: domain private key. account.key and mydomain.key are private keys and can be generated using openssl. The downloaded tool “le” can also generate them.
• • mydomain.csr: certificate signing request file for the domain requested
• • mydomain.crt: certificates for the domain requested
• • mydomain.ca: not in command line but will be generated at the end as option “ — legacy” is used. This is called the issuer’s certificate file, or CA certificate or intermediate cert.
• • handle-as dns: this option asks for domain verification instead of http verfication. Http verification will generate two files which need to be uploaded to your website. Domain verification option will generate challenge key/value pair for TXT record verification on your domain.
• • generate-missing: this option will generate specified files if they don’t exist yet
• • legacy: this is important and it’s mandatory to successfully upload generated certs to Okta custom domain setup. As Okta requires 2048 bit key, legacy option will result in using 2048 bit key and placing the issuer’s certificate separately in its own .ca file.
• • api 2: this option will use version 2 API. Wildcard in domain is only supported in v2.0 such as “*.mydomain.com”
• • live: this option is used to run the actual generation process. It’s advised to “test” the process without the live option first.

Check https://zerossl.com/usage.html for more reference if needed.

During the process, the command will generate two challenge key/value pairs as two domains (sub-domain and main domain) that are defined in the command. The key/value pairs need to be inserted to your domain management using TXT record for verification. Only after the domain is verified can the subsequent certs be generated successfully.

After the certs are generated, first thing to do is to update them in your own domain. Next I will show how to configure the custom domain in Okta.

Note that the generated certs will expire in 90 days. It’s important to renew the certificates a few days before they expire. Auto-renew can be setup only if the shell access is available to your domain servers.

To learn more about configuring Okta for a custom URL domain and view photos, view the full article here: https://www.logic2020.com/insight/tactical/how-to-set-up-okta-custom-url-domain