multipass

README

Multipass

Better authentication for HTTP

Multipass is like HTTP Basic authentication but better and without passwords.

Multipass implements the idea to authenticate users based on something they own instead of something they know. This is better known as the second factor of Two-factor Authentication.

Multipass comes in two forms; a single binary to run in front of your web services and as a package to include in your Go project.

Installation

Download the binary from the releases page or build from source.

Usage

$ multipass -conf multipass.conf

For an example configuration see Configuration.

Contribution

Bug reports and feature requests are welcome. Follow GiHub's guide to using-pull-requests.

Goal

Protect internet exposed web resources and services with automatic HTTPS (TLS) and provide user friendly authentication.

Motivation

Many private web resources and services end up exposed on the internet, accessible by anyone. Think IP video cameras, Key-value stores, analytic applications and many more. Using Multipass, these web resources and services can be protected using automatic HTTPS (TLS) and access can be granted on an individual basis.

Further reading

• Configuration
• How it Works
  • User Flow
  • Configuration
  • JWT
  • RSA Key Pairs
  • Automatic HTTPS
  • Reverse Proxy
• Include in Go project
• Extending

Build

The Multipass binary depends on the excellent Caddy webserver.

1. Get the Caddy web server source code:

   $ go get github.com/mholt/caddy
   

2. Register Multipass as a caddy plugin by adding multipass to the caddy directive:

   Open $GOPATH/src/github.com/mholt/caddy/caddyhttp/httpserver/plugin.go in your favorite editor and make the following changes.

   var directives = []string{
   	...
    	"expvar",
   	"multipass", // <- insert this line somewhere before "proxy"
   	"proxy",
   	...
   }
   

3. Get the Multipass source code and build the command:

   $ go get github.com/namsral/multipass
   $ go install github.com/namsral/multipass/cmd/multipass
   

The next thing is to create a configuration file and run the multipass command.

Configuration

Syntax

Use the following syntax:

multipass {
	resources   path [path]
	handles     email [email]
	basepath    path
	expires     duration
	smtp_addr   host:port
	smtp_user   username
	smtp_pass   password
	smtp_client command [args...]
	mail_from   email
	mail_tmpl   path
}

• resources: path of resources to protect. Default: /
• handles: the handles which identify the users; accepts wildcards like '@' and '@dallas'. Required
• basepath: path to the log-in and sign-out page. Default: /multipass
• expires: The time duration after which the token expires. Any time duration Go can parse. Default: 24h
• smtp_addr: Mailserver address used for sending login links. Default: localhost:25
• smtp_user: Mailserver username used for authentication.
• smtp_pass: Mailserver password used for authentication.
• smtp_client: SMTP client command with arguments. Mutually exclusive with smtp_addr
• mail_from: From address used in email messages sent to users. Required
• mail_tmpl: Path to mail template to override deault subject, plain and html body.

Examples:

In the following example, the service running on localhost:2016 is proxied and protected to allow only users with handles leeloo@dallas and korben@dallas to access the /fhloston and /paradise resources.

example.com {
	bind 0.0.0.0
	multipass {
		resources /fhloston /paradise
		handles leeloo@dallas korben@dallas
		basepath /multipass
		expires 24h
		smtp_addr localhost:2525
		mail_from "Multipass <no-reply@dallas>"
	}
	proxy / localhost:2016
	log stdout
}

Same example but replaced the SMTP server with a SMTP client and accepts a domain wildcard:

example.com {
	bind 0.0.0.0
	multipass {
		resources /fhloston /paradise
		handles @dallas
		basepath /multipass
		expires 24h
		smtp_client /usr/sbin/sendmail -t -i
		mail_from "Multipass <no-reply@dallas>"
	}
	proxy / localhost:2016
	log stdout
}

How it works

Multipass works by sending the user a login link with an embedded access token. When the user follows the login link the access token is stored in the browser session and used to authenticate the user on successive requests. The access token is a JSON web token containing claims specific to Multipass and signed with a RSA key pair.

User flow:

1. User visits protected resource
2. User is redirected to log-in page and enters a known handle, e.g. email address
3. An user access token is sent to user in the form of a login link
4. User follows the login link and is granted access the protected resource

JWT

Access tokens are signed JSON Web Tokens with specific claims like user handle and expire date. The tokens are embedded in login links which are sent to user.

RSA key pairs

A RSA key pair is used to sign user access tokens. These access tokens and other signatures can be verified by others using the public key made available at the url [siteaddr][basepath]/pub.cer when Multipass is running.

You can set your own private RSA key in the MULTIPASS_RSA_PRIVATE_KEY environment variable; make sure to PEM encode the private key.

When no private key is set, the MULTIPASS_RSA_PRIVATE_KEY environment variable is empty, a RSA key pair is randomly generated and stored in the environment. This ensures signatures still validate after Multipass reloads during a configuration reload.

Automatic HTTPS

Multipass piggybacks on the Caddy web server which comes with automatic HTTPS using Let's Encrypt and many more features and plugins.

Reverse Proxy

The user handle which was used to authenticate the user is passed down to the protected web services as a HTTP header:

Multipass-Handle: <user handle>

Include in Go project

Multipass comes with multipass.AuthHandler which can wrap any http.Handler to provide Multipass authentication. Handlers from other routers and frameworks can be supported, see the caddy sub-package for an example.

In the example below, the appHandler function is wrapped using the AuthHandler wrapper. It assumes you have a SMTP service running on localhost:2525 and a user identified by email address leeloo@dallas whom has access to the resource at /private.

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/namsral/multipass"
	"github.com/namsral/multipass/services/email"
)

func appHandler(w http.ResponseWriter, r *http.Request) {
	handle := r.Header.Get("Multipass-Handle")
	if len(handle) == 0 {
		handle = "anonymous"
	}
	switch r.URL.Path {
	case "/", "/private":
		fmt.Fprintf(w, "Hello %s, welcome to %s", handle, r.URL.Path)
		return
	}
	http.NotFound(w, r)
}

func main() {
	service, err := email.NewUserService(email.Options{
		SMTPAddr: "localhost:2525",
		FromAddr: "Multipass Bot <noreply@dallas>",
	})
	if err != nil {
		log.Fatal(err)
	}
	service.AddHandle("leeloo@dallas") // Register user
	service.AddResource("/private")    // Make resource private

	addr := "localhost:6080"
	siteaddr := "http://" + addr
	m := multipass.New(siteaddr, multipass.Service(service))

	h := multipass.AuthHandler(http.HandlerFunc(appHandler), m)
	log.Fatal(http.ListenAndServe(addr, h))
}

Extending

Extending Multipass by implementing the UserService interface.

By implementing the UserService, shown below, Multipass can be extended to support other user handles which can identify and other ways to notify users of requested login URLs.

// UserService is an interface used by the Multipass instance to query about
// listed handles, authorized resource access and to notify users about login
// urls. A handle is a unique user identifier, e.g. username, email address.
type UserService interface {
	// Listed returns true when the given handle is listed with the
	// service.
	Listed(handle string) bool

	// Authorized returns true when the user identified by the given handle is
	// authorized to access the given resource at rawurl with the given method.
	Authorized(handle, method, rawurl string) bool

	// Notify returns nil when the given login URL is successfully
	// communicated to the given handle.
	Notify(handle, loginurl string) error

	// Close closes any open connections.
	Close() error
}

Documentation

Overview

Package multipass implements an authentication service which can be used to wrap any http.Handler(Func).

Multipass implements the concept to authenticate users based on something they own instead of something they know. This is better known as the second factor of Two-factor Authentication.

Quick Start

Wrap any http.Handler or http.HandlerFunc to provide user authentication. In the example below, the appHandler function is wrapped using the AuthHandler wrapper. It assumes you have a SMTP service running on `localhost:2525` and user identified by email address leeloo@dallas has access to the resource at `/private`.

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/namsral/multipass"
	"github.com/namsral/multipass/services/email"
)

func appHandler(w http.ResponseWriter, r *http.Request) {
	handle := r.Header.Get("Multipass-Handle")
	if len(handle) == 0 {
		handle = "anonymous"
	}
	switch r.URL.Path {
	case "/", "/private":
		fmt.Fprintf(w, "Hello %s, welcome to %s", handle, r.URL.Path)
		return
	}
	http.NotFound(w, r)
}

func main() {
	service, err := email.NewUserService(email.Options{
		SMTPAddr: "localhost:2525",
		FromAddr: "Multipass Bot <noreply@dallas>",
	})
	if err != nil {
		log.Fatal(err)
	}
	service.AddHandle("leeloo@dallas") // Register user
	service.AddResource("/private")    // Make resource private

	addr := "localhost:6080"
	siteaddr := "http://" + addr
	m := multipass.New(siteaddr, multipass.Service(service))

	h := multipass.AuthHandler(http.HandlerFunc(appHandler), m)
	log.Fatal(http.ListenAndServe(addr, h))
}

The package consist of three major components; Multipass, ResourceHandler and UserService.

Multipass

Multipass is a http.Handler which issues and signs user tokens and validates their signature.

func New(siteaddr string, opts ...Option) *Multipass {

Multipass has it's own web UI which is available at the configurable basepath. From the web UI users can request a login url to gain access to private resources.

UserService

User authorization is offloaded to the UserService service. Because the UserService is an interface custom UserService's can be developed and plugged into the Multipass instance. Allowing other means of authentication and authorization besides the built-in email UserService.

// UserService is an interface used by the Multipass instance to query about
// listed handles, authorized resource access and to notify users about login
// urls. A handle is a unique user identifier, e.g. username, email address.
type UserService interface {
	// Listed returns true when the given handle is listed with the
	// service.
	Listed(handle string) bool

	// Authorized returns true when the user identified by the given handle is
	// authorized to access the given resource at rawurl with the given method.
	Authorized(handle, method, rawurl string) bool

	// Notify returns nil when the given login URL is successfully
	// communicated to the given handle.
	Notify(handle, loginurl string) error

	// Close closes any open connections.
	Close() error
}

An implementation can be found in the `services/email` package. This implementations identifies users by their email address.

ResourceHandler

ResourceHandler accepts a http.ResponseWriter and http.Request and determines if the request is from an authenticated user and if this user is authorized to access the requested resource according to the UserService. The ResourceHandler extracts any user token from the header, cookie header or query parameters and validates the user tokens signature with preset or pre-generated key pairs.

func ResourceHandler(w http.ResponseWriter, r *http.Request, m *Multipass) (int, error) {

Index

• Constants
• Variables
• func AuthHandler(next http.Handler, m *Multipass) http.Handler
• func ConcatonateHeader(h http.Header) []byte
• func GetTokenRequest(r *http.Request) string
• func NewLoginURL(siteaddr, Basepath, token string, v url.Values) (*url.URL, error)
• func PrivateKeyFromEnvironment() (*rsa.PrivateKey, error)
• func ResourceHandler(w http.ResponseWriter, r *http.Request, m *Multipass) (int, error)
• func SignHeader(h http.Header, key *rsa.PrivateKey) error
• func VerifySignedHeader(h http.Header, key *rsa.PublicKey) error
• type Claims
• type Multipass
  • func New(siteaddr string, opts ...Option) *Multipass
  • func (m *Multipass) AccessToken(handle string) (tokenStr string, err error)
  • func (m *Multipass) Basepath() string
  • func (m *Multipass) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Option
  • func Basepath(basepath string) Option
  • func CSRF(b bool) Option
  • func Expires(d time.Duration) Option
  • func Service(s UserService) Option
  • func Template(t template.Template) Option
• type UserService

Constants

const (
	DefaultDigest  = "SHA256"
	DefaultAlgo    = "RSASSA-PSS"
	DefaultKeySize = 2048
)

Portable constants

const (
	PKENV = "MULTIPASS_RSA_PRIVATE_KEY"
)

Portable constants

Variables

var (
	ErrInvalidToken = errors.New("invalid token")
	ErrForbidden    = errors.New(http.StatusText(http.StatusForbidden))
	ErrUnauthorized = errors.New(http.StatusText(http.StatusUnauthorized))
)

Portable errors

var (
	ErrInvalidSignature = errors.New("invalid signature")
)

Portable errors

Functions

func AuthHandler

func AuthHandler(next http.Handler, m *Multipass) http.Handler

AuthHandler wraps any http.Handler to provide authentication using the given Multipass instance. Handlers from other http routers can be wrapped with little effort by copying the AuthHandler and make minor changes.

func ConcatonateHeader

func ConcatonateHeader(h http.Header) []byte

ConcatonateHeader returns concatination of the given headers. Headers are sorted, trimmed of whitespace, and converted to lowercase. Multiple headers with the same name are joined using commas to separate values.

func GetTokenRequest

func GetTokenRequest(r *http.Request) string

GetTokenRequest returns the JWT token embedded in the given request. JWT tokens can be embedded in the header prefixed with "Bearer ", with a "token" key query parameter or a cookie named "jwt_token".

func NewLoginURL

func NewLoginURL(siteaddr, Basepath, token string, v url.Values) (*url.URL, error)

NewLoginURL returns a login url which can be used as a time limited login. Optional values will be encoded in the login URL.

func PrivateKeyFromEnvironment

func PrivateKeyFromEnvironment() (*rsa.PrivateKey, error)

PrivateKeyFromEnvironment returns the private key as indicated by the environment variable MULTIPASS_RSA_PRIVATE_KEY. The environment value must be a PEM encoding key starting with "-----BEGIN RSA PRIVATE KEY-----".

A nil PrivateKey and nil error are returned if no private key is found in the environment variable value.

func ResourceHandler

func ResourceHandler(w http.ResponseWriter, r *http.Request, m *Multipass) (int, error)

ResourceHandler validates the token in the request before it writes the response. It adds the user handle if the user is authenticated and signs the any Multipass specific headers.

func SignHeader

func SignHeader(h http.Header, key *rsa.PrivateKey) error

SignHeader signs the given header and adds the key with name "Multipass-Signature". The signature is generated using the RSA_PSS algorithm and sha-256 digest.

func VerifySignedHeader

func VerifySignedHeader(h http.Header, key *rsa.PublicKey) error

VerifySignedHeader verifies the signed header with the given public key. It returns an erros when the key with name "Multipass-Signature" is not set.

Types

type Claims

type Claims struct {
	Handle  string `json:"handle"`
	Expires int64  `json:"exp"`
}

Claims are part of the JSON web token

type Multipass

type Multipass struct {
	// contains filtered or unexported fields
}

Multipass implements the http.Handler interface which can handle authentication and authorization of users and resources using signed JWT.

func New

func New(siteaddr string, opts ...Option) *Multipass

New returns a new instance of Multipass with the given site address.

The site address must point to the absolute base URL of the site.

Multipass is initialized with the following defaults:

2048 bit key size
/multipass Basepath
24h token lifespan

func (*Multipass) AccessToken

func (m *Multipass) AccessToken(handle string) (tokenStr string, err error)

AccessToken returns a new signed and serialized token with the given handle as a claim.

func (*Multipass) Basepath

func (m *Multipass) Basepath() string

Basepath return the base path.

func (*Multipass) ServeHTTP

func (m *Multipass) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP satisfies the ServeHTTP interface

type Option

type Option func(*Multipass)

Option describes a functional option for configuring the Multipass instance.

func Basepath

func Basepath(basepath string) Option

Basepath overrides the default base path of `/multipass`. The given basepath is made absolute before it is set.

func CSRF

func CSRF(b bool) Option

CSRF sets a bool wether to protect against CSRF attaks. The default is true.

func Expires

func Expires(d time.Duration) Option

Expires sets the maximum age for JWT tokens. When a token exceeds the maximum age it is no longer valid.

func Service

func Service(s UserService) Option

Service sets the UserService and overrides DefaultUserService.

func Template

func Template(t template.Template) Option

Template sets the template to use for generating the web interface.

type UserService

type UserService interface {
	// Listed returns true when the given handle is listed with the
	// service.
	Listed(handle string) bool

	// Authorized returns true when the user identified by the given handle is
	// authorized to access the given resource at rawurl with the given method.
	Authorized(handle, method, rawurl string) bool

	// Notify returns nil when the given login URL is successfully
	// communicated to the given handle.
	Notify(handle, loginurl string) error

	// Close closes any open connections.
	Close() error
}

UserService is an interface used by the Multipass instance to query about listed handles, authorized resource access and to notify users about login urls. A handle is a unique user identifier, e.g. username, email address.