Custom Domains

PingOne supports the mapping of customer-owned and controlled domain names that are used to access user interfaces and services. You have the ability to route your own domain name alias to PingOne hosts, removing all references to "pingone" in the URLs (including the environment ID).

Companies typically consider domain names associated with their company as essential and valuable brand assets. They do not want vendor domains visible on sites visited by their customers. If a request to a vendor is visible to their customers, such as authentication requests to Ping Identity, companies want the domain in that request to be a corporate domain and not a vendor domain (for example: auth.pingone.com).

The custom domain feature enables such domain substitution.

Custom domains affect only the authorization endpoints on https://auth.pingone.com and the web verification endpoint on https://apps.pingone.com. Some examples when a custom domain is configured:

Custom domains are not applicable to:

Custom domains can be applied to:

For example, if your company domain is acme.com and you want to use auth.acme.com for your custom domain, you can create a custom domain resource, passing in auth.acme.com. When the custom domain resource is created, the status value is set to VERIFICATION_REQUIRED and the response returns a canonicalName property value that looks similar to this: 1234-abcd-5678-efgh.edge1.pingone.com. However, before you can verify the domain, you must first create a record with the Domain Name System (DNS) to describe how traffic is routed for the domain. The DNS record identifies the domain, and it requires a CNAME record value, which is a name-value pair consisting of your domain name pointing to the PingOne canonicalName property value returned by the create request. In this example, the CNAME record resolves auth.acme.com to the canonical name, 1234-abcd-5678-efgh.edge1.pingone.com.

After defining the CNAME record in the Domain Name System, you can verify the domain using the POST {{apiPath}}/environments/{{envID}}/customDomains/{{customDomainID}} request with the application/vnd.pingidentity.domainName.verify+json custom media type (and an empty request body). Be aware that after entering the CNAME record, it can take some time to propagate to the DNS servers, which can result in a request failure during this period. When successful, the response returns a status of SSL_CERTIFICATE_REQUIRED, which requires an SSL certificate import action.

To import the certificate, you can run the POST {{apiPath}}/environments/{{envID}}/customDomains/{{customDomainID}} request again using the application/vnd.pingidentity.certificate.import+json custom media type in the request header. The body for this request must specify the certificate, the certificate chain, and the private key. If successful, the response returns a status of ACTIVE to indicate that the custom domain has been verified and is active. Again, be aware that it can take some time before the custom domain is operational.

If you do not have an SSL certificate for the custom domain, refer to Generate a CSR for custom domains below for information about generating an SSL certificate.

For web-based verification, PingOne Verify service permits custom domains for the webVerificationUrl returned by the Create Verify Transaction request. The service then serves the web verification single-page app (SPA) from verify.customer-domain.com instead of apps.pingone.com. The service also uses that domain in all SMS messages, email messages, and the QR code during web verification. The custom domain status must be ACTIVE and certificate must be unexpired.