--- title: Setting up a custom domain description: Create an entry for the custom domain in PingOne. component: pingone page_id: pingone:settings:p1_set_up_custom_domain canonical_url: https://docs.pingidentity.com/pingone/settings/p1_set_up_custom_domain.html revdate: March 04, 2025 section_ids: before-you-begin: Before you begin p1-add-custom-domain: Adding a custom domain steps: Steps p1-add-cname-to-dns-config: Adding the CNAME record to your DNS configuration steps-2: Steps p1-verify-custom-domain-name: Verifying the custom domain name steps-3: Steps result: Result p1-add-ssl-certificate-to-domain: Adding a TLS/SSL certificate steps-4: Steps result-2: Result next-steps: Next steps p1-enable-mtls-in-domain: Enabling mTLS for the custom domain (optional) steps-5: Steps result-3: Result disabling-mtls-for-the-custom-domain: Disabling mTLS for the custom domain p1-troubleshoot-domain: Troubleshooting your custom domain configuration steps-6: Steps p1-test-custom-domain: Testing the custom domain steps-7: Steps --- # Setting up a custom domain Before you create a Canonical Name (CNAME) record with your DNS manager, you must create an entry for the custom domain in PingOne. PingOne provides a CNAME value that you'll use to create a CNAME record for your domain name. | | | | - | ---------------------------------------------------- | | | You can configure one custom domain per environment. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Custom domains created after March 17, 2025 will use Cloudflare instead of Amazon CloudFront due to changes in our ingress infrastructure.If you are planning to use a reverse proxy or Web Application Firewall (WAF) with your Cloudflare custom domain, Cloudflare DNS cannot be the authoritative nameserver for your custom domain or the provider of the reverse proxy or WAF. Consult your network infrastructure team to determine if this might be an issue for your organization. Note that Cloudflare DNS could be in use directly or through an intermediate supplier.These limitations apply to all custom domains created since March 17, 2025, as well as to any CloudFront custom domains that you are considering for migration to Cloudflare.Review [Migrating a custom domain to Cloudflare](p1_migrate_custom_domain_to_cloudflare.html) and [Verifying that custom domain traffic is routing to Cloudflare](p1_verifying_custom_domain_traffic_to_cloudflare.html) for more information about assessing whether your network and firewall settings require updates to support the new infrastructure. | ## Before you begin Before you begin, you'll need the following: * An existing custom domain * Access to your DNS manager * A valid TLS/SSL certificate | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're using an LDAP gateway with Kerberos, you must add a Cloudflare SPN applicable for the geography in which your organization resides. If your custom domain was created between March 17 and August 11, 2025, you might need to add two Cloudflare SPN references. Custom domains created during that time period have unique references for each custom domain, such as `.ping-ccd.com`. Learn more in [Creating SPNs](../integrations/p1_creating_spns.html) and [SPN reference](../integrations/p1_spn_reference.html).If you don't add the SPN reference, a Kerberos outage can occur. | ## Adding a custom domain Add a custom domain to your PingOne environment. ### Steps 1. In the PingOne admin console, go to **Settings > Domains**. 2. Next to **Custom Domain**, click the **[icon: plus, set=fa]**icon. 3. In the **Configure Custom Domain** panel, enter a **Domain Name**, such as `auth.example.com`, and click **Save**. PingOne validates the domain name to ensure it isn't already in use. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before the custom domain becomes active, PingOne requires that you point your custom domain to a PingOne-supplied canonical name using a CNAME record and provide an appropriate TLS/SSL certificate. The CNAME record proves that your custom domain isn't already in use and directs requests to your custom domain through your PingOne environment. | ## Adding the CNAME record to your DNS configuration After you add the custom domain name, copy the CNAME record from PingOne and add it to your DNS configuration. ### Steps 1. In the PingOne admin console, go to **Settings > Domains**. 2. Click the custom domain entry to open the details panel. 3. In the **Cloudflare** section, copy the **CNAME Name** and **CNAME Value** entries and add them to your DNS configuration. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Some DNS providers don't support a trailing period in the CNAME. If you're using one of these DNS providers, omit the trailing period from the CNAME record.The CNAME won't have a DNS resolution until you complete the steps in [Verifying the custom domain name](#p1-verify-custom-domain-name) and [Adding a TLS/SSL certificate](#p1-add-ssl-certificate-to-domain). | ## Verifying the custom domain name Ensure that you've added the Cloudflare CNAME record to your DNS configuration before starting this task. You can't verify a custom domain until you update the DNS manager to add the CNAME record value, which consists of your domain name pointing to the canonical name that you copied from PingOne. ### Steps 1. In the PingOne admin console, go to **Settings > Domains**. 2. Click the custom domain entry and then click **Verify**. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The specifics of DNS configuration depend on your DNS manager. Changes to the DNS can take up to 24 hours to propagate through the internet, so you might need to click **Verify** multiple times over that period of time until the DNS record is found. | ### Result To set up domain control and enable the functionality of a custom domain, PingOne verifies that the Cloudflare CNAME record is associated with the custom domain name you entered. ## Adding a TLS/SSL certificate To enable HTTPS for your custom domain or update a certificate that has expired, make sure you've verified your custom domain and then add a TLS/SSL certificate from a certificate authority (CA) *(tooltip: \
\

An entity that issues digital certificates.\

\
)*. Learn more in [Generating a CSR for a custom domain](p1_generate_csr_for_custom_domain.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * A minimum encryption of RSA-2048 or ECDSA-256 is required. * Don't use a self-signed certificate. * The certificate chain leads to a globally trusted CA. If your certificate was issued by an intermediate CA, include the full intermediate certificate chain. Omitting it can cause validation errors for public clients, including PingOne services. * The certificate must be valid. * You can use wildcard and Subject Alternative Name (SAN) certificates, but they must match the domain name. | ### Steps 1. In the PingOne admin console, go to **Settings > Domains**. 2. Click the custom domain and then click **Add TLS/SSL Certificate**. 3. In the **Add TLS/SSL Certificate** modal, enter the following information: * **Private Key**: A PEM-encoded unencrypted private key that matches the certificate's public key. * **Certificate**: A PEM-encoded certificate to import. * **Intermediate Certificates**: A PEM-encoded certificate chain that leads to a globally trusted CA. | | | | - | ----------------------------------------- | | | Don't include the end-entity certificate. | 1. Click **Save**. 2. In the **TLS/SSL Certificate Added** modal, click **Continue**. ### Result A **Valid until** date is listed in the **TLS/SSL Certificate** section of the custom domain details panel, and a **TXT Record** entry is displayed in the **Cloudflare** section under the CNAME fields. One of the following status labels displays: * Setup in Progress The steps to prepare your custom domain have been completed, but the domain setup is updating in PingOne. Check back in 10 minutes. * []()Review Required The preparation for the domain can't be completed. If your custom domain isn't publicly accessible, possibly because it's behind a VPN or using reverse proxy, you need to complete domain control validation (DCV) for setup to complete. Copy the values from the **TXT Name** and **TXT Value** fields in the **Cloudflare** section of the details panel for the custom domain. Add these values to your DNS configuration. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If **Review Required** is still displayed after 10 minutes, try renewing your certificates again. If **Review Required** is still displayed after another 10 minutes, open a Support case. Don't continue with the migration until the issue is resolved. | After 10 minutes or so, the **Cloudflare Active** label should display, indicating that your custom domain is active and routing to Cloudflare. ### Next steps You can now update any applications you've configured to use the custom domain. ## Enabling mTLS for the custom domain (optional) To configure inbound traffic policies to match requests using a certificate's SHA-256 thumbprint, you must enable mTLS for the custom domain. | | | | - | ------------------------------------------------------------------------ | | | Only custom domains routing to Cloudflare can be configured to use mTLS. | To enable mTLS on the custom domain, do the following. ### Steps 1. In the PingOne admin console, go to **Settings > Domains**. 2. Click the custom domain entry to open the details panel. 3. In the **Mutual TLS (mTLS) Support** section, click **Enable Support**. 4. On the confirmation modal, click **Enable**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Changes might take up to 10 minutes to take effect.mTLS isn't compatible with some clients, including [Microsoft Entra ID hybrid join](../use_cases/p1_microsoft_entra_hybrid_join.html). Verify compatibility before enabling mTLS. | ### Result You can now configure inbound traffic policies to use mTLS thumbprint as a match criteria for requests. Learn more in [Adding or editing inbound traffic policies for custom domains](p1_configure_inbound_traffic_policies.html). ### Disabling mTLS for the custom domain To disable mTLS on the custom domain, do the following. 1. In the PingOne admin console, go to **Settings > Domains**. 2. Click the custom domain entry to open the details panel. 3. In the **Mutual TLS (mTLS) Support** section, click **Disable Support**. 4. On the confirmation modal, click **Disable**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Changes might take up to 10 minutes to take effect.Disabling mTLS can interrupt traffic to your custom domain if you've configured inbound traffic policies to use mTLS thumbprint as a match criteria. | ## Troubleshooting your custom domain configuration If a **Review Required** label is displayed on your custom domain instead of the **Cloudflare Active** label, traffic isn't routing to Cloudflare, and you need to add additional information to your DNS configuration. ### Steps 1. In the PingOne admin console, go to **Settings > Domains** and click the custom domain to open the details panel. 2. In the **Cloudflare** section, copy the values in the **TXT Name** and **TXT Value** fields and add them to your DNS configuration. 3. Import your TLS/SSL certificate again. Within 24 hours the **Cloudflare Active** label should be displayed in the details panel, indicating the custom domain setup is complete. ## Testing the custom domain Test your custom domain to ensure that it resolves to the correct location. It often takes only a few minutes after you add a certificate for the changes to propagate through the network, but could take up to 24 hours. ### Steps 1. Open a web browser, and enter the address of your custom domain, such as `https://auth.example.com/myaccount`. 2. Verify that you are presented with the sign-on screen for your application or other appropriate resource.