Custom Certificates on Pantheon Advanced and Global CDN
For contract customers who require dedicated, custom TLS certificates.
Discuss in our Forum Discuss in SlackThis article provides an overview of the steps to set up and work with manually managed, custom certificates through Pantheon's Global CDN and Advanced Global CDN, available through Pantheon's Custom Certificates concierge service.
Custom Certificates service is available to contract customers, including Elite, Enterprise, Higher Education, and Resellers. To get started, contact your account manager or our Sales Team.
Add a Custom Certificate
Follow the steps below to request and send the appropriate certificate, and private key information for AGCDN where applicable:
Send the CSR to Your CA
Approximately two business days after a closed contract, the Pantheon Onboarding Team will provide you with the CSR file, to pass on to your Certificate Authority (CA).
Allow two business days for your Account Team to load the certificate.
CSR Notes
You must use a Pantheon-generated CSR. This is a hard requirement. If you already have a certificate, it will need to be re-keyed to match the CSR we provide.
Your CA must accept the CSR Pantheon provides. If your CA fails to accept our CSR, you will not be able to use it to generate a certificate. The CA GlobalSign does not currently meet this requirement. The workaround is to use another CA.
Streamlined AGCDN
This procedure also applies for customers who use Streamlined AGCDN. Pantheon staff uploads your certificate and the related domains are marked or show an indicator the same way regular domains with custom certificates do.
You can use the self service tool to add your custom certificate if you have a legacy AGCDN setup.
Before You Begin
Make sure you have your certificate bundle ready:
- Main certificate
- Intermediate certificate
- Private Key
Note: The platform currently only accepts 2048-bit RSA keys. AGCDN custom certificates (and private keys) must be in .PEM format.
Navigate to your Customer Cert Management account and log in.
Note
You must contact Professional Services to have your account created for you if you don't have an existing account.
Optional. Click Upload New Key, paste your key into the Key field, enter a name for the key in the Key name field, and then click Upload. Note that this step is required if your certificate has a private key. You can click the Refresh Key List button to see the newly added key.
Click Upload New Cert, paste your certificate and intermediate certificate into the appropriate fields, and then click Upload. Both certificates must be in
.PEMformat. You can click Refresh Cert List to see the newly added certificate.
As an alternative, you can also submit the certificate bundle to Pantheon Support to upload. You must allow two business days for your Account Team to load the certificate.
Add the Domain
Next, add the domain to your environment.
If you are presented with the option to Verify your domain to provision HTTPS, skip the verification by clicking Skip to updating DNS.
Once the certificate is in place, you will see the following under Details for your domain(s):
Test Before Going Live
Test production domain(s) before updating DNS by overriding DNS on your local computer from your local hosts file:
Note that modifying the hosts file usually requires administrative privileges from the OS.
The location of the hosts file varies depending on your operating system:
- MacOS / Linux:
/etc/hosts - Windows:
C:\\Windows\System32\Drivers\etc\hosts
Add lines to your operating system's hosts file in the following format:
203.0.113.10 example.com
203.0.113.20 www.example.comIn the example above, replace the IP addresses with those provided by Pantheon, and the domains with your own.
For non-production domains, test on any environment (Dev, Test, Live or Multidev), just make sure to include the non-production domains on your certificate. We are happy to provide a new CSR if your original CSR and certificate did not initially non-production domains.
Disable Let's Encrypt with CAA Records
A Certification Authority Authorization (CAA) record is used to specify which certificate authorities (CAs) are allowed to issue certificates for a domain. In order to ensure your custom certificate is served for all traffic, you must prevent Let’s Encrypt from issuing certificates.
You have two options to prevent Let’s Encrypt from issuing certificates for domains on your custom certificate:
- An empty CAA policy
- CAA records permitting your CA, but not Let’s Encrypt
To help generate CAA records, please see the free online tool: https://sslmate.com/caa/
CAA records configured for the root domain (e.g., example.com) are inherited by subdomains (e.g., www.example.com, blog.example.com, etc.). Disabling Let's Encrypt for the root domain will disable subdomains.
Issue: A Let's Encrypt Certificate is being served instead of the custom certificate
If a Let's Encrypt Certificate is deployed before the CAA record preventing it, contact Pantheon Support for assistance. Please allow at least 3 business days for Pantheon to resolve the Let's Encrypt Certificate.
Update A and AAAA Records
Update A and AAAA records provided by Pantheon Support. Note that even for subdomains, A and AAAA records are required. Do not use a CNAME record.
Renew or Replace a Custom Certificate
About 45 days before your custom certificate expires, Pantheon will open a ticket with your team with a new CSR. You can send that CSR to the Certificate Authority to generate new certificates (as described above for bringing a custom certificate).
To update a certificate with additional domains, contact Pantheon Support with the following details:
- The current common name (CN) and any SANs
- A colon-separated list of domains the certificate is valid for
- The updated certificate attached
It may take up to two business days to process the request.
Remove a Custom Certificate
All sites require an encryption certificate. To downgrade a site that uses a custom certificate, modify the site's CAA records to re-enable Pantheon’s Global CDN Let's Encrypt to issue certificates. Alternatively, you can use another CDN like Cloudflare.
Frequently Asked Questions
Do I need a separate certificate for each site in my organization?
You can use a single certificate to cover multiple domains spread across various environments or sites. Pantheon's Global and Advanced Global CDN use Server Name Indication (SNI), which automatically matches inbound requests with an appropriate certificate, including custom certificates.
What about sites purchased online?
Custom certificates are available for contract customers (e.g. Elite, Enterprise, EDU+) and we have no plans to offer it for Basic or Performance sites purchased online. If bringing your own certificate for non-contract site is a requirement, please see suggestions on how to terminate TLS through a 3rd-party.
Will custom certificates be self-serve?
We have no current plans to offer a self-serve option. The concierge service is designed to quickly guide you through the steps required to deliver HTTPS on the Global CDN using your custom certificate, and we may follow-up with a self-serve option in the future.
What is the maximum number of SAN entries?
For the broadest client compatibility we recommend limiting the number of Subject Alternate Names to 100.
Are private keys available for export?
Private keys are just that, private, and not available for export. They are stored securely, server side, and it’s a security best practice to not share private keys among different deployments.
If you manage multiple domains, with some on Pantheon, and some outside of Pantheon, then we recommend using separate certificates, and we are happy to provide you with a new Certificate Signing Request (CSR) so we can deploy a certificate on Pantheon that only has the domains served on Pantheon.
What are the Global CDN IP addresses?
The Global CDN currently has 4 offsets. After certificate deployment, we will provide DNS information so you can upgrade. In the examples below, X will be replaced with a value of 1, 2, 3, or 4:
A record: 23.185.0.X
AAAA record 1: 2620:12a:8000::X
AAAA record 2: 2620:12a:8001::X
Note: AAAA records are not required, but recommended as a best practice for performance, especially for mobile devices. See Introduction to Domain Name Services for more information.
What if my DNS manager doesn't support CAA DNS records?
CAA records are required in order to prohibit Let's Encrypt from issuing certificates. If your DNS provider does not support CAA records, consider one that does. If using a DNS provider that supports CAA records is not possible, please contact your Professional Services Engagement Manager for help.
How do I relaunch an existing site with a custom certificate?
To take your site live by moving custom domains from one Site Dashboard to another, with minimal HTTPS interruptions, please refer to Relaunch Existing Pantheon Site.
Technical Specifications
| Global CDN with Let's Encrypt | Global CDN with a Custom Certificate | |
|---|---|---|
| Certificate Type | Issued by Let's Encrypt | Bring your own |
| Renewal | Automatic | Self-managed (up to you) |
| Inbound IP | Static (shared) | Static (shared) |
| Client Support | 95.55% of Browsers Some very old browsers not supported 1 2 | 95.55% of Browsers Some very old browsers not supported 1 2 * |
| SSL Labs Rating | A+ with HSTS | A+ with HSTS * |
| Protocol | TLS 1.3 with SNI | TLS 1.3 with SNI |
| Ciphers | No Weak 3DES cipher | No Weak 3DES cipher |
| Delivery | Global CDN | Global CDN |
| Encryption Endpoint | Application Container | Application Container |
* The browser compatibility and SSL Labs scores are guaranteed for Pantheon-provided Let’s Encrypt certificates. The same results are typical for a custom certificate from a mainstream CA with mainstream attributes, but not guaranteed. For custom certificates, compatibility and SSL Labs score depends on attributes of that certificate, such as number of SAN entries, CA and signing algorithm.