Settings > Customization
You can customize your Okta orgThe Okta container that represents a real-world organization. by replacing the Okta domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). 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.
- Domain name
- Subdomain name. More
- TLS certificate for your subdomain (PEM-encoded)
- Private key (PEM-encoded)
- To configure a Custom URL, some developer(s) and administrator(s) in your org must have access to your organization's valid TLS certificate or a certificate authority (assuming that is permitted by your organization's policies).
- Wildcard certificates must specify the full URL in the CN or SAN before the certificate is generated. For details, see Caveats.
- If you blacklist localhost IP 127.0.0.1 from your network, you must remove it from the network blacklist before you configure a custom URL domain. You can add it again after you've configured your custom URL domain. See Caveats.
- 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 IdPAn acronym for Identity Provider. It is a service that manages end user accounts analogous to user directories such as LDAP and Active Directory, and can send SAML responses to SPs to authenticate end users. Within this scenario, the IdP is Okta. Redirect
- Okta Verify
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 as id.example.com).
- Only one custom URL is allowed per Okta org.
- Intended users – Currently, this feature is intended primarily for software developers integrating custom applications through the Okta API, but IT administrators provisioning apps to the Okta end user dashboard can configure a custom URL.
- URL variations– The Custom URL changes when navigating between the adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. console and the end user dashboard. End usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using chiclets to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. will not see this variation.
- Not supported with SWAAn acronym for Secure Web Authentication. SWA is a SSO system developed by Okta to provide single sign-on for apps that don't support proprietary federated sign-on methods or SAML. Users can enter their credentials for these apps on their homepage. These credentials are stored such that users can access their apps without entering their credentials each time. When users first sign-in to a SWA app from their homepage, they see a pop-up message asking if they were able to sign-in successfully. plugin – Custom URL Domains are not supported for use with the Okta Secure Web Authentication browser plugin.
Give your DNS changes time to propagate – 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.
- Length of Host value in DNS step – 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.
- Chain file length – Certificate chain files can contain keys up to 4096 bits in length.
- Other features' dependency – You must configure this feature in order for Okta's Custom Sign In Page and Custom Error Page features to work.
- Error possible when using wildcard certificates – Okta performs validation checks on the certificate you upload. If your TLS certificate is a wildcard certificate, it must have included the full URL in the CN (Common Name) or SAN (Subject Alternative Name) when it was generated. Otherwise, the following error occurs when you attempt to upload the certificate:
- Let's Encrypt limitation – 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.
- Temporarily remove 127.0.0.1 from the network blacklist.
- Configure your custom URL domain as described in this document.
- Add 127.0.0.1 back to the network blacklist.
If you are using the Custom URL feature and integrating with one of the Okta agents, take note of the following:
- Agents – Need to be installed against the actual domain (example.okta.com), not the custom domain (example.customname.com). This applies to all agents.
- If using IWA SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones. – You should modify the web.config file to include the custom url. The configuration will continue to work without these modifications, but it could cause confusion for your end user if their sign-in attempt fails and they end up on a different domain.
- If you are using Agentless DSSO – Because you can only specify one SPN when setting up Agentless DSSO, you should ensure that all your sign-in flows and browser bookmarks use the URL you want ADSSO to use.
The specified certificate does not match your Custom URL Domain.
If you receive that error, consult the person in your organization responsible for generating the certificate to determine whether your TLS certificate is a wildcard type. If so, make sure the full URL in the CN or SAN is specified before the certificate is regenerated.
- Obtain the certificate and private key described in Prerequsites.
Go to Settings > Customization.
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.
- Click Get Started to start the configuration wizard.
- Enter your domain and sub-domain name. For example, id.example.com.
- Click Next.
- Copy the value provided in the Host column.
- Log in to your Domain Name registrar.
- Locate the option to modify your DNS records and add a TXT record by pasting the value you copied from the Host column.
- 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.
- If Verified appears, click Next.
- Paste your certificate in the Certificate field.
- Paste your private key in the Private Key field.
- If applicable to your environment (required for use with Okta Mobile for Android; see note below), Okta recommends that you enter a PEM-encoded certificate chain (if any) in the Certificate Chain field.
- Click Next.
- Return to your Domain Name registrar and again locate the option to modify your DNS records.
- Add a CNAME record and paste the Host (Name) and Data (Value) values provided in the CNAME table in Okta.
For example, depending on what type of Okta org you have, the Data value should look similar to the following:
org.Subdomain.customdomains.okta.com org.Subdomain.customdomains.oktapreview.com org.Subdomain.customdomains.okta-emea.com
- Save your DNS record.
- 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.
- Click Finish.
- To view the details of your custom URL configuration, go to Settings > Customization and scroll to the Custom URL Domain section.
- If you're using MacOS, you can run the following command to see dig output for a properly configured domain:
$ dig id.example.com