nforwardauth is an extremely lightweight, blazing-fast forward auth service that allows you to use a single authentication middleware for all your sites. It is intended for use with reverse proxies like Traefik, Caddy, Nginx, and others to allow/deny access via an auth wall.

The inspiration for nforwardauth came from the frustration of using basic auth as a simple way to protect self-hosted server applications. The creator wanted something that was more user-friendly and streamlined, and that didn't require authenticating with every site and allowed the use of password managers. They also wanted something that could be used in conjunction with other self-host server homepages like Homer and homepage. After finding Organizr's forwardauth too complex and heavy for their needs, the creator decided to create nforwardauth, a simple and lightweight alternative that gets the job done without any unnecessary bells and whistles.

How It Works #

Here is a simple illustration of how nforwardauth integrates with reverse proxies:

When you visit a route/host that is protected by nforwardauth, the server will first forward the request to nforwardauth, which will check whether or not your request contains a valid access token. If your request does not, you will be redirected to the nforwardauth login page. Upon logging in, you will be redirected to the URI of your initial request.

nforwardauth uses a passwd file to store valid credentials. Currently, it only supports username and password combinations (similar to that of HTTP basic auth). The passwd file should contain one line per user in the format username:hashed_password.

Getting Started #

To use nforwardauth, you'll need to create a passwd file and mount it as a volume when you run the container. Here's an example of how to create an initial passwd file with a single user named test and the password test:

echo "test:$(mkpasswd -m sha-512 test)" >> /path/to/passwd

When you run the nforwardauth container, you should mount the passwd file as a volume with the -v option when using the command line, like this:

docker run -p 3000:3000 \
  -e TOKEN_SECRET=example-secret-123 \
  -e AUTH_HOST=nforwardauth.localhost.com \
  -v /path/to/passwd:/passwd \
  nosduco/nforwardauth:v1

With your passwd file mounted, nforwardauth will use it to authenticate users when they access sites with the forwardauth middleware. You will only need to log in once to access all sites behind the middleware.

nforwardauth is highly configurable, and the creator has provided various examples on how to use it with Traefik v2, Caddy, and Nginx. Here's a simple configuration using Traefik v2 and protecting a simple whoami container behind the forwardauth middleware:

version: '3'

services:
  traefik:  # Basic traefik v2 configuration
    image: traefik:v2.9
    command: --providers.docker
    ports:
      - "80:80"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Mount docker socket as read