Pomerium

# Certificates

Certificates and TLS play a vital role in zero-trust networks, and in Pomerium. This document covers how to generate and set up wild-card certificates suitable for working with pomerium.

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.

WARNING

LetsEncrypt certificates must be renewed every 90 days.

# Why

Since one of Pomerium's core principles is to treat internal and external traffic impartially, Pomerium uses mutually authenticated TLS ubiquitously. For example, Pomerium uses mTLS between:

  • end-user and Pomerium
  • Pomerium's services regardless of if the network is "trusted"
  • Pomerium and the destination application

# How

First, you'll want to set a CNAME record for wild-card domain name you will be using with Pomerium.

pomerium add a text entry to your dns records

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.

pomerium add a text entry to your dns records

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
CERTIFICATE $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer
CERTIFICATE_KEY $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
CERTIFICATE_AUTHORITY $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer
OVERRIDE_CERTIFICATE_NAME *.corp.example.com

Your end users will see a valid certificate for all domains delegated by Pomerium.

pomerium valid certificate

pomerium certificates A+ ssl labs rating

# Resources

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:

← User impersonation →