PingOne Platform APIs

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:

  • https://auth.pingone.com/{{envID}}/* becomes https://{{customDomain}}/*.

  • https://auth.pingone.asia/{{envID}}/as/authorize becomes https://{{customDomain}}/as/authorize.

Custom domains are not applicable to:

  • api.pingone

  • scim-api.pingone

  • orchestrate-api.pingone

  • uploads*.pingone

Custom domains can be applied to:

  • https://apps.pingone.com/{{envID}}/myapps/ becomes https://{{customDomain}}/myapps.

  • https://apps.pingone.com/{{envID}}/myaccount/ becomes https://{{customDomain}}/myaccount.

  • https://apps.pingone.com/{{envID}}/signon/?flowId={{flowID}} becomes https://{{customDomain}}/signon/?flowId={{flowID}}

  • https://apps.pingone.com/{{envID}}/verify/verify-webapp/index.html becomes https://{{customDomain}}/verify/verify-webapp/index.html.

  • The https://auth.pingone.com domain. For example:

    • https://auth.pingone.com/{{envID}}/* becomes {{customDomain}}/*.

    • https://auth.pingone.asia/{{envID}}/as/authorize becomes {{customDomain}}/as/authorize.

  • The https://apps.pingone.com domain. For example:

    • https://apps.pingone.com/{{envID}}/myapps/ becomes {{customDomain}}/myapps.

    • https://apps.pingone.com/{{envID}}/myaccount/ becomes {{customDomain}}/myaccount.

    • https://apps.pingone.com/{{envID}}/signon/?flowId={{flowID}} becomes {{customDomain}}/signon/?flowId={{flowID}}

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}}/v1/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}}/v1/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.

The canonicalName value will not have a DNS resolution until TLS (Transport Layer Security) is complete and the status changes to ACTIVE.

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.

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, refer to Application Operations.

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.

Generate a CSR for custom domains

If you use a custom domain, you need to create the custom domain resource in PingOne and import the SSL certificate used by the custom domain resource. In brief, the steps in PingOne to implement a custom domain are:

  1. Create the custom domain resource (for example, auth.acme.com).

  2. Create a CNAME record in the acme.com DNS for auth.acme.com that points to the canonical name when the custom domain was created.

  3. If you do not have an SSL certificate, outside of PingOne, generate a certificate for auth.acme.com (a certificated request that is signed by a certificate authority), which results in a private key, certificate chain, and certificate.

  4. Import the SSL certificate (chain, cert, private key).

Generate an SSL certificate

If you do not have an SSL certificate, which is referenced in step 3, follow these steps to create the trusted SSL certificate for the custom domain:

  1. Open (or install) openssl on your computer.

  2. Enter the following openssl command:

    openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr

  3. Enter the following certificate signing request (CSR) information at the prompt:

    • Common Name (CN)

    • Organization

    • Organization Unit (OU)

    • City (or Locality)

    • State (or Province)

    • Country

  4. Submit your CSR to a Certificate Authority (CA) for validation.

After validation, the CA returns the trusted SSL certificate, which you can import to complete and enable the custom domain. For information about custom domains, refer to Custom Domains.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Custom domains data model

Property Type Required Mutable Description

certificate

Object

N/A

Read-only

Contains 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

String

N/A

Read-only

The UUID of the domain name used as the value of the CNAME record in the customer’s DNS. In a response, PingOne resolves this to ".edge1.pingone.com".

certificate.expiresAt

Date

N/A

Read-only

The time when the certificate expires.

domainName

String

Required

Immutable

The resource name, which must be provided and must be unique within an environment (for example, auth.shopco.com).

environment.id

String

Required

Immutable

The UUID of the environment associated with the resource.

id

String

N/A

Read-only

The UUID of the custom domain.

mtlsEnabled

Boolean

Optional

Mutable

A boolean that specifies whether the custom domain supports the use of mTLS when establishing connections to PingOne.

status

String

N/A

Read-only

The status of the custom domain. Options are ACTIVE, VERIFICATION_REQUIRED, and SSL_CERTIFICATE_REQUIRED.

cloudflareCanonicalName

String

N/A

Read-only

The Cloudflare canonical name to be used in the CNAME record for the custom domain.

cloudflareTxtDcv.txtName

String

N/A

Read-only

The TXT name used for Cloudflare TXT Domain Control Validation (DCV).

cloudflareTxtDcv.txtValue

String

N/A

Read-only

The TXT value used for Cloudflare TXT Domain Control Validation (DCV).

SSL certificate import request data model

Property Type Required Mutable Description

certificate

String

Required

Mutable

The PEM-encoded certificate to import. 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

String

Required

Mutable

The PEM-encoded certificate chain.

privateKey

String

Required

Mutable

The PEM-encoded, unencrypted private key that matches the certificate’s public key.

Custom domain events generated

Refer to Audit Reporting Events for the events generated.

Response codes

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 domain errors

In addition to the general error codes, custom domain operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /customDomains request omits the domainName property or supplies a domainName that is not a valid domain name with a valid TLD, ends with a dot, contains non-ASCII characters, or contains uppercase characters, or a POST /customDomains/{customDomainID} (import certificate) request supplies values that fail the certificate checks — a certificate that is not a valid X.509 PEM-encoded certificate or is self-signed, is expired, is not yet valid, has an RSA key size below 2048 bits or an ECDSA key size below 256 bits, or includes a certificate chain; an intermediateCertificates value that is not a valid X.509 PEM-encoded certificate chain; a privateKey that does not include the RSA private key header and footer or is not Base64-encoded; or a certificate whose hostname does not match the custom domain name

Details: Describes the failing property; for example must be a valid domain name with a valid TLD, cannot end with a dot, cannot contain non-ascii characters, or cannot contain uppercase characters (each on target domainName), not a valid X.509 PEM-encoded certificate, RSA key size must be >= 2048 bits, ECDSA key size must be >= 256 bits, a certificate chain was provided, self-signed certificates are not allowed, certificate is expired, or certificate is not yet valid (on target certificate), not a valid X.509 PEM-encoded certificate chain (on target intermediateCertificates), does not include RSA private key header/footer or private key must be Base64-encoded (on target privateKey), or Custom domain hostname does not match the provided certificate

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /customDomains request creates a custom domain in an environment that already has one, or supplies a domainName that already exists in another environment in the same geography

Details: An environment can have at most one custom domain. with target environmentId, or A custom domain with this domain name already exists in another environment with target domainName

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /customDomains/{customDomainID} (verify) request runs when the domain’s status is not VERIFICATION_REQUIRED, when no CNAME record is found with the expected domain alias value, when the authoritative name servers return an error, or when DNS propagation is not complete, or a POST /customDomains/{customDomainID} (import certificate) request runs when the domain’s status is not SSL_CERTIFICATE_REQUIRED or ACTIVE

Details: Describes the verification or import failure; for example custom domain does not need to be verified, No CNAME records found with matching canonical name, No response from authoritative name servers, Error response from authoritative name servers: <rcode>, or Custom domain status must be 'SSL_CERTIFICATE_REQUIRED' or 'ACTIVE' in order to import a certificate

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The environment lacks the capability to operate on custom domains (POST, verify, import, and PUT operations)

Details: The request exceeded your license limit.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the branding:create:customDomain permission (POST /customDomains), the branding:read:customDomain permission (GET operations), the branding:update:customDomain permission (the verify and import POST /customDomains/{customDomainID} operations and PUT /customDomains/{customDomainID}), or the branding:delete:customDomain permission (DELETE /customDomains/{customDomainID})

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, POST (verify or import), or DELETE /customDomains/{customDomainID} request references a custom domain that does not exist in the environment

Details: None.

415

INVALID_REQUEST

None

Message:

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
When and details

When: A verify or import request omits the required custom media type Content-Type header (application/vnd.pingidentity.domainName.verify+json for verify, application/vnd.pingidentity.certificate.import+json for import), or any request supplies an unsupported Content-Type

Details: None.

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: A verify request cannot reach the authoritative name servers, or the service fails to process the request

Details: None.