https://github.com/gbirke/traefik-sessionauth
A session-based authentication app for Traefik's forwardAuth middleware
https://github.com/gbirke/traefik-sessionauth
authentication session-cookie traefik
Last synced: 6 months ago
JSON representation
A session-based authentication app for Traefik's forwardAuth middleware
- Host: GitHub
- URL: https://github.com/gbirke/traefik-sessionauth
- Owner: gbirke
- Created: 2021-10-23T12:01:59.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2021-12-05T14:21:42.000Z (about 4 years ago)
- Last Synced: 2025-03-28T16:34:42.011Z (10 months ago)
- Topics: authentication, session-cookie, traefik
- Language: PHP
- Homepage:
- Size: 63.5 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Traefik-sessionauth
This is a small application that acts as an end point for the Traefik
forwardAuth middleware, authenticating users with a cookie and a
password-based login. You don't need any OAuth/based external services.
Think of it as "basic auth middleware without the browser popup".
## Configuration
Copy the `env.template` file to `.env` and edit it. There are two
important settings, `COOKIE_DOMAIN` and `USERS`:
`COOKIE_DOMAIN` is the top-level domain that's shared between the
application you want to secure and the login page. For example, if you
have the domains `app.example.com` and `auth.example.com` the
`COOKIE_DOMAIN` should be `example.com`.
`USERS` is a space-separated list of user names and passwords (separated
with a colon). You must hash passwords with PHPs `password_hash`
function. To hash a password on the command line you can run the following
command:
php -r 'echo password_hash("your_password_here", PASSWORD_DEFAULT);'
With the setting `SESSION_LIFETIME` you can change how long the session
persists between page interactions. Whenever Traefik queries the
authentication of the logged in user, the application sets the session
expiry to the current time plus lifetime. The default lifetime is 30
minutes (1800 seconds).
### Overriding templates
If you want to show some branding on your page, use different styling or
wording, you can edit the files in the [`templates`](templates/)
directory.
The file [`docker-compose.fullexample.yml`](docker-compose.fullexample.yml)
shows and example how to use docker volume mounts to override templates
## Running the application
Run `docker-compose up` to run the application as a standalone application
on [localhost:8090](http://localhost:8090/). On its own, it's not very
useful but you can use the `docker-compose.yml` setup for development or
to try out the functionality without a Traefik setup.
### Building the docker image
The Dockerfile in `docker/app/Dockerfile` is a
[multi-stage](https://docs.docker.com/develop/develop-images/multistage-build/)
Dockerfile that returns a production-ready image (using opcache and PHP
production settings). The `docker-compose.yml` file builds the development
image without opcache.
## Traefik setup
In the file [`docker-compose.fullexample.yml`](docker-compose.fullexample.yml)
you can find a full example of how to use the app:
* A **Traefik** container, configured to serve on port 80.
* The **authentication app**, running as a PHP-FPM service.
* An **Nginx** web server, running two sites:
* `site.example.docker` serves a single static page
* `auth.example.docker` is a reverse proxy for the authentication
application
The single Nginx configuration is for efficiency reasons, you could also
put the authentication app behind a second Nginx or a different web server
that acts as a FastCGI proxy.
To test the example on you local machine, you need to add the following
entries to your `/etc/hosts` file:
127.0.0.1 monitor.example.docker
127.0.0.1 site.example.docker
127.0.0.1 auth.example.docker
### Request handling for the protected site
```
Request for +---------------------+
site.example.docker Show if OK | |
---------------------> ForwardAuth ----------------->| site.example.docker |
| ^ | |
| | +---------------------+
| |
| |
| | OK or redirect to auth.example.docker/login
| +------------------------------+
| |
| +---------------------+
| | |
| OK to access? | auth.example.docker|
+---------------------------> | |
+---------------------+
```
### Pitfalls to look out for when configuring for your own site
Make sure you're using the right protocol for the forwardAuth middleware
address! If you set it to `http` and your authentication URL is `https`,
every forwardAuth request will fail, even when you're logged in, because
Traefik will redirect to the HTTPs protocol, which looks like a failure to
forwardAuth.
## Development
To use the pre-commit git hooks, run
vendor/bin/captainhook install
## Possible future features
* Make base path of auth configurable and concat base path with routes.
* Use encrypted cookies instead of session - this will make the app
storage-independent and allows for longer-lasting authentication.
* Add Page titles (Login page and index page) to config
* Unit tests and static analysis (see
https://odan.github.io/2020/06/09/slim4-testing.html for how to test)
* Add CI (GitHub Actions) to test and build Docker image
* Expose more session configuration
* Support for CORS headers instead of central cookie domain
* "Remember me" cookie for more independence from PHP sessions
* Describe PHP session tuning for longer-lived sessions and using
different storage mechanisms
* Rewrite in Go to get rid of the need for a FastCGI proxy.
* Serve SVG image badge that shows login status. Configurable SVG template
to allow perfect integration in site.