> For the complete documentation index, see [llms.txt](https://docs.navigaglobal.com/navigaid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.navigaglobal.com/navigaid/local-development/local-https-support.md). # Local 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` {% hint style="info" %} 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. {% endhint %} ### Let's get started! #### 1. Start a demo http-server {% hint style="info" %} 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. {% endhint %} To start the demo server, open a terminal and run the following command ```bash docker run -p 8888:80 nginxdemos/hello ``` Let the application run and open your browser and verify that 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 and follow the installation instructions for your OS. Once installed, execute the following steps to generate your first certificate. ```bash 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](< 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. {% hint style="warning" %} There are **two** instances on line 3 where the name must be replaced {% endhint %} ```bash 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 ```bash 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 ```bash 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 ```bash cd ~/ caddy adapt caddy reload ``` Finally, add an entry in `/etc/hosts` that matches the domain you added in `~/Caddyfile` ```bash 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. ```bash 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.