This guide uses the following tools and resources:
- LetsEncrypt is a public certificate authority that issues free certificates trusted by the major browsers. Other private or public CAs would also be fine.
- Google Domains registrar will be used to set up our wildcard domain and certificate validation. But any registrar would do and some providers support automatic renewal.
- acme.sh will be used to retrieve the wild-card domain certificate. Any LetsEncrypt client that supports wildcard domains would work.
It should be noted that there are countless ways of building and managing public-key infrastructure. And although we hope this guide serves as a helpful baseline for generating and securing pomerium with certificates, these instructions should be modified to meet your own organization's tools, needs, and constraints.
LetsEncrypt certificates must be renewed every 90 days.
- end-user and Pomerium
- Pomerium's services regardless of if the network is "trusted"
- Pomerium and the destination application
First, you'll want to set a CNAME record for wild-card domain name you will be using with Pomerium.
Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
# Requires acme.sh @ https://github.com/Neilpang/acme.sh # Install (after reviewing, obviously) by running : # $ curl https://get.acme.sh | sh $HOME/.acme.sh/acme.sh \ --issue \ -k ec-256 \ -d '*.corp.example.com' \ --dns \ --yes-I-know-dns-manual-mode-enough-go-ahead-please Creating domain key The domain key is here: $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key Single domain='*.corp.example.com' Getting domain auth token for each domain Getting webroot for domain='*.corp.example.com' Add the following TXT record: Domain: '_acme-challenge.corp.example.com' TXT value: 'Yz0B1Uf2xjyUI7Cr9-k96P2PQnw3RIK32dMViuvT58s' Please be aware that you prepend _acme-challenge. before your domain so the resulting subdomain will be: _acme-challenge.corp.example.com Please add the TXT records to the domains, and re-run with --renew. Please check log file for more details: $HOME/.acme.sh/acme.sh.log Removing DNS records. Not Found domain api file:
LetsEncrypt will respond with the corresponding
TXT record needed to verify our domain.
It may take a few minutes for the DNS records to propagate. Once it does, you can run the following command to complete the certificate request process.
# Complete the certificate request now that we have validated our domain $HOME/.acme.sh/acme.sh \ --renew \ --ecc \ -k ec-256 \ -d '*.corp.example.com' \ --dns \ --yes-I-know-dns-manual-mode-enough-go-ahead-please Renew: '*.corp.example.com' Single domain='*.corp.example.com' Getting domain auth token for each domain Verifying: *.corp.example.com Success Verify finished, start to sign. Cert success. -----BEGIN CERTIFICATE----- .... snip... -----END CERTIFICATE----- Your cert is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer Your cert key is in $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key The intermediate CA cert is in $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer And the full chain certs is there: $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer
Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings:
|Pomerium Config||Certificate file|
Your end users will see a valid certificate for all domains delegated by Pomerium.
Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequately cover here so if you are new to or just need a brush up, the following resources may be helpful:
- Why HTTPS for Everything? The US government's CIO office has an excellent guide covering HTTPS and why future government sites will all be HTTPS.
- Is TLS Fast debunks the performance myth associated with HTTPS.
- Use TLS covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations.
- Everything you should know about certificates and PKI but are too afraid to ask