Security

To operate heimdall in a secure way, you should configure heimdall accordingly. Following sections address the corresponding areas.

TLS

As documented in Concepts section, the execution of heimdall’s pipeline typically includes communication to other systems. The endpoints of the corresponding systems should be TLS protected. This is however actually out of scope for heimdall. What is in scope, is the verification of the used TLS server certificate, if TLS is used. This happens by making use of the operating system-wide trust store, containing the certificates of Root and Intermediate CAs (trust anchors) shipped with the OS. That means, you should

  1. ensure this trust store contains the certificates of the Root CAs of your PKI hierarchy and

  2. ensure the endpoints, heimdall communicates with over TLS, provide not only their own certificates, but also the intermediate certificates and cross certificates not included within the OS trust store

Both is required to enable heimdall building the certificate chain for TLS server certificate verification purpose. If heimdall fails doing so, the connection will be dropped.

As written above, heimdall makes use of the OS wide trust store to build the certificate chain. The most common installation directory on a Linux system for that trust store is the /etc/ssl/certs directory. In addition to the separate root and intermediate CA certificates, it also contains a ca-certificates.crt file, containing all installed certificates as well. This file is used by heimdall for the aforesaid purpose.

heimdall Docker image is shipped without any certificates by intention to ensure you take care about the up-to-date status of the trust store. This way, if you use heimdall in a container, you have to mount the OS trust store into heimdall’s container to enable its usage.

E.g.

docker run -t -p 4456:4456 \
  -v $PWD:/heimdall/conf \
  -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro \
   dadrus/heimdall:latest serve decision \
  -c /heimdall/conf/heimdall.yaml

The verification of TLS server certificates is not the single configuration option. You should also ensure heimdall’s services, you’re using, are configured to be available via TLS as well. See TLS Configuration for all available options.

Signatures

When heimdall is used to issue signed objects, like JWTs, to enable upstream services to rely on authentic subject information, it acts as an issuer of such objects and requires corresponding configuration (see Cryptographic Material).

In a typical production scenario, there is a need for proper key and certificate management. This is supported by heimdall in the following way:

  • you can and should configure not only the private key for signature creation purposes, but also the corresponding certificate chain. This way your upstream services are able not only to verify the signatures of the signed objects for cryptographic validity, but also perform verification of the revocation status of used certificates and also their time validity. All of that is crucial for secure communication.

    The cryptographic material for the above said verification purposes is available via the JWKS endpoint for the upstream services.

  • you can configure multiple keys in heimdall’s key_store and specify the key_id of the key to use. The easiest way to let heimdall use the key id, you need, is to set X-Key-ID header in the PEM block of the corresponding private key. With that in place you can perform key roll over without down-times by first updating the key stores of all heimdall instances to include the new key and certificates, and when this is done, by updating the key id to reference the new key material instance by instance. This way all upstream services can verify the signatures of the objects issued by heimdall, regardless of the used key material, as all heimdall instances, are able to serve the new and the old cryptographic material.

Last updated on Dec 17, 2022

Observability
Traefik Proxy Integration