Traefik Proxy Integration

Traefik Proxy is a modern HTTP proxy and load balancer for microservices, heimdall can be integrated with via the ForwardAuth Middleware while operated in the Decision Operation Mode. In such setup, traefik delegates authentication and authorization to heimdall. If heimdall answers with a 2XX code, traefik grants access and forwards the original request to the upstream service. Otherwise, the response from heimdall is returned to the client.

To achieve this, configure traefik

  • to make use of the aforesaid ForwardAuth middleware by setting the address property to the decision service endpoint and

  • configure the authResponseHeaders to contain the required header name(s), heimdall sets in the HTTP responses (depends on your Contextualizers and Unifiers configuration).

  • Configure the route of your service to make use of this middleware.

Traefik makes use of X-Forwarded-* HTTP headers to forward the HTTP method, protocol, host, etc. to the ForwardAuth middleware. By default, heimdall does not trust those. To allow heimdall making use of such headers, you must configure trusted proxies in heimdall’s decision service configuration to contain the IPs or networks of your traefik instances. For test purposes, you can set it to "0.0.0.0/0", which would basically disable the check and let heimdall trust requests from any source.

Since traefik makes use of those X-Forwarded-* headers, which heimdall also handles with precedence, there is no need to drop any headers to prevent spoofing (see also Security Considerations for details.
Example 1. Using Docker labels
edge-router:
  image: traefik
  # further configuration
  labels:
    - traefik.http.middlewares.heimdall.forwardauth.address=http://heimdall:4456
    - traefik.http.middlewares.heimdall.forwardauth.authResponseHeaders=X-Id-Token,Authorization
    # further labels

service:
  image: my-service
  # further configuration
  labels:
    - traefik.http.routers.service.middlewares=heimdall
    # further labels

A fully working example with Traefik is shown in the Decision Service Quickstart and is also available on GitHub.

Last updated on Aug 7, 2023

Security
NGINX Integration