133 lines
3.2 KiB
Markdown
133 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
|
|
# Project Home
|
|
|
|
The canonical home for this project is
|
|
https://git.woozle.org/neale/simpleauth
|
|
|