diff --git a/README.md b/README.md index b790784..00dbc43 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,64 @@ -# lucidAuth -[![](https://img.shields.io/badge/status-in%20production-%23003399.svg)](#) [![](https://img.shields.io/badge/contributors-1-green.svg) ](#) - -Forward Authentication for use with proxies (caddy, nginx, traefik, etc) - -## Usage -- Create a new folder, navigate to it in a commandprompt and run the following command: - `git clone https://code.spamasaurus.com/djpbessems/lucidAuth.git` -- Edit `include/lucidAuth.config.php.example` to reflect your configuration and save as `include/lucidAuth.config.php` -- Create a new website (within any php-capable webserver) and make sure that the documentroot points to the `public` folder -- Check if you are able to browse to `https:///lucidAuth.login.php` (where `` is the actual domain -or IP address- your webserver is listening on) -- Edit your proxy's configuration to use the new website as forward proxy: - - #### ~~in Caddy/nginx~~ (planned for a later stage) - - - #### in Traefik - Add the following lines (change to reflect your existing configuration): - ``` - [frontends.server1] - entrypoints = ["https"] - backend = "server1" - [frontends.server1.auth.forward] - address = "https:///lucidAuth.validateRequest.php" - [frontends.server1.routes] - [frontends.server1.routes.ext] - rule = "Host:" - ``` - -## Questions or bugs +# lucidAuth [![](https://img.shields.io/badge/status-in%20production-%23003399.svg)](#) [![](https://img.shields.io/badge/contributors-1-green.svg) ](#) +> *Respect* the unexpected, mitigate your risks + +Forward Authentication for use with proxies (caddy, nginx, traefik, etc) + +## Usage +- Create a new folder, navigate to it in a commandprompt and run the following command: + `git clone https://code.spamasaurus.com/djpbessems/lucidAuth.git` +- Edit `include/lucidAuth.config.php.example` to reflect your configuration and save as `include/lucidAuth.config.php` +- Create a new website (within any php-capable webserver) and make sure that the documentroot points to the `public` folder +- Check if you are able to browse to `https:///lucidAuth.login.php` (where `` is the actual domain -or IP address- your webserver is listening on) +- Edit your proxy's configuration to use the new website as forward proxy: + - #### ~~in Caddy/nginx~~ (planned for a later stage) + + - #### in Traefik + Add the following lines (change to reflect your existing configuration): +##### 1.7 + ``` + [frontends.server1] + entrypoints = ["https"] + backend = "server1" + [frontends.server1.auth.forward] + address = "https:///lucidAuth.validateRequest.php" + [frontends.server1.routes] + [frontends.server1.routes.ext] + rule = "Host:" + ``` +##### 2.0 + Either whitelist IP's which should be trusted to send `HTTP_X-Forwarded-*` headers, ór enable insecure-mode in your static configuration: + ``` + entryPoints: + https: + address: :443 + forwardedHeaders: + trustedIPs: + - "127.0.0.1/32" + - "192.168.1.0/24" + # insecure: true + ``` + Define a middleware that tells Traefik to forward requests for authentication in your dynamic file provider: + ``` + https: + middlewares: + ldap-authentication: + forwardAuth: + address: "https:///lucidAuth.validateRequest.php" + trustForwardHeader: true + ``` + And finally add the new middleware to your service (different methods; this depends on your configuration): + ``` + # as a label (when using Docker provider) + traefik.http.routers.router1.middlewares: "ldap-authentication@file" + # as yaml (when using file provider) + routers: + router1: + middlewares: + - "ldap-authentication" + ``` + +- #### Important! + The domainname of the website made in step 3, needs to match the domainname (*ignoring subdomains, if any*) of the resource utilizing this authentication proxy. + +## Questions or bugs Feel free to open issues in this repository. \ No newline at end of file