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 install mkcert follow the instructions on Github (opens new window).

  WARNING

  The 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 on localhost.pomerium.io point to localhost).

Create Certificates

1. Create a trusted root certificate authority (CA):

   mkcert -install
   

2. Create a wildcard certificate for *.localhost.pomerium.io:

   mkcert '*.localhost.pomerium.io'
   

   Note

   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.

3. 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 aditions. Replace /YOUR/MKCERT/CAROOT in this example with the value of mkcert -CAROOT:

TIP

This configuration will require client certificates for all routes. See rquire mTLS per Route to enable mTLS on for specific routes.

# 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.

1. Go to chrome://settings/certificates:

   

2. Click on Import and browse to the directory where you created the certificates above. Choose _wildcard.localhost.pomerium.io-client.p12:

   

3. You will be prompted for the certificate password. The default password is changeit:

   

4. 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: