Local HTTPS support

How to enable local development with HTTPS support

Naviga ID does not allow the ID-token cookie to be included in requests over unencrypted connections. Therefore, local SSL support is required to have locally hosted web applications make use of the Naviga ID cookie.

For this to work, a couple of things are needed

• A locally running HTTP service

• A locally installed root-certificate that can be used to generate custom certificates

• A local proxy that handles the SSL handshake and encryption/decryption and also proxy the request to the local HTTP service

• At least one ...local.infomaker.io entry in /etc/hosts that points to 127.0.0.1

Almost all web backends support SSL termination. However, since we always use ALB, API Gateway, or CloudFront for SSL termination in our hosted services, it's better to mimic that setup with a proxy locally as well. That way, no code change is required for your service.

Let's get started!

1. Start a demo http-server

For simplicity and to ensure that anyone can use this guide, a simple demo server is used instead of an actual Naviga service. At the end of the guide, there's a description of what you need to change to run one (or more) "real" services locally with HTTPS support.

To start the demo server, open a terminal and run the following command

docker run -p 8888:80 nginxdemos/hello

Let the application run and open your browser and verify that http://localhost:8888 returns a test page.

Looks good? Great!

2. Install and run mkcert

Next, let's install the tool that will help us generate and install root and service certificates. Go to https://github.com/FiloSottile/mkcert and follow the installation instructions for your OS.

Once installed, execute the following steps to generate your first certificate.

mkdir ~/certificates 
cd ~/certificates 
mkcert "*.local.infomaker.io"
mkcert -install
chmod +r *.pem  # might not be needed

3. Install and configure Caddy as reversed proxy

The next step is to install the proxy server to use for the SSL termination. Go to https://caddyserver.com/docs/install and follow the instructions for your OS.

Next, create a file called ~/Caddyfile in your home directory. Use the example below as a template but make sure to replace the name in the path to the certificates (/home/jacob/certificates/...) with the name of your home dir.

There are two instances on line 3 where the name must be replaced

demo.local.infomaker.io {

    tls /home/jacob/certificates/_wildcard.local.infomaker.io.pem /home/jacob/certificates/_wildcard.local.infomaker.io-key.pem

    reverse_proxy localhost:8888 {
        header_up Host                {host}
        header_up Origin              {host}
        header_up X-Real-IP           {remote}
        header_up X-Forwarded-Host    {host}
        header_up X-Forwarded-Server  {host}
        header_up X-Forwarded-Port    {port}
        header_up X-Forwarded-For     {remote}
        header_up X-Forwarded-Proto   {scheme}
        header_down Access-Control-Allow-Origin       https://demo.local.infomaker.io
        header_down Access-Control-Allow-Credentials  true
    }
}

Once done, run the following commands

cd ~/
caddy start
caddy adapt
caddy reload

4. Configure /etc/hosts to map domain name to localhost

The last step to tie it all together is to update your local hosts file with an entry that tells your browsers and applications that demo.local.infomaker.io is hosted on your own machine and not online somewhere. We use the same domain name as in the ~/Caddyfile and add it to /etc/hosts as below

127.0.0.1 demo.local.infomaker.io

5. Profit!

If you open your browser and go to https://demo.local.infomaker.io you should be greeted with the same test page as before, but this time with a locked padlock to the left or the URL bar and no errors about an unsecured connection.

6. Optional: Run multiple services

To add more services, simply duplicate the current entry in the ~/Caddyfile and update the following parts:

1. The domain name. Change demo to whatever name you want to use for your service

2. The local port. Change localhost:8888 to match the port your application is bound to.

Save the file and reload the Caddy config

cd ~/
caddy adapt
caddy reload

Finally, add an entry in /etc/hosts that matches the domain you added in ~/Caddyfile

127.0.0.1 WHATEVER-SERVICE-NAME-YOU-WANT.local.infomaker.io

Gotchas

Some frameworks (such as Node) have their own trust-store. In that case, the root certificate must be added there as well. If not added, any requests from node to https://demo.local.infomaker.io will fail since the root certificate from mkcert is not trusted.

For node, make sure you have the following environment variable set.

NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem

If you're using Docker, you must also mount the rootCA.pem file inside docker, and use the NODE_EXTRA_CA_CERTS to point the location inside docker.