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 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
.
Custom domains also affect 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.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.
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:
Create the custom domain resource (for example, auth.acme.com).
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.
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.
Import the SSL certificate (chain, cert, private key).
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:
Open (or install) openssl on your computer.
Enter the following openssl
command:
openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr
Enter the following certificate signing request (CSR) information at the prompt:
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, see Custom Domains.
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. |
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. |
status |
String | N/A | Read-only | The status of the custom domain. Options are ACTIVE , VERIFICATION_REQUIRED , and SSL_CERTIFICATE_REQUIRED . |
Property | Type | Required? | Mutable? | Description |
---|---|---|---|---|
certificate |
String | Required | Mutable | The PEM-encoded certificate to import. The following validation is performed 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. |
To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.
Service | Event |
---|---|
branding | CUSTOM_DOMAIN.CREATED |
branding | CUSTOM_DOMAIN.UPDATED |
branding | CUSTOM_DOMAIN.DELETED |
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. |