simpleauth/README.md

# Simple Auth

This is a stateless forward-auth provider.
I tested it with Caddy, but it should work fine with Traefik.

# Theory of Operation

This issues cryptographically signed authentication tokens to the client.
Some JavaScript stores the token in a cookie.

When a client presents an authentication token in a cookie,
they are allowed in if the token was properly signed,
and has not expired.

Authentication tokens consist of:

* Username
* Expiration date
* Hashed Message Authentication Code (HMAC)

Simpleauth also works with HTTP Basic authentication.

# Setup

Simpleauth needs two (2) files:

* A secret key, to sign authentication tokens
* A list of usernames and hashed passwords


## Create secret key

This will use `/dev/urandom` to generate a 64-byte secret key.

```sh
SASECRET=/run/secrets/simpleauth.key  # Set to wherever you want your secret to live
dd if=/dev/urandom of=$SASECRET bs=1 count=64
```


## Create password file

It's just a text file with hashed passwords.
Each line is of the format `username:password_hash`

```sh
alias sacrypt="docker run --rm --entrypoint=/crypt git.woozle.org/neale/simpleauth"
SAPASSWD=/run/secrets/passwd   # Set to wherever you want your password file to live
: > $SAPASSWD                  # Reset password file
sacrypt user1 password1 >> $SAPASSWD
sacrypt user2 password2 >> $SAPASSWD
sacrypt user3 password3 >> $SAPASSWD
```


## Start it

Turning this into the container orchestration system you prefer
(Docker Swarm, Kubernetes, Docker Compose)
is left as an exercise for the reader.

```sh
docker run \
  --name=simpleauth \
  --detach \
  --restart=always \
  --port 8080:8080 \
  --volume $SASECRET:/run/secrets/simpleauth.key:ro \
  --volume $SAPASSWD:/run/secrets/passwd:ro \
  git.woozle.org/neale/simpleauth
```

## Make your web server use it

### Caddy

You'll want a `forward-auth` section like this:

```
private.example.com {
  forward_auth localhost:8080 {
    uri /
    copy_headers X-Simpleauth-Username
    header_down X-Simpleauth-Domain example.com    # Set cookie for all of example.com
  }
  respond "Hello, friend!"
}
```

The `copy_headers` directive tells Caddy to pass
Simpleauth's `X-Simpleauth-Username` header
along in the HTTP request.
If you are reverse proxying to some other app,
it can look at this header to determine who's logged in.

`header_down` sets the
`X-Simpleauth-Domain` header in HTTP responses.
The only time a client would get an HTTP response is when it is not yet authenticated.
The built-in JavaScript login page uses this header to set the cookie domain:
this way, you can protect multiple sites within a single cookie

### Traefik

I need someone to send me equivalent
traefik
configuration,
to include here.


### nginx

I need someone to send me equivalent
nginx
configuration,
to include here.


# Why not some other thing?

The main reason is that I couldn't get the freedesktop.org
WebDAV client code to work with anything else I found.

* Authelia - I like it, but I couldn't get WebDAV to work. Also, it used 4.8GB of RAM and wanted a Redis server.
* Authentik - Didn't try it, looked too complicated.
* Keycloak - Didn't try it, looked way too complicated.


# Todo

* [ ] Performance testing: somehow this takes more CPU than caddy?

# Project Home

The canonical home for this project is
https://git.woozle.org/neale/simpleauth