Okta Custom Domain Configuration with Let’s Encrypt Certificates

UPDATE 11/09/2023:

Okta has now the let’s encrypt option built in. You can register your customer domain as per below.

If you had a let’s encrypt domain certificate simply delete the domain and register it again following the steps below:

This guide will walk through the process of changing your Okta URL to a custom domain.

In this guide, I’ll be using my domain hogwartsadmin.com, which has been purchased through GoDaddy, Let’s Encrypt (TLS Certificate) and Google’s Dig for (DNS Lookup).

Step 1: Decide on and enter custom domain name in your Okta Tenant

Once in the Admin Portal for your tenant, navigate to:

Customization → Custom URL Domain → Select Edit → Select Get Started

Enter the custom domain name you would like to use. For example, I’ll be setting my tenant to use: sso.hogwartsadmin.com

Step 2: Verify domain name ownership

You will need to copy the verification value provided by Okta and add it as a TXT type record for your domain.

In GoDaddy, you can do this by navigating to your domain and selecting Manage DNS. In GoDaddy you do not need to include the domain name, only _oktaverification.subdomain (_oktaverification.sso in this example)

To verify this has been configured correctly, you can use Google’s Dig to confirm the DNS update.

Once verification can be searched and seen by Google’s Dig, return to Okta and select verify. If successful you’ll be able to continue forward with setup.

Step 3: Create TLS Certificate and Upload to Okta

If this domain will be used as a demo or POC account, you likely won’t want to pay for a TLS certificate.

If this is the case, Let’s Encrypt is a great and free option to obtain a certificate. This will allow you to use your custom domain for Okta authentication, but the certificates are short lived and will need to be renewed at least once every three months.

Install Let’s Encrypt

You can check if your hosting provider supports Let’s Encrypt, but if not you’ll have to install certbot and use the manual mode to generate the certificate. GoDaddy does not support Let’s Encrypt, so I’ll be using the manual mode in this example.

I am on a MacOS with homebrew already installed, so installation was a single command via terminal: brew install certbot

If you do not have homebrew installed or you are on a different OS, you can find the instructions for setup by selecting your system and following the instructions provided by certbot.

Generate the Certificate and Private Key via the Command Line

The specific command typed in may look different depending on OS devices, the below commands are based on MacOS. If you’re using a different OS, the certbot install instructions also include instructions for running the certbot if needed.

The specific command typed into the terminal is:

sudo certbot certonly –manual -d login.ebden.page –manual-public-ip-logging-ok –preferred-challenges dns –key-type rsa

You will need to enter your password for the sudo command.

You do not have to specify domain (-d) or manual-public-ip-logging-ok in the initial command as certbot will prompt you for this information. However, you must specify preferred-challenge if you want to switch to dns.

Note: Selecting DNS, means that I can verify domain ownership by adding a TXT record to my domain, exactly the same way we verified ownership for Okta. There is also an http method (default) that requires you place a file with a specific name and specific content in the top level directory file of your webserver. Given these two options, I find dns to be easier.

Note2: Let’s Encrypt Certbot default key type is changed to ECDSA with the latest version 2.0.0. Hence you have to specifiy –key-type rsa to comply with Okta custom domain cert requirement to be RSA type Cert.

Once the command is typed in, you’ll be prompted to add the TXT record with a specific value for domain ownership verification.

Note: Prior to the verification prompt, you will first have to enter your password to use the sudo command.

Add a TXT record for _acme-challenge.subdomain (in this example _acme-challenge.sso) and the value specified to your domain.

Leverage Google’s Dig to verify the TXT value is deployed.

Once verified, press enter to continue. If successful, you’ll see the following message with the location of your certificate and key file.

Copy the Certificate, Chain and Key File into Okta

You can open the files using whatever method you prefer, but in this example, I’ll be using ‘cat’ to view the file contents:

sudo cat /etc/letsencrypt/live/sso.hogwartsadmin.com/fullchain.pem

Partial screenshot of first certificate.

In the fullchain.pem file there should be two certificates enclosed with Begin Certificate and End Certificate. Starting with the first Begin Certificate line, copy the full block (including the first End Certificate line) into the Certificate (first) field on the Okta Upload Your TLS Certificate screen.

Copy the second certificate block and paste that into the Certificate Chain (optional) field in Okta. This is the third and final field on this screen.

Open the key file (privkey.pem) and follow the same process, copying from Begin Private Key to End Private Key and pasting the value in the Private Key (second) field in your Okta tenant.

Upon completion, all fields on the screen should be populated. Press Next.

Step 4: Set Custom Domain as Alias for your Okta Domain

On the next screen, you’ll be shown information to be added as a CNAME record in your domain.

Copy the values and return to GoDaddy (or your domain service) and create a CNAME record. Although the host provided by Okta includes the full domain, you will only need to add the subdomain if using GoDaddy.

Return to Google’s Dig to verify the CNAME is present with the correct value.

Once the value can be seen in Google’s Dig, return to your Okta tenant and select Finish.

Step 5: Verify custom domain is working

Open an incognito window or a new browser and type in your url to confirm it redirects to your Okta page.

I have not customized the landing page shown below, but the custom domain can be seen in the url bar with the Okta Hosted widget.

Note: The update happened immediately for my custom url, but may take up to 48 hours

Credit to heatherwallander for this blog.