PingOne

Setting up a custom domain

Before you create a CNAME record with your DNS manager, you must first create an entry for the custom domain in PingOne. PingOne provides a canonical name value that you will use to create a CNAME record for your domain name.

You can configure one custom domain per environment.

Before you begin

Before you begin, you’ll need the following:

  • An existing custom domain

  • Access to your DNS manager

  • A valid SSL certificate

Adding a custom domain

Add the custom domain to your PingOne environment.

Steps

  1. Go to Settings > Domains.

  2. Click Add custom domain.

  3. Enter the domain name, such as auth.example.com and click Save. PingOne validates the domain name to ensure that it is not already in use.

    Before the custom domain becomes active, PingOne requires that you provide an appropriate Secure Sockets Layer (SSL) certificate and point your custom domain to a PingOne-supplied canonical name using a CNAME record. The CNAME record proves that your custom domain is not already in use and directs requests to your custom domain through your PingOne environment.

Adding the CNAME to your DNS configuration

After you add the custom domain name, copy the canonical name from PingOne and add it to the CNAME record for your custom domain.

Steps

  1. Go to Settings > Domains.

  2. Click Verify domain.

  3. In the Verify Custom Domain window, copy the Canonical Name.

    Some DNS providers do not support a trailing period in the CNAME. If you are using one of these DNS providers, omit the trailing period from the CNAME record.

  4. Add the Canonical Name to the CNAME record for your custom domain.

    The canonical name will not have a DNS resolution until you complete the steps in Verifying the custom domain name and Adding an SSL certificate.

Verifying the custom domain name

Ensure that you have added a CNAME record to your DNS configuration before starting this task. You cannot 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. Go to Settings > Domains.

  2. Click Verify domain.

  3. In the Verify Custom Domain window, 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

PingOne verifies that the CNAME is associated with the custom domain name you entered. This association is needed to set up domain control and enable the functionality of a custom domain.

Adding an SSL certificate

To enable HTTPS for your custom domain, you need to add an SSL certificate from a certificate authority (CA). You can also use these steps to update a certificate that has expired. Learn more in Generating a CSR for a custom domain.

About this task

  • Do not use a self-signed certificate or a certificate signed by a CA that is internal to your own organization. Certificates must be signed by a globally trusted CA.

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

  • The certificate must be valid.

  • You can use wildcard and Subject Alternative Name (SAN) certificates, but they must match the domain name.

  • When reimporting a certificate, the key type and size cannot be changed.

Steps

  1. Go to Settings > Domains.

  2. Click Add an SSL certificate.

  3. 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.

Testing the custom domain

Test your custom domain to ensure that it resolves to the correct location. After you add a certificate, it can take up to several hours for the changes to propagate through the network.

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.