hauth

hauth

Simple and lightweight go application for securing applications using Caddy's forward_auth directive and a GitHub/Keycloak authentication provider.

Customizable per hostname with email-/role-based whitelist. Runs stateless by saving state in encrypted user cookies, allowing to be run without a central source of truth.

Deployment

Docker image: registry.hserv.org/infra/hauth:main (or just build the binary yourself using go)

See .env.example for a list of available environment variables. I would recommend to use docker compose for a simple setup, see their docs on how to use it.

The forward-auth endpoint is available at /api/v1/auth, so to use this in your Caddyfile:

forward_auth http://<hauth-endpoint> {
    uri /api/v1/auth
}

Example config

You will need to know how to create these OAuth2 Applications yourself (or search for the docs on how to do this).

- provider:
    type: keycloak
    application: blabla-oauth
    secret: asdasdsdgjdfgnjsdnf
    domain: keycloak.example.net
    realm: master
  entries:
    - hosts:
        - dashboard.example.net
      roles:
        - admin
        - manager
        - sales
    - hosts:
        - sales.example.net
      emails:
        - sales
    - hosts:
        - public.example.net
- provider:
    type: github
    application: Kjasdjdfghjdfgfgh3
    secret: asdacasdreedasdasdedasdasd
  entries:
    - hosts:
        - dashboard.example.org
      emails:
        - admin@example.org
        - manager@example.org
        - sales@example.org
    - hosts:
        - sales.example.org
      emails:
        - sales@example.org
    - hosts:
        - public.example.org

roles are only available for the Keycloak provider and need to be activated be going to Client scopes → "roles" → Mappers → "client roles" and "realm roles" → activating "Add to ID token" and "Add to userinfo".

Only either one match in roles and emails is required to allow access. Missing hosts will always be rejected.