Table of Contents

Requesting a custom domain name for applications hosted in Pega Cloud

This content applies only to Cloud environments.

For your applications that are hosted in Pega Cloud®, a client can use a custom domain name that conforms to your enterprise standards. By using a custom domain name, users of your Pega Cloud-hosted applications see domain names that are familiar to them. For example, if a client already registered a domain (for example, www.CustomerSite.com), you can now host your Pega applications on CreditCard.CustomerSite.com instead of CreditCard-prod1.pegacloud.net.

The certificates that are generated by this process are protected and managed by Amazon Web Services (AWS) Certificate Manager (ACM).  ACM simplifies the certificate request and renewal process as well as secures each certificate’s private key using AWS Key Management Service (KMS).   

A client’s private key can never be exported or exposed which ensures a secure process. 

Certificate validation requirements

Every certificate must be validated. There are two methods available:

  1. DNS Validation
  2. Email Validation

Pega Cloud Services recommends every client utilize the DNS validation method. If a client does not have the ability to add a new record to your Domain Zone file, email validation is required.

Pega Cloud Services selects one of the two methods during the certificate request process based on your preference.

DNS validation

Pega Cloud Services selects DNS validation during the certificate request process. This method requires that the client has the ability to update their Domain Zone file with a CNAME record that references the certificate request. ACM uses this CNAME record to validate the certificate.

As long as the CNAME record remains intact, certificate renewal occurs automatically, eliminating the potential of the certificate expiring.

Email validation

Pega Cloud Services selects email validation during the certificate request process. ACM sends a validation email to a maximum of 8 contacts (see below). You must have access to one or more of these emails in order to validate the certificate. A client who prefers email validation must agree to following the terms of certification renewal, including the need to revalidate the certificate within 825 days. For details, see the AWS document, How Domain Validation Works.

ACM sends email to the 3 contact addresses listed in the WHOIS directory and an optional 5 common system addresses for each domain that you specify. This means ACM sends up to 8 email messages to registered and common contacts for every domain name and subject alternative name that you include in your request as shown below.

  • Registered Contacts:
    • Domain registrant
    • Technical contact
    • Administrative contact
  • Common Contacts:
    • administrator@your_domain_name
    • hostmaster@your_domain_name
    • postmaster@your_domain_name
    • webmaster@your_domain_name
    • admin@your_domain_name

Outline and details of the certificate validation

Certificate validation requires that Pegasystems, Inc and clients coordinate their efforts throughout the process as described below.

  1. The client makes a request by selecting New request in My Support Portal. For the latest documentation on making requests, see My Support Portal: New Design, Streamlined Features. Clients must provide the following information in the ticket:
  • Your custom domain name (for example, CreditCard.CustomerSite.com).
Pega Cloud recommends the use of Fully Qualified Domain Names (FQDN) and does not recommend the use of wildcard domains. 
  • Each environment for which a client wants to generate a certificate requires listing the Pega URL. For example, if you wanted certificates for both your prod1 and stage environments, you must provide both the pega URLS and your requested certificate | domain for each. Your SR must include the following details:
    • Production environment details: 
      • Pega URL: https://CreditCard-prod1.pegacloud.net/prweb
      • Requested Certificate | Domain: CreditCard.CustomerSite.com
    • Staging environment details:
      • Pega URL: https://CreditCard-stg1.pegacloud.net/prweb 
      • Requested Certificate | Domain: CreditCard.CustomerSite-stg.com
    • Your preferred certificate validation method, DNS or Email.
    • Your deadline for completing this request.
A client SR cannot be processed without including a preferred validation method; when a client does not provide a preferred method, Pega Cloud contacts the client confirm the certificate validation method before proceeding.
  1. Pega Cloud operations processes the client SR and generates a certificate request in ACM using the preferred validation method stated in the request:
  • For DNS Validations, Pega Cloud operations generates a DNS CNAME, attaches the record to your SR, and then instructs the client on how to add the record to their domain zone file. 
  • For Email Validations, ACM will send up to 8 emails for contacts listed in the domain registration. The client must respond to one of the emails within 72 hours.

After ACM validates the certificate request, either by looking up the new CNAME record or by you responding to the validation email, ACM generates the public certificate and private key. Pega Cloud operations then apply the public certificate and private key to the load balancers in your Pega Cloud environments . 

  1. Pega Cloud operations associates each validated SSL/TLS certificate with the appropriate environment. Pega Cloud operations leaves in place the Pega Cloud certificate so your previous URL (example, https://CreditCard-prod1.pegacloud.net/prweb) continues to work without service interruption.
  2. To resolve the new custom domain name, the client must add a CNAME record that points your custom domain name to the Pega Cloud Services domain name. For example: 

CreditCard.CustomerSite.com CNAME CreditCard-prod1.pegacloud.net.


After your custom domain name is set up, you can still resolve the original URL of your system, such as https://CreditCard-prod1.pegacloud.net/prweb. With your customer domain certificate and the Pega Cloud Services certificate in place, both URLs terminate SSL without any errors.

Certificate revocation

Clients can request the revocation of an ACM certificate that it has in service for one or more of their environments.  It is important to note that the revocation process removes the certificate from their environment. If a new certificate is not applied for the custom domain, the custom URL no longer works.

The certificate revocation process requires that Pegasystems, Inc and clients coordinate their efforts throughout the process shown below.

  1. The client files an SR using the Support Requests tab in the My Support Portal and provides the following information in the ticket:
  • New Certificate FQDN (Only if the old certificate is to be replaced).
  • Certificate Common Name (FQDN) to be revoked.
  • Customer URL
  1. Pega Cloud processes the client SR to revoke the certificate which includes the following steps:
    1. If a new certificate is to be applied, a new certificate request will be processed. Refer to requesting a new custom URL above.

       

      If Pega Cloud Services does not apply a new certificate before the old certificate is revoked, the client site using the custom URL can no longer be accessed by your customers. 

       

    2. Pega Cloud will remove the certificate to be revoked from all services to which it is applied. 
    3. Pega Cloud will delete the certificate from ACM
    4. Pega Cloud will notify the client via the SR that process has been completed.

For immediate questions or additional information, call the Pega Support Contact Information that is listed for your region.

Suggest Edit

100% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.