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, this can also be called by GET|POST /login?logout=true

API Examples

Example:

Default is to return the token as Content-Type application/jwt within the body.

curl -i --data "username=bob&password=secret" http://127.0.0.1:6789/login
HTTP/1.1 200 OK
Content-Type: application/jwt
Date: Mon, 14 Nov 2016 21:35:42 GMT
Content-Length: 100

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.-51G5JQmpJleARHp8rIljBczPFanWT93d_N_7LQGUXU

Example: Credentials as JSON

The credentials can also be sent JSON encoded.

curl -i -H 'Content-Type: application/json'  --data '{"username": "bob", "password": "secret"}' http://127.0.0.1:6789/login
HTTP/1.1 200 OK
Content-Type: application/jwt
Date: Mon, 14 Nov 2016 21:35:42 GMT
Content-Length: 100

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.-51G5JQmpJleARHp8rIljBczPFanWT93d_N_7LQGUXU

Example: web based flow with 'Accept: text/html'

Sets the JWT as a cookie and redirects to a web page.

curl -i -H 'Accept: text/html' --data "username=bob&password=secret" http://127.0.0.1:6789/login
HTTP/1.1 303 See Other
Location: /
Set-Cookie: jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.-51G5JQmpJleARHp8rIljBczPFanWT93d_N_7LQGUXU; HttpOnly

Example: AJAX call with JQuery to fetch a JWT token and create a cookie from it

Creates a cookie from a successful API call to login.

$.ajax({
	url: "http://localhost:8080/login",
	type: 'POST',
	dataType: 'text',
	contentType: 'application/json',
	data: JSON.stringify( { 
		'username': 'demo', 
		'password': 'demo'
	}),
	success: function(data) {
		document.cookie = "jwt_token=" + data + ";path=/";
	},
	error: function (xhr, ajaxOptions, thrownError) {
	}
});

Make sure your main page has JQuery:

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>

Redirects

The API has support for a redirect query parameter, e.g. ?backTo=/dynamic/return/path. For security reasons, the default behaviour is very restrictive:

• Only local redirects (same host) are allowed.
• The Referer header is checked to ensure that the call to the login page came from the same page.

These restrictions are there, to prevent you from unchecked redirect attacks, e.g. phishing or login attacks. If you know, what you are doing, you can disable the Referer check with --redirect-check-referer=false and provide a whitelist file for allowed external domains with --redirect-host-file=/some/domains.txt.

The JWT Token

Depending on the provider, the token may look as follows:

{
  "sub": "smancke",
  "picture": "https://avatars2.githubusercontent.com/u/4291379?v=3",
  "name": "Sebastian Mancke",
  "email": "[email protected]",
  "origin": "github"
}

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

Parameters for the provider:

Example:

loginsrv -htpasswd file=users

Httpupstream

Authentication against an upstream HTTP server by performing a HTTP Basic authentication request and checking the response for a HTTP 200 OK status code. Anything other than a 200 OK status code will result in a failure to authenticate.

Parameters for the provider:

Example:

loginsrv -httpupstream upstream=https://google.com,timeout=1s

OSIAM

OSIAM is a secure identity management solution providing REST based services for authentication and authorization. It implements the multiple OAuth2 flows, as well as SCIM for managing the user data.

To start loginsrv against the default OSIAM configuration on the same machine, use the following example.

loginsrv --jwt-secret=jwtsecret --text-logging -osiam endpoint=http://localhost:8080,client_id=example-client,client_secret=secret'

Then go to http://127.0.0.1:6789/login and login with admin/koala.

Simple

Simple is a demo provider for testing only. It holds a user/password table in memory.

Example

loginsrv -simple bob=secret

OAuth2

The OAuth Web Flow (aka 3-legged-OAuth flow) is also supported. Currently the following OAuth provider is supported:

• GitHub
• Google
• Bitbucket
• Facebook
• Gitlab

An OAuth provider supports the following parameters:

When configuring the OAuth parameters at your external OAuth provider, a redirect URI has to be supplied. This redirect URI has to point to the path /login/<provider>. If not supplied, the OAuth redirect URI is calculated out of the current URL. This should work in most cases and should even work if loginsrv is routed through a reverse proxy, if the headers X-Forwarded-Host and X-Forwarded-Proto are set correctly.

GitHub Startup Example

$ docker run -p 80:80 tarent/loginsrv -github client_id=xxx,client_secret=yyy

Templating

A custom template can be supplied by the parameter template. You can find the original template in login/login_form.go.

The templating uses the Golang template package. A short intro can be found here.

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:

<!DOCTYPE html>
<html>
  <head>
      <!-- your styles -->
  <head>
  <body>
      <!-- your header -->

      {{ if .Error}}
        <div class="alert alert-danger" role="alert">
          <strong>Internal Error. </strong> Please try again later.
        </div>
      {{end}}

      {{if .Authenticated}}

         {{template "userInfo" . }}

      {{else}}

        {{template "login" . }}

      {{end}}

      <!-- your footer -->
  </body>
</html>

Custom claims

To customize the content of the JWT token either a file wich contains user data or an endpoint providing claims can be provided.

User file

A user file is a YAML file which contains additional information which is encoded in the token. After successful authentication against a backend system, the user is searched within the file and the content of the claims parameter is used to enhance the user JWT claim parameters.

To match an entry, the user file is searched in linear order and all attributes has to match the data of the authentication backend. The first matching entry will be used and all parameters below the claim attribute are written into the token. The following attributes can be used for matching:

• sub - the username (all backends)
• origin - the provider or backend name (all backends)
• email - the mail address (the OAuth provider)
• domain - the domain (Google only)
• groups - the full path string of user groups enclosed in an array (Gitlab only)

Example:

• The user bob will become the "role": "superAdmin", when authenticating with htpasswd file
• The user [email protected] 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", independent of the authentication provider

- sub: bob
  origin: htpasswd
  claims:
    role: superAdmin

- email: [email protected]
  origin: Google
  claims:
    role: admin
    projects:
      - example

- domain: example.org
  origin: Google
  claims:
    role: user
    projects:
      - example

- groups:
    - example/subgroup
    - othergroup
  origin: gitlab
  claims:
    role: admin

- claims:
    role: unknown

User endpoint

A user endpoint is a http endpoint which provides additional information on an authenticated user. After successful authentication against a backend system, the endpoint gets called and the provided information is used to enhance the user JWT claim parameters.

loginsrv passes these parameters to the endpoint:

• sub - the username (all backends)
• origin - the provider or backend name (all backends)
• email - the mail address (the OAuth provider)
• domain - the domain (Google only)
• groups - the full path string of user groups enclosed in an array (Gitlab only)

An interaction looks like this

GET /claims?origin=google&[email protected]&[email protected] HTTP/1.1
Host: localhost:8080
Accept: */*
Authorization: Bearer token

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sub":"[email protected]",
  "uid":"113",
  "origin":"google",
  "permissions": ["read", "write"]
}