loginsrv

loginsrv is a standalone minimalistic login server providing a JWT login for multiple login backends.

Attention: Update to v1.3.0 for Google Login Update !!!!

Google will stop support for the Google+ APIs. So we changed loginsrv to use the standard oauth endpoints for Google login. Please update loginsrv to v1.3.0 if you are using google login.

Attention: Since v1.3.0, pure HTTP is not supported by default

Since v1.3.0, loginsrv sets the secure flag for the login cookie. So, if you use HTTP fo connect with the browser, e.g. for testing, you browser will ignore the cookie. Use the flag -cookie-secure=false when testing without HTTPS.

Abstract

Loginsrv provides a minimal endpoint for authentication. The login is performed against the providers and returned as a JSON Web Token (JWT). It can be used as:

• Standalone microservice
• Docker container
• Golang library
• Caddy plugin. (See caddy/README.md for details)

Supported Provider Backends

The following providers (login backends) are supported.

• Htpasswd
• OSIAM
• Simple (user/password pairs by configuration)
• Httpupstream
• OAuth2
• GitHub login
• Google login
• Bitbucket login
• Facebook login
• Gitlab login

Questions

For questions and support please use the Gitter chat room.

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 also be used with _ in the names, e.g. cookie_http_only.

Environment Variables

All of the above Config Options can also be applied as environment variables by using variables named this way: LOGINSRV_OPTION_NAME. So e.g. jwt-secret can be set by environment variable LOGINSRV_JWT_SECRET.

Startup Examples

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 -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

The same configuration could be written with environment variables this way:

$ 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 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.

GET /login/

Starts the OAuth Web Flow with the configured provider. E.g. GET /login/github redirects to the GitHub login form.

POST /login

Performs the login and returns the JWT. Depending on the content-type and parameters, a classical JSON-Rest or a redirect can be performed.

Runtime Parameters

Possible Return Codes

Hint: The status 401 Unauthorized is not used as a return code to not conflict with an HTTP Basic authentication.

JWT-Refresh

If the POST-Parameters for username and password are missing and a valid JWT-Cookie is part of the request, then the JWT-Cookie is refreshed. This only happens if the jwt-refreshes config option is set to a value greater than 0.

DELETE /login

Deletes the JWT cookie.

For simple usage in web applications, thi