Helgrind is an HTTPS Authentication Gateway with strong focus on security.

Make sure Git and Go 1.8+ (on Debian Stretch one can use stretch-backports) are installed on the host system.

go get gitlab.stusta.de/stustanet/helgrind

Helgrind requieres a TLS certificate to offer HTTPS. You can acquire one e.g. via Let's Encrypt and certbot.

Generate a CA certificate and private key:

openssl genrsa -aes256 -out ca.key 4096
chmod 400 ca.key
openssl req -new -x509 -sha256 -days 3650 -key ca.key -out ca.crt
chmod 444 ca.crt

The ca.key should be kept private in a secure offline storage. The ca.crt has to be copied to the gateway server.

First copy the example file to /etc/helgrind.json:

cp $GOPATH/src/gitlab.stusta.de/stustanet/helgrind/etc/helgrind.json.example /etc/helgrind.json

Then adjust the /etc/helgrind.json config file. Each backend service has to be configured in its own block. User access is granted per service.

First, create a separate user for helgrind:

useradd --system -s /bin/false -M helgrind

Then copy the systemd unit files:

cp $GOPATH/src/gitlab.stusta.de/stustanet/helgrind/systemd/helgrind.* /etc/systemd/system/

Adjust /etc/systemd/system/helgrind.socket and /etc/systemd/system/helgrind.service if necessary.

Afterwards, run:

systemctl enable helgrind.socket helgrind.service
systemctl start helgrind.socket helgrind.service

Create a new entry in services in the /etc/helgrind.json and set the target (URL to be reverse-proxied). HTTPS should be used.

Also set a unique base64 encoded secret (which will be shared with the backend) to create the HMAC signatures. You can for example generate a random 64 bytes (the length of the secret does not need to be 64 bytes) long base64 string as follows:

base64 --wrap=0 /dev/urandom |head -c 64

The backend server should verify the signature and parse the user information sent by the helgrind server. For that, the hel package can be used.

First the user has to generate a private key and a signing request for it:

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr

Then the client.csr (the private key must not be shared) has to be sent to the gateway admin, which has to sign the certificate:

openssl x509 -req -days 730 -sha256 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 1 -out client.crt
openssl x509 -noout -fingerprint -sha256 -inform pem -in client.crt

The SHA256 fingerprint of the certificate is required to grant access to a backend service, which can be configured in the /etc/helgrind.json on the helgrind server.

The client.crt then has to be sent back to the user, who then creates a PKCS#12 file from the private key and the certificate, which can then imported in the browser (Firefox) or system keychain (Chrome).

openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12

Firefox: Preferences > Advanced > Certificates > View Certificates > Your Certificates

Chrome: Import in the system keychain instead, which is used by Chrome.

Access can easily be managed in /etc/helgrind.json. Either the user can be removed entirely or the specific user or user device can be set to Enabled = false.

• create a signature (HMAC) for the whole request body and selected headers
• include a timestamp in the HMAC