Security

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

HTTP Header Security Considerations

If trusted_proxies property is configured (see also the corresponding Decision and Proxy service configuration options) to let heimdall make use of different HTTP headers to build the URL for rule and HTTP method matching purposes, following logic apply:

  • The value for the used HTTP schema is taken from the X-Forwarded-Proto header.

  • The value for the used HTTP host and port is taken from the X-Forwarded-Host header.

  • The value for the used HTTP path is taken either from X-Forwarded-Uri or X-Forwarded-Path with X-Forwarded-Uri taking precedence. Compared to X-Forwarded-Path, X-Forwarded-Uri does also contain query parameters.

  • The value for the used HTTP method is taken from the X-Forwarded-Method header.

If the evaluation result for any of the above said steps is empty, the corresponding value is taken from the actual request to heimdall. E.g. if X-Forwarded-Method is set, the HTTP method used to communicate with heimdall is used for rule matching respectively evaluation purposes.

That means, if the client integrating with heimdall does not make use of the above said headers and does not drop them, a malicious actor could spoof them most probably leading to privileges escalation (depending on your rules). To avoid such situations, please adhere to the following practices:

  • If you can, try avoiding usage of trusted_proxies. Nothing can be spoofed then. However, you will lose the information about the used HTTP scheme, host and port and cannot rely on these in your rules.

  • Configure all headers and use those taking precedence. That is, always set X-Forwarded-Method, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Uri.

  • If you cannot influence, which headers are set by your system, you’re integrating with heimdall, let it drop unused ones. E.g. If the proxy forwarding the request to heimdall by default sets only X-Forwarded-Proto and X-Forwarded-Host, let it drop the X-Forwarded-Method and X-Forwarded-Uri headers.

The Integration Guides follow these practices, respectively highlight where caution is required. So, you can find examples there.

Observability Information

Logs, metrics and profiling information is very valuable for operating heimdall. These are however also very valuable for any adversary. For this reason, the corresponding services, which expose such information are by default, if enabled, listening only on the loopback (127.0.0.1) interface. If you have to configure them to listen to other interfaces, e.g. because you operate heimdall in a container, make sure, you don’t expose them publicly.

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 Aug 7, 2023

Observability
Traefik Proxy Integration