tarent/loginsrv repository overview

⁠loginsrv

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

⁠Abstract

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

• standalone microservice
• docker container
• golang library
• caddyserver⁠ plugin

NOTE: This Readme ist not updated automatically. For the latest version visit github.com/tarent/loginsrv⁠

⁠Supported Provider Backends

The following providers (login backends) are supported.

• Htpasswd⁠
• OSIAM⁠
• Simple⁠ (user/password pairs by configuration)
• Oauth2⁠
  • Github Login
  • .. google and facebook will come soon ..

⁠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. Incaddy, the parameter names can be 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 variable, where the name is written in the 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 80:80 tarent/loginsrv -jwt-secret my_secret -simple bob=secret

$ curl --data "username=bob&password=secret" 127.0.0.1/login
eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IifQ.uWoJkSXTLA_RvfLKe12pb4CyxQNxe5_Ovw-N5wfQwkzXz2enbhA9JZf8MmTp9n-TTDcWdY3Fd1SA72_M20G9lQ

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

$ docker run -d -p 80:80 -e LOGINSRV_JWT_SECRET=my_secret -e LOGINSRV_BACKEND=provider=simple,bob=secret tarent/loginsrv

⁠API

⁠GET /login

Returns a simple bootstrap styled login form.

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

Perfoms 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 BasicAuth Authentication.

⁠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 also could be send as 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 token as 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

⁠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 -backend 'provider=htpasswd,file=users

⁠OSIAM

OSIAM⁠ is a secure identity management solution providing REST based services for authentication and authorization. It implements the multplie 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 -backend 'provider=osiam,endpoint=http://localhost:8080,clientId=example-client,clientSecret=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 -backend provider=simple,bob=secret

⁠Oauth2

The Oauth Web Flow (aka 3-leged-Oauth flow) is also supported. Currently the following oauth Provider is supported:

• github

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 caclulated 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 build in template language. 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>