Client-Side mTLS With Pomerium
Secure communication on the web typically refers to using signed server certificates with the TLS protocol. TLS connections are both private and authenticated, preventing eavesdropping and impersonation of the server.
To authenticate clients (users), we typically use an identity provider (IDP). Clients must login before they can access a protected endpoint. However the TLS protocol also supports mutual authenticate (mTLS) via signed client certificates.
Pomerium supports requiring signed client certificates with the client_ca
/client_ca_file
configuration options. This guide covers how to configure Pomerium to implement mutual authentication using client certificates with a custom certificate authority.
Before You Begin
This guide assumes you already have a working Pomerium instance. See our Quick-Start doc for installation through Docker, and one of the Identity Provider docs to connect it to your IdP. You should also have a working route to test against.
We will use the
mkcert
application to create the certificates. To installmkcert
follow the instructions on Github.cautionThe
mkcert
tool is designed for testing. It creates a locally-trusted root certificate for development purposes. We're using mkcert for this proof-of-concept example, but consider using a different certificate solution for production environments.For this guide the
localhost.pomerium.io
domain will be our root domain (all subdomains onlocalhost.pomerium.io
point tolocalhost
).
Create Certificates
Create a trusted root certificate authority (CA):
mkcert -install
Create a wildcard certificate for
*.localhost.pomerium.io
:mkcert '*.localhost.pomerium.io'
tipNote If you already have a certificate solution for route ingress, you can skip this step. Client certificates can be validated from a certificate authority independent of the route CA.
This creates two files in the current working directory:
_wildcard.localhost.pomerium.io.pem
_wildcard.localhost.pomerium.io-key.pem
We will use these files for the server TLS certificate.
Create a client TLS certificate:
mkcert -client -pkcs12 'yourUsername@localhost.pomerium.io'
This creates a new file in the current working directory:
yourUsername@localhost.pomerium.io-client.p12
Configure Pomerium
Pomerium can be configured to require a client certificate for all routes signed by a single CA, or on a per-route basis with the CA set individually.
Require mTLS for All Routes
Update the config.yaml
file or environment variables with the following additions. Replace /YOUR/MKCERT/CAROOT
in this example with the value of mkcert -CAROOT
:
Configuration will require client certificates for all routes. See require mTLS per Route to enable mTLS on for specific routes.
- config.yaml
- Environment Variables
# If you're using a separate certificate for server-side TLS, leave these keys unchanged.
certificate_file: '_wildcard.localhost.pomerium.io.pem'
certificate_key_file: '_wildcard.localhost.pomerium.io-key.pem'
# "$(mkcert -CAROOT)/rootCA.pem"
client_ca_file: '/YOUR/MKCERT/CAROOT/rootCA.pem'
Alternately, you can encode the client certificate authority as a base64-encoded string (cat $(mkcert -CAROOT)/rootCA.pem | base64 -w 0
) and provide the value to client_ca
.
# If you're using a separate certificate for server-side TLS, leave these variables unchanged.
CERTIFICATE_FILE="_wildcard.localhost.pomerium.io.pem"
CERTIFICATE_KEY_FILE="_wildcard.localhost.pomerium.io-key.pem"
# "$(mkcert -CAROOT)/rootCA.pem"
CLIENT_CA_FILE="/YOUR/MKCERT/CAROOT/rootCA.pem"
Alternately, you can encode the client certificate authority as a base64-encoded string (cat $(mkcert -CAROOT)/rootCA.pem | base64 -w 0
) and provide the value as CLIENT_CA
.
Start Pomerium.
Require mTLS per Route
You can define a client certificate authority for an individual route. Use this option to only require mTLS for specific routes, or to require certificates singed by a different CA than the one required by default with client_ca
or client_ca_file
:
- from: https://verify.localhost.pomerium.io
to: https://verify.pomerium.com
# "$(mkcert -CAROOT)/rootCA.pem"
tls_downstream_client_ca_file: '/YOUR/MKCERT/CAROOT/rootCA.pem'
pass_identity_headers: true
policy:
- allow:
or:
- domain:
is: example.com
Alternately, you can encode the client certificate authority as a base64-encoded string (cat $(mkcert -CAROOT)/rootCA.pem | base64 -w 0
) and provide the value to tls_downstream_client_ca
.
Install Client Certificate
Because your routes now require a client certificate to be accessed, we must install that client certificate in the browser. The following instructions are for Chrome, but client certificates are supported in all major browsers.
Go to
chrome://settings/certificates
:Click on Import and browse to the directory where you created the certificates above. Choose
_wildcard.localhost.pomerium.io-client.p12
:You will be prompted for the certificate password. The default password is
changeit
:The org-mkcert development certificate should now be in your list of certificates:
Using the Client Certificate
You can now visit https://verify.localhost.pomerium.io (or another route you've defined) and you should be prompted to choose a client certificate: