Configure a custom URL domain Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka00z0000019tfzsau&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fconfigure-a-custom-url-domain-649159225
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Configure a custom URL domain
Published: May 15, 2018   -   Updated: May 15, 2018

okta-doc-source

This is an Early Access feature. To enable it, please contact Okta Support.

Configure a custom URL domain


Settings > Customization

You can customize your Okta org by replacing the Okta domain name with a custom URL domain name that you specify. For example, if the URL of your Okta org is https://example.okta.com, you can configure a custom URL for the org such as https://id.example.com.

CustURL_WizardFlow

Prerequisites
  • Domain name
  • Subdomain name. More
  • Okta uses CNAME DNS records to point to your Okta org. Because DNS does not allow you to set a CNAME record for a domain (for example, example.com), you must create CNAME records for subdomains (such asid.example.com).

  • TLS certificate for your subdomain (PEM-encoded)
  • Private key (PEM-encoded)
  • A valid TLS certificate is required to configure a Custom URL domain. Depending on your organization's policies, developers and administrators must have access to your organization's certificates or a certificate authority.
  • If your org uses any of the following components, additional configuration may be required:
    • Custom Authorization Servers for API management
    • Issuer for OIDC clients
    • Social IdP Redirect
    • Okta Verify

Caveats
  • Currently, this feature is intended primarily for software developers integrating custom applications through the Okta API. While IT administrators provisioning apps to the Okta end user dashboard can configure a custom URL, they should be aware that the following components are not supported with Custom URL Domains:
    • Okta Mobile (iOS, Android)
    • Okta Secure Web Authentication browser plugin
    • Okta IWA web app for Desktop SSO
    • Okta Active Directory agent
    • Okta LDAP agent
  • After you modify your DNS records, it may take up to 24 hours for your changes to propagate. If your changes do not appear within 24 hours, return to the CNAME step in the wizard and confirm your settings.

  • Depending on your registrar, you must enter either a long or short value for Host in the DNS step of the configuration wizard. If your registrar does not support the value you entered, verification will fail and your custom URL domain configuration will be incomplete.
  • You must configure this feature in order for Okta's Custom Sign In Page and Custom Error Page features to work.
  • Only one custom URL is allowed per Okta org.
  • If you use Let's Encrypt to become familiar with this feature, be aware that their certificates are valid for only 90 days. For a more permanent TLS certificate, you must generate one yourself and have it signed by a provider like Namecheap.

Procedure
  1. Obtain the certificate and private key described in Prerequsites.
  2. Go to Settings > Customization.

  3. Scroll down to Custom URL Domain and then click Edit.

    • The Continue button appears if the configuration is incomplete.
    • The Update Certification button appears if a custom URL domain is already configured for your org. To delete the current configuration, click Restore to default.
  4. Click Get Started to start the configuration wizard.
  5. DOMAIN
    1. Enter your domain and sub-domain name. For example, id.example.com.
    2. Click Next.

    DNS RECORDS

    CustURL_TXT-values_id

    1. Copy the value provided in the Host column.

      Important: Depending on your registrar, you may only need to enter _oktaverification instead of _oktaverification.id.example.com. Some registrars require the longer value, others the shorter value. If your registrar does not support the value you entered, verification will fail and your custom URL domain configuration will be incomplete.

    2. Log in to your Domain Name registrar.
    3. Locate the option to modify your DNS records and add a TXT record by pasting the value you copied from the Host column.
    4. Wait for the DNS record to propogate (typically 1 - 5 minutes, but it may take longer), and then return to Okta and click Verify to prove to your Domain Name registrar that you have rights to use the domain name.

      Note: After you modify your DNS records, it may take up to 24 hours for your changes to propagate. If your changes do not appear within 24 hours, return to this step and confirm your settings.

    5. If Verified appears, click Next.

    CERTIFICATION
    1. Paste your certificate in the Certificate field.
    2. Paste your private key in the Private Key field.
    3. CustURL_Cert-PrivKey

    4. If applicable to your environment, Okta recommends that you enter a PEM-encoded certificate chain (if any) in the Certificate Chain field.

      CustURL_Cert-Chain

    5. Click Next.

    CNAME
    1. Return to your Domain Name registrar and again locate the option to modify your DNS records.
    2. Add a CNAME record and paste the Host (Name) and Data (Value) values provided in the CNAME table in Okta.

      CustURL_CNAME-values_example

    3. Save your DNS record.
    4. To confirm that Okta is serving traffic over HTTPS (TLS) to your domain, wait for your updated DNS record to propagate, return to the CNAME step in Okta, and then click your custom URL under Confirmation.

      Note: After you modify your DNS records, it may take up to 24 hours for your changes to propagate. If your changes do not appear within 24 hours, return to the CNAME step in the wizard and confirm your settings.

    5. CustURL_ClickToTest

    6. Click Finish.

Flush the cache
  • Google DNS – Reset Google’s DNS cache for your domain using this tool.
  • OpenDNS – Reset the OpenDNS cache for your domain using this tool.
View configuration details
  • To view the details of your custom URL configuration, go to Settings > Customization and scroll to the Custom URL Domain section.
  • CustURL_ReviewConfig

  • If you're using MacOS, you can run the following command to see dig output for a properly configured domain:
  • $ dig id.example.com

    CustURL_DigOutput


Post a Comment