Custom Domains in Pomerium Zero
This document describes Custom Domains in Pomerium Zero.
Overview
When you deploy a cluster in Pomerium Zero, we provision a randomly generated starter subdomain under pomerium.app
that's assigned to that cluster (for example, unique-jellyfish-3578.pomerium.app
).
Each starter subdomain comes with its own DNS records and TLS certificates, which makes it easier for new users to quickly build and test routes and policies in Pomerium Zero.
After testing Pomerium Zero with your starter domain, you may want to add a custom domain for use by your cluster's routes to secure your apps and services.
See the Clusters Concepts page for more information about clusters in Pomerium Zero.
Custom Domains
In Pomerium Zero, a Custom Domain is a wildcard subdomain you can use to build routes in Pomerium. After adding the appropriate record to your DNS provider, Pomerium will automatically provision and renew a TLS certificate for this subdomain.
For example, if you added a custom domain like mycorp.example.com
to Pomerium Zero, you could build routes like:
verify.mycorp.example.com
internal-tool.mycorp.example.com
authenticate.mycorp.example.com
How to add a custom domain
Add a wildcard CNAME record that points to your starter domain. For example:
*.mycorp.example.com CNAME unique-jellyfish-3578.pomerium.app
If you're using a DNS provider like Google's Cloud DNS, you can add the wildcard CNAME record without code:
Add the custom domain in Cluster Settings > Domains:
- Select Settings
- In the Editing Clusters Settings dashboard, select Domains
- In the Custom Domains field, select the + icon to add a domain name
- Enter your custom domain
If added successfully, you will be able to build routes with your custom domain instead of the starter domain. Pomerium will automatically issue and renew X.509 certificates for this custom domain, which you can verify by the Common Name found in the certificate:
You can also review the certificate in the Certificates dashboard:
How custom domains work
In order for Pomerium to provision certificates on behalf of a custom domain, you must prove that you control the domain name specified in the certificate through DNS validation. Per the ACME protocol, Pomerium uses its own ACME client to communicate with Let's Encrypt, a free Certificate Authority, to validate a domain's DNS records.
Let's Encrypt provides several challenge types to validate a domain, including the DNS-01 challenge. At a high level, this challenge requires that either:
- A
TXT
record must be placed at_acme-challenge.<YOUR_DOMAIN>
- Or, a
CNAME
record must be placed at_acme-challenge.<YOUR_DOMAIN>
that points to another domain with theTXT
record
Because Pomerium owns the pomerium.app
subdomain, we can write the TXT
record for you. All you need to do is point a wildcard CNAME record to your cluster's starter domain.