heimdall

README

Heimdall

Background

Heimdall is inspired by the Zero Trust idea and also by Pomerium and Ory's OAthkeeper. Some experience with both and my inability to update the latter one to include the desired functionality and behavior was Heimdall's born hour.

What is heimdall

Heimdall authenticates and authorizes incoming HTTP (HTTP 1.x and HTTP 2.0) requests as well as enriches these with further contextual information and finally transforms resulting subject information into a format, required by the upstream services.

It can do so

• standalone as a proxy in front of your service or web server that rejects unauthorized requests and forwards authorized ones to your end points, or
• integrated into any other proxy, ingress controller or API gateway, like Kong, NGNIX, Envoy, Traefik, Contour, Ambassador and many more. Here that other proxy will forward the incoming request to heimdall and depending on its response either forward the original request, verified and updated by heimdall to your upstream service, or reject it with the information provided by heimdall.

In both cases is acts as a Policy Enforcement and to some degree a Policy Decision Point according to NIST Zero Trust Architecture (SP 800-207)

How does authentication, authorization and transformation happen

The above said decision and transformation process happens via rules, respectively rule sets, which can be controlled by each and every upstream service individually and loaded by heimdall from different sources, like

• the local file system,
• any HTTP endpoint,
• cloud storages, like AWS S3, Google's GC, etc. and
• RuleSet kubernetes resources (a corresponding CRD is shipped with the helm chart)

That way, these rule sets can not only be managed centrally, but be deployed together with each particular upstream service as well without the need to restart or redeploy heimdall. Indeed, these rule sets are optional first class citizens of the upstream service and allow:

• implementation of secure defaults. If no rule matches the incoming request, a default decision and transformation, if configured, is applied. This is the reason for "optional first class citizens" above.
• configuration of as many authentication (e.g. OpenID Connect), authorization (e.g. via CEL expressions, or via OPA, or OpenFGA), contextualization (by e.g. communicating to some specific endpoint) and finalization mechanisms (e.g. creation of a JWT out of the available subject information), supported by heimdall, as required for the particular system. So, if your system requires integration with multiple authentication providers, or you want to migrate from one to another - it is just a matter of configuring them in heimdall.
• reuse and combination of these mechanisms in as many rules, as required for the particular system.
• partial reconfiguration of a particular mechanism in a rule if required by the upstream service.
• authentication mechanism fallbacks
• implementation of different decision process schemes by combining e.g. authentication mechanisms with error handlers to drive authentication mechanism specific error handling strategies.
• execution of authorization and contextualization mechanisms in any order; that way, if the information about your subject, available from the authentication system, is not sufficient to make proper authorization decisions, you can let heimdall call other services to retrieve that additional information.
• conditional execution of authorization, contextualization and finalization mechanisms is possible, e.g. if depending on the available information about the subject you would like heimdall to either block the request, or let the upstream return different representations of the requested resource.

Beyond the functionality

Heimdall's main focus points beyond its functionality are:

• Performance - To achieve this, heimdall does use any http routing frameworks and does not load or convert data during execution whenever possible. This is also true for reflection use.
• Clear abstractions - To allow extensibility and even replacement of components without side effects.
• Simplicity - To allow better understanding of code to everybody, who would like to contribute.

Where can I find more details

Head over to the documentation for details or if you would like to give it a try.

Current state

The current implementation is a late alpha version. That means it does not solve all the problems heimdall aims to solve. With other words a lot of functionality is missing. In addition, alpha version means, there will be breaking changes. Nevertheless, the code base is very stable and pretty good tested. Functionality already supported can be found in Release descriptions. Planned features can be found in the defined Milestones.

If you ...

• ... like the project - please give it a ⭐
• ... miss something, or found a bug, file a ticket. You are also very welcome to contribute 😉
• ... would like to support, reach out to me via Discord
• ... need help, head over to Discord as well