PingOne

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 and Verifying that custom domain traffic is routing to Cloudflare 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 region 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 <uuid>.ping-ccd.com. Learn more in Creating SPNs and SPN reference.

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.

  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 and Adding a TLS/SSL certificate.

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). Learn more in Generating a CSR for a custom domain.

  • A minimum encryption of RSA-2048 or ECDSA-256 is required.

  • Don’t use a self-signed certificate or a certificate signed by a CA that’s internal to your own organization. Certificates must be signed by a globally trusted CA.

  • 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. Do not include the end-entity certificate.

  4. Click Save.

  5. 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. Do not 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. 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.

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.