loginsrv

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

commit 14651bba903922fccb34776ef16aaf632c2fd878
parent 4f50a64b7c5a5c22e3cf356724b308c6e53fc32b
Author: Sebastian Mancke <sebastian.mancke@snabble.io>
Date:   Fri, 25 Jan 2019 10:59:37 +0100

Merge pull request #116 from magikstm/Fix-issue-115

Fix issue 115 and a few other minor doc issues
Diffstat:
MREADME.md | 16++++++++--------
Mcaddy/README.md | 27++++++++++++++-------------
2 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md @@ -54,7 +54,7 @@ For questions and support please use the [Gitter chat room](https://gitter.im/ta ## Configuration and Startup ### Config Options -_Note for Caddy users_: Not all parameters are available in Caddy. See the table for details. With Caddy, the parameter names can be also be used with `_` in the names, e.g. `cookie_http_only`. +_Note for Caddy users_: Not all parameters are available in Caddy. See the table for details. With Caddy, the parameter names can also be used with `_` in the names, e.g. `cookie_http_only`. | Parameter | Type | Default | Caddy | Description | |-----------------------------|-------------|--------------|-------|--------------------------------------------------------------------------------------------| @@ -99,7 +99,7 @@ So e.g. `jwt-secret` can be set by environment variable `LOGINSRV_JWT_SECRET`. The simplest way to use loginsrv is by the provided docker container. E.g. configured with the simple provider: ``` -$ docker run -d -p 8080:8080 tarent/loginsrv -secure-cookie=false -jwt-secret my_secret -simple bob=secret +$ docker run -d -p 8080:8080 tarent/loginsrv -cookie-secure=false -jwt-secret my_secret -simple bob=secret $ curl --data "username=bob&password=secret" 127.0.0.1:8080/login eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.uWoJkSXTLA_RvfLKe12pb4CyxQNxe5_Ovw-N5wfQwkzXz2enbhA9JZf8MmTp9n-TTDcWdY3Fd1SA72_M20G9lQ @@ -107,15 +107,15 @@ eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.uWoJkSXTLA_RvfLKe12pb4Cy The same configuration could be written with environment variables this way: ``` -$ docker run -d -p 8080:8080 -E SECURE_COOKIE=false -e LOGINSRV_JWT_SECRET=my_secret -e LOGINSRV_BACKEND=provider=simple,bob=secret tarent/loginsrv +$ docker run -d -p 8080:8080 -E COOKIE_SECURE=false -e LOGINSRV_JWT_SECRET=my_secret -e LOGINSRV_BACKEND=provider=simple,bob=secret tarent/loginsrv ``` ## API ### GET /login -Per default, it returns a simple bootstrap styled login form for unauthenticated requests an a small page with user info authenticated requests. -When the call accepts a JSON output, the json content of the token is returned authenticated requests. +Per default, it returns a simple bootstrap styled login form for unauthenticated requests and a page with user info for authenticated requests. +When the call accepts a JSON output, the json content of the token is returned to authenticated requests. The returned HTML follows the UI composition conventions from (lib-compose)[https://github.com/tarent/lib-compose], so it can be embedded into an existing layout. @@ -253,7 +253,7 @@ Depending on the provider, the token may look as follows: ## Provider Backends ### Htpasswd -Authentication against htpasswd file. MD5, SHA1 and Bcrypt are supported. But we recommend to only use bcrypt for security reasons (e.g. `htpasswd -B -C 15`). +Authentication against htpasswd file. MD5, SHA1 and Bcrypt are supported. But we recommend to only use Bcrypt for security reasons (e.g. `htpasswd -B -C 15`). Parameters for the provider: @@ -335,7 +335,7 @@ $ docker run -p 80:80 tarent/loginsrv -github client_id=xxx,client_secret=yyy A custom template can be supplied by the parameter `template`. You can find the original template in [login/login_form.go](https://github.com/tarent/loginsrv/blob/master/login/login_form.go). -The templating uses the Golang build in template language. A short intro can be found [here](https://astaxie.gitbooks.io/build-web-application-with-golang/en/07.4.html). +The templating uses the Golang template package. A short intro can be found [here](https://astaxie.gitbooks.io/build-web-application-with-golang/en/07.4.html). When you specify a custom template, only the layout of the original template is replaced. The partials of the original are still loaded into the template context and can be used by your template. So a minimal unstyled login template could look like this: @@ -389,7 +389,7 @@ Example: * The user admin@example.org will become `"role": "admin"` and `"projects": ["example"]`, when authenticating with Google OAuth * All other Google users with the domain example will become `"role": "user"` and `"projects": ["example"]` * All other Gitlab users with group `example/subgroup` and `othergroup` will become `"role": "admin"`. -* All others will become `"role": "unknown"`, indenpendent of the authentication provider +* All others will become `"role": "unknown"`, independent of the authentication provider ``` - sub: bob diff --git a/caddy/README.md b/caddy/README.md @@ -1,24 +1,24 @@ # loginsrv Caddy middleware Login plugin for Caddy, based on [tarent/loginsrv](https://github.com/tarent/loginsrv). -The login is checked against a backend and then returned as JWT token. +The login is checked against a backend and then returned as a JWT token. This middleware is designed to play together with the [caddy-jwt](https://github.com/BTBurke/caddy-jwt) plugin. For a full documentation of loginsrv configuration and usage, visit the [loginsrv README.md](https://github.com/tarent/loginsrv). -A small demo can also be found in the [./demo](https://github.com/tarent/loginsrv/tree/master/caddy/demo) directory. +A small demo can be found in the [./demo](https://github.com/tarent/loginsrv/tree/master/caddy/demo) directory. ## Configuration of `JWT_SECRET` -The jwt secret is taken from the environment variable `JWT_SECRET` if such a variable is set. +The jwt secret is taken from the environment variable `JWT_SECRET` if this variable is set. If a secret was configured in the directive config, this has higher priority and will be used over the environment variable in the case, that both are set. This way, it is also possible to configure different secrets for multiple hosts. If no secret was set at all, a random token is generated and used. -To be compatible with caddy-jwt the secred is also written to the environment variable JWT_SECRET, if this variable was not set before. -This enables caddy-jwt to look up the same shared secret, even in the case of a random token. If the configuration uses differnt tokens -for different server blocks, only the first one will be stored in enviroment environment variable. You can't use a random key as the jwt-secret +To be compatible with caddy-jwt the secret is also written to the environment variable JWT_SECRET, if this variable was not set before. +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 +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 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, -you should configure the jwt behaviour in caddy-jwt with the `secret` or `publickey` directives. +you should configure the jwt behaviour in caddy-jwt with the `secret` or `publickey` directive. ## Cookie Name You can configure the cookie name by `cookie_name`. By default loginsrv and http.jwt use the same cookie name for the JWT token. @@ -106,13 +106,13 @@ login { ### Potential issue with a different `cookie-name` in http.login and `token_source cookie cookie_name` in http.jwt 1. If you use `redirect` in http.jwt and you: -1.1. Are redirected to http.jwt's `redirect` page that is in your caddyfile -1.2. Are unable to navigate to any page that is protected by http.login -1.3. Appear to be authenticated when you visit the `redirect` page or `/login` + * Are redirected to http.jwt's `redirect` page that is in your caddyfile + * Are unable to navigate to any page that is protected by http.login + * Appear to be authenticated when you visit the `redirect` page or `/login` 2. If you don't use `redirect` in http.jwt and you: -2.1. Are displayed a 401 error for the page you navigate to -2.2. Appear to be authenticated if you navigate to `/login` + * Are displayed a 401 error for the page you navigate to + * Appear to be authenticated if you navigate to `/login` Possible solution: -Confirm that `cookie-name` in http.login and `token_source cookie cookie_name` in http.jwt are identical +Confirm that `cookie-name` in http.login and `token_source cookie cookie_name` in http.jwt are identical+ \ No newline at end of file