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

Custom domains affect only the endpoints on https://auth.pingone.com. Some examples when a custom domain is configured:

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.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.pingone.com.

After defining the CNAME record in the Domain Name System, you can verify the domain using the POST /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 /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, see Generating a CSR for custom domains for information about generating an SSL certificate.

Warning: Any applications that use a custom value for loginPageUrl must include the custom domain (plus another domain level) in the login URL. A custom domain shared by the environment and the loginPageUrl avoids issues with third-party cookies in some browsers. This configuration gives your PingOne environment the same parent domain as your authentication application. For example, for client-side custom login applications calling /{{envID}}/flows/{{flowID}}, if your parent domain is acme.com, you can set your environment’s custom domain to us.acme.com. Applications in the environment that use a custom loginPageUrl can set the value to share the top-level parent domain of acme.com plus another domain level, something like app1.acme.com or login.app2.acme.com.

For server-side calls to /{{envID}}/flows/{{flowID}}, the custom login application must be hosted at a domain that is a subdomain of the custom domain for the environment. For example, if the environment’s custom domain is us.acme.com, then the login application can be on a server at login.us.acme.com.

For more information about the loginPageUrl property, see Applications.

The examples that follow show common actions to find and manage custom domain entities. You need the Environment Admin role to perform operations on resources entities.

Property	Description
`certificate`	An object that specifies information about the SSL certificate used by this custom domain. If this property is not present, it indicates that an SSL certificate has not been setup for this custom domain.
`canonicalName`	A string that specifies the domain name that should be used as the value of the CNAME record in the customer’s DNS.
`certificate.expiresAt`	The time when the certificate expires.
`domainName`	A string that specifies the resource name, which must be provided and must be unique within an environment (for example, auth.shopco.com). This is a required property.
`environment.id`	A string that specifies the environment resource’s unique identifier associated with the resource.
`id`	A string that specifies the resource’s unique identifier.
`status`	A string that specifies the status of the custom domain. Options are `ACTIVE`, `VERIFICATION_REQUIRED`, and `SSL_CERTIFICATE_REQUIRED`.

Property	Description
`certificate`	A string that specifies the PEM-encoded certificate to import. This is a required property. The following validation is performed on the certificate: It must not be expired. It MUST not be self signed. The custom domain name MUST match one of the subject alternative name (SAN) values on the certificate.
`intermediateCertificates`	A string that specifies the PEM-encoded certificate chain.
`privateKey`	A string that specifies the PEM-encoded, unencrypted private key that matches the certificate’s public key. This is a required property.

Code	Message
200	Successful operation.
201	Successfully created.
204	Successfully removed. No content.
400	The request could not be completed.
401	You do not have access to this resource.
404	The requested resource was not found.

Custom domains data model

SSL certificate import request data model

Response codes