By default, Okta tenants use a subdomain under an Okta-owned domain name, which might not the best URL for multiple reasons. In this blog post, I go through the process of configuring a custom subdomain for your tenant and how to acquire a TLS certificate to secure said domain.
Okta is one of the major players in the identity and access management field, their access management and identity provisioning / automation features are widely used in all types of organizations. Knowing how to administer Okta is a valuable skill for system admins, but also security engineers.
This post explains how to configure custom domains for your Okta tenant, it also outlines the possible options for obtaining a TLS certificate that's required before you can configure a custom domain.
Configure The Custom Domain
- Login into your Okta account, switch to the Admin interface.
- Navigate to Settings → Customization
- Scroll a bit down until you find the Custom URL Domain section, click Edit.
We will need to verify our custom subdomain first, enter the subdomain in the field (see below) and continue.
Verify your domain
The next screen will provide a DNS record for domain verification, create the DNS record in your DNS management tool and wait until it propagates before clicking Verify.
Add Certificate Information
Once your domain is verified, move to the next step, the TLS certificate. Follow the steps outlined in the next section to obtain a TLS certificate, then fill in the fields with the proper information.
Create CNAME Record
The last step in this process is to create a CNAME record that will redirect traffic from your custom domain to the correct destination. Use the information provided in the screen below to create your DNS records.
Congratulations, you did it. Now you have a custom domain configured on your Okta tenant, which should improve your users' life a bit. Well done!!
Obtaining A TLS Certificate
we can only use subdomains as custom domains in an Okta tenant, and you must provide a TLS certificate before you can enable the custom domain. We have four different options to obtain a TLS certificate.
1. Use a commercial CA
The simplest option among the four. Simply buy a certificate for the subdomain you plan on using from any of the popular commercial Certificate Authorities and upload the content of the certificate and private key files to Okta before enabling the custom domain. That's it, you are done and can now celebrate 🎉🎉🎉
2. Let's Encrypt
If you prefer not to buy a certificate, and you don't mind performing manual renewal every 90 days, then you can use this option. Simply, request a certificate from Let's Encrypt using DNS Authentication. Once the certificate is issued, upload the private key and certificate files to Okta and enabled your custom subdomain.
🚨 Don't forget to add a calendar event for renewal every 55 days (just to be safe).
3. Let's Encrypt + Bash
If you aren't a big fan of manual renewals, you could use a bit of Bash magic to automate the process. You could use ACME to obtain the TLS certificate using DNS authentication, and then use Okta's API to upload the certificate to your tenant.
The only catch with this approach is that you need to perform the manual process at least once, so you can verify your subdomain and create it (which is a must before you can automate anything).
bdemers wrote a couple of Bash scripts that can help you automate this process, check them out using the link below. A couple of reminders:
- You will need to tweak the scripts with your URLs and data, drop me a message on Twitter if you need some help with that, and I will see what I can do.
- Don't forget to give some recognition to bdemers for this useful work.
4. Let's Encrypt + Lambda
It's possible to use AWS Lambda to obtain TLS certificates from Let's Encrypt. Arkadiy Tetelman wrote a wonderful blog post on how to do that. It's possible to use that information, make small modifications to the main.py, so it pushes the certificate to Okta instead of ACM, and you are golden to go.
I tried to cover this topic to the best of my ability. If you have any comments or suggestions, feel free to reach out to me through Twitter or Email. Otherwise, have fun and keep learning.
- Before you begin | Okta Developer
- okta.sh (github.com)
- How To Acquire a Let's Encrypt Certificate Using DNS Validation with acme-dns-certbot on Ubuntu 18.04 | DigitalOcean
- okta.sh (github.com)
- Deploying EFF's Certbot in AWS Lambda (arkadiyt.com)
- Welcome to the Certbot documentation! — Certbot 1.16.0.dev0 documentation (eff.org)