# 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_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
mkcertapplication to create the certificates. To install
mkcertfollow the instructions on Github (opens new window).
mkcerttool 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.iodomain will be our root domain (all subdomains on
# Create Certificates
Create a trusted root certificate authority (CA):
Create a wildcard certificate for
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:
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:
# 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
config.yaml file or environment variables with the following aditions. Replace
/YOUR/MKCERT/CAROOT in this example with the value of
This configuration will require client certificates for all routes. See rquire mTLS per Route to enable mTLS on for specific routes.
# 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
- 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
# 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.
Click on Import and browse to the directory where you created the certificates above. Choose
You will be prompted for the certificate password. The default password is
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 (opens new window) (or another route you've defined) and you should be prompted to choose a client certificate: