Setting Up Custom Trusted Certificates

Intro

When working with some features of the Grey Matter Proxy, notably the Oauth Filter, it may become necessary to update the OS level trusted certificates with customer provided certs. This document shows briefly how to accomplish this.

Background

Normally, the OS manages trusted certificates that tools like the browser, curl, etc use. These managed trusted certificates are provided by reliable third-party companies like Verisign and Cloudflare. Over time, as certificates expire or update, re-running OS tools like update-ca-certificates will fetch the most recent certs for known entities like google.com, amazon.com, etc.

When a customer uses self-signed certificates, they may not be using one of these third-party companies for validation. In this case, the browser and curl won't trust that they are who they say they are, unless we explicitly tell them to using the methods outlined here.

Setup

To configure new trusted certificates, we'll need to pull the existing docker image and re-build it with any added certs to trust. This can't easily be done just by mounting certs at runtime, as it would also require overriding the default command. (possible to do, just not very clean)

Note: the docs here assume the container is running Alpine Linux, but similar procedures can be found for Ubuntu, CentOS, etc.

Warning: Each certificate loaded must be in separate file. Any file with multiple certs will cause the procedure to fail.

1. Setup a local directory with any certs that need to be trusted.

   1. For demo purposes here, this directory is called ./certs-override

2. Insert certs into that directly, one cert at a time. E.g.

   1. trust1.pem, trust2.pem, trust3.pem, etc

3. Build the new image with the command docker build -t test/gm-proxy -f Dockerfile .. This will:

   1. Pull an existing proxy build

   2. Mount in the local certs

   3. Run the OS update command

   4. Setup the correct default runtime command

The resulting image can be run exactly the same as any other gm-proxy image, but operations will now trust the mounted certs as well.

Dockerfile

FROM docker.greymatter.io/release/gm-proxy:1.4.5

# Switch to root user, necessary for the following operations
USER root

ADD ./certs-override/ /usr/local/share/ca-certificates/
RUN update-ca-certificates

# Switch back to a non-root user for execution
USER gmproxy

CMD ./gm-proxy -c config.yaml