loginsrv

Unnamed repository; edit this file 'description' to name the repository.
git clone git@jamesshield.xyz:repos/loginsrv.git
Log | Files | Refs | README | LICENSE

README.md (3844B)


      1 # loginsrv Caddy middleware
      2 
      3 Login plugin for Caddy, based on [tarent/loginsrv](https://github.com/tarent/loginsrv).
      4 The login is checked against a backend and then returned as a JWT token.
      5 This middleware is designed to play together with the [caddy-jwt](https://github.com/BTBurke/caddy-jwt) plugin.
      6 
      7 For a full documentation of loginsrv configuration and usage, visit the [loginsrv README.md](https://github.com/tarent/loginsrv).
      8 
      9 A small demo can be found in the [./demo](https://github.com/tarent/loginsrv/tree/master/caddy/demo) directory.
     10 
     11 ## Configuration of `JWT_SECRET`
     12 The jwt secret is taken from the environment variable `JWT_SECRET` if this variable is set.
     13 If a secret was configured in the directive config, this has higher priority and will be used over the environment variable in the case,
     14 that both are set. This way, it is also possible to configure different secrets for multiple hosts. If no secret was set at all,
     15 a random token is generated and used.
     16 
     17 **Note:** If using `JWT_SECRET_FILE` (see root README), `JWT_SECRET` is filled with the secret, to maintain compatibility.
     18 
     19 To be compatible with caddy-jwt the secret is also written to the environment variable JWT_SECRET, if this variable was not set before.
     20 This enables caddy-jwt to look up the same shared secret, even in the case of a random token. If the configuration uses different tokens
     21 for different server blocks, only the first one will be stored in environment variable. You can't use a random key as the jwt-secret
     22 and a custom one in the same caddyfile. If you want to have better control, of the integration with caddy-jwt, e.g. for multiple server blocks,
     23 you should configure the jwt behaviour in caddy-jwt with the `secret` or `publickey` directive.
     24 
     25 ## Cookie Name
     26 You can configure the cookie name by `cookie_name`. By default loginsrv and http.jwt use the same cookie name for the JWT token. 
     27 If you don't use the default, set related param `token_source cookie my_cookie_name` in http.jwt.
     28 
     29 ### Basic configuration
     30 Provide a login resource under /login, for user bob with password secret:
     31 ```
     32 login {
     33     simple bob=secret
     34 }
     35 ```
     36 
     37 ### Full configuration example
     38 ```
     39 login {
     40     success_url /after/login
     41     cookie_name alternativeName
     42     cookie_http_only true
     43     simple bob=secret
     44     osiam endpoint=http://localhost:8080,client_id=example-client,client_secret=secret
     45     htpasswd file=users
     46     github client_id=xxx,client_secret=yyy
     47     google client_id=xxx,client_secret=yyy,scope=email
     48 }
     49 ```
     50 
     51 ### Example caddyfile
     52 ```
     53 127.0.0.1
     54 
     55 root {$PWD}
     56 browse
     57 
     58 jwt {
     59     path /
     60     allow sub bob
     61 }
     62 
     63 login {
     64     simple bob=secret,alice=secret
     65 }
     66 ```
     67 
     68 ### Example caddyfile with dynamic redirects
     69 ```
     70 127.0.0.1
     71 
     72 root {$PWD}
     73 browse
     74 
     75 jwt {
     76     path /
     77     except /favicon.ico
     78     redirect /login?backTo={rewrite_uri}
     79     allow sub bob
     80     allow sub alice
     81 }
     82 
     83 login {
     84     simple bob=secret,alice=secret
     85     redirect_check_referer false
     86     redirect_host_file ../redirect_hosts.txt
     87 }
     88 ```
     89 
     90 ### Example caddyfile with Google login
     91 
     92 ```
     93 127.0.0.1
     94 
     95 root {$PWD}
     96 browse
     97 
     98 jwt {
     99     path /
    100     allow domain example.com
    101 }
    102 
    103 login {
    104     google client_id=xxx,client_secret=yyy
    105 }
    106 ```
    107 
    108 ### Potential issue with a different `cookie-name` in http.login and `token_source cookie cookie_name` in http.jwt
    109 
    110 1. If you use `redirect` in http.jwt and you:
    111    * Are redirected to http.jwt's `redirect` page that is in your caddyfile
    112    * Are unable to navigate to any page that is protected by http.login
    113    * Appear to be authenticated when you visit the `redirect` page or `/login`
    114 
    115 2. If you don't use `redirect` in http.jwt and you:
    116    * Are displayed a 401 error for the page you navigate to
    117    * Appear to be authenticated if you navigate to `/login`
    118 
    119 Possible solution:
    120 Confirm that `cookie-name` in http.login and `token_source cookie cookie_name` in http.jwt are identical