simpleauth/README.md

92 lines
2.4 KiB
Markdown

The canonical home for this project is
https://git.woozle.org/neale/simpleauth
# Simple Auth
All this does is present a login page.
Upon successful login, the browser gets a cookie,
and further attempts to access will get the success page.
I made this to use with the Traefik forward-auth middleware.
I now use Caddy: it works with that too.
All I need is a simple password, that's easy to fill with a password manager.
This checks those boxes.
## Format of the `passwd` file
It's just like `/etc/shadow`.
username:crypted-password
We use sha256,
until there's a Go library that supports everything.
There's a program included called `crypt` that will output lines for this file.
## Installation with Caddy
Run simpleauth as a service.
Make sure it can read your `passwd` file,
which you set up in the previous section.
You'll want a section like this in your Caddyfile:
```
forward_auth simpleauth:8080 {
uri /
copy_headers X-Simpleauth-Token
}
```
## Installation with Traefik
I don't use Traefik any longer, but when I did,
I had it set up like this:
```yaml
services:
my-cool-service:
# All your cool stuff here
deploy:
labels:
# Keep all your existing traefik stuff
traefik.http.routers.dashboard.middlewares: forward-auth
traefik.http.middlewares.forward-auth.forwardauth.address: http://simpleauth:8080/
simpleauth:
image: ghcr.io/nealey/simpleauth
secrets:
- password
deploy:
labels:
traefik.enable: "true"
traefik.http.routers.simpleauth.rules: "PathPrefix(`/`)"
traefik.http.services.simpleauth.loadbalancer.server.port: "8080"
secrets:
password:
file: password
name: password-v1
```
# How It Works
Simpleauth uses a token cookie, in addition to HTTP Basic authentication.
The token is an HMAC digest of an expiration timestamp,
plus the timestamp.
When the HMAC is good, and the timestamp is in the future,
the token is a valid authentication.
This technique means there is no persistent server storage.
If you use the default of pulling the session secret from the OS PRNG,
then everybody will have to log in again every time the server restarts.
You can use the `-secret` argument to provide a persistent secret,
so this won't happen.
Some things,
like WebDAV,
will only ever use HTTP Basic auth.
That's okay:
Simpleauth will issue a new token for every request,
and the client will ignore it.