Using HTTPS and mTLS with Kapow!¶
Kapow! can be accesed over HTTPS and use mutual TLS for authentication. Right now there are two possibilities to configure HTTPS/mTLS on a running server.
Note
In the following sections we refer to the host running the Kapow! server as
kapow:8080
.
For testing purposes you can generate a self-signed certificate with the following command:
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
Using Kapow! built in capabilities¶
In this section we present the option flags that the Kapow! server command provides in order to set up a server with HTTPS and/or mTLS.
Enabling HTTPS¶
When starting the server we can provide the private key and the certificate
chain presented to the clients by giving to the server the paths to the
corresponding files using the --keyfile
and --certfile
option flags in the
command line:
$ kapow server --keyfile path/to/keyfile --certfile path/to/certfile foobar-route
Now Kapow! is listening on its default port (8080) accepting requests over HTTPS. You can test it with the following command:
$ curl --cacert path/to/CAfile https://localhost:8080/endpoint
Where path/to/CAfile
is the path to the file containing the CA certificate
that issued Kapow!’s certificate.
Enabling mTLS¶
Once we have Kapow! configured to use HTTPS we can, optionally, activate mTLS so we can reject client connections that do not present a valid client certificate. Currently only issuer CA matching is supported, but in a near future we’ll be able to filter by DN in order to get more fine grained authentication.
In order to activate mTLS we have to provide Kapow! server command with the
CA certificate issuing the client certificates we want to accept with the
--clientcafile
option flag and toggle the --clientauth=true
option flag:
$ kapow server --keyfile path/to/keyfile --certfile path/to/certfile --clientauth=true --clientcafile path/to/clientCAfile foobar-route
With this configuration Kapow! will reject connections that do not present a client certificate or one certificate not issued by the specified CA. You can test it with the following command:
$ curl --cacert path/to/CAfile --cert path/to/clientcredentials https://localhost:8080/endpoint
Where path/to/clientcredentials
is the path to the file in PKCS#12 format
containing the client certificate and private key. If you have the certificate
and the private key in different files you can use the –key option to specify
it independently.
Kapow! Behind a Reverse Proxy¶
Although Kapow! supports HTTPS
you can use a reverse proxy to serve a
Kapow! service via HTTPS
.
In this section we present a series of reverse proxy configurations that augment the capabilities of Kapow!.
Caddy¶
Automatic Let’s Encrypt Certificate
Caddy
automatically enablesHTTPS
usingLet's Encrypt
certificates given that some criteria are met.yourpublicdomain.example proxy / kapow:8080
Automatic Self-signed Certificate
If you want
Caddy
to automatically generate a self-signed certificate for testing you can use the following configuration.yourdomain.example proxy / kapow:8080 tls self_signed
Custom Certificate
If you already have a valid certificate for your server use this configuration.
yourdomain.example proxy / kapow:8080 tls /path/to/cert.pem /path/to/key.pem
In order to enable mutual TLS authentication read the Caddy documentation.
HAProxy¶
With the following configuration you can run HAProxy
with a custom
certificate.
frontend myserver.local
bind *:443 ssl crt /path/to/myserver.local.pem
mode http
default_backend nodes
backend nodes
mode http
server kapow1 kapow:8080
Note
You can produce myserver.local.pem
from the certificates in
previous examples with this command:
$ cat /path/to/cert.pem /path/to/key.pem > /path/to/myserver.local.pem
In order to enable mutual TLS authentication read the HAProxy documentation.
nginx¶
With the following configuration you can run nginx
with a custom
certificate.
server {
listen 443 ssl;
server_name myserver.local;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://kapow:8080;
}
}
In order to enable mutual TLS authentication read the `Nginx documentation`_.