lucidAuth/README.md

# 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 loadbalancers/proxies/webservers (Apache, ~~Caddy~~, Lighttpd, 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://<fqdn>/lucidAuth.login.php` (where `<fqdn>` is the actual domain -or IP address- your webserver is listening on)  
- Edit your webserver's/proxy's configuration to use the new website for forward authentication:  
  - #### ~~in Apache~~    <small>(Soon™)</small>  

  - #### ~~in Caddy~~    <small>(Never, due to lacking functionality)</small>  

  - #### ~~in Lighttpd~~    <small>(Soon™)</small>  

  - #### in NGINX
  Add the following lines (adjust to reflect your existing configuration - more [details](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/)):  
  ```
  http {
          #...
          server {
          #...
            location /private/ {
              auth_request     /auth;
              auth_request_set $auth_status $upstream_status;
            }

            location = /auth {
              internal;
              proxy_pass              https://<fqdn>/lucidAuth.validateRequest.php;
              proxy_pass_request_body off;
              proxy_set_header        Content-Length "";
              proxy_set_header        X-Original-URI $request_uri;
            }
          }
  }
  ```

  - #### in Traefik  
  Add the following lines (change to reflect your existing configuration):  
#####   1.7.x (more [details](https://docs.traefik.io/v1.7/configuration/entrypoints/#forward-authentication))  
  ```
  [frontends.server1]
          entrypoints = ["https"]
          backend = "server1"
          [frontends.server1.auth.forward]
            address = "https://<fqdn>/lucidAuth.validateRequest.php"
          [frontends.server1.routes]
            [frontends.server1.routes.ext]
              rule = "Host:<fqdn>"
  ```
#####   2.x (more [details](https://docs.traefik.io/middlewares/forwardauth/))  
  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://<fqdn>/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.