authware

README

authware - Its middleware, for auth

This is a collection of basic middlewares that allow you to authenticate users on a webserver. It is architected in such a way that the authenticators are not exclusively locked to HTTP use cases, and it is possible to get access to the authenticators directly. You can also write your own if you want a backend that this library does not support.

For information on how to use this library, consult the basic demo.

Documentation

Index

• func RegisterFactory(s string, f Factory)
• type Authenticator
  • func Initialize(s string) (Authenticator, error)
• type BasicMiddleware
  • func NewAuth() (*BasicMiddleware, error)
  • func (b *BasicMiddleware) BasicHandler(next http.Handler) http.Handler
  • func (b *BasicMiddleware) LoginFormHandler(userField, passField, defaultNext string) func(http.ResponseWriter, *http.Request)
  • func (b *BasicMiddleware) LoginHandler(loginPath string) func(http.Handler) http.Handler
  • func (b *BasicMiddleware) LogoutHandler(nextPath string) func(w http.ResponseWriter, r *http.Request)
  • func (b *BasicMiddleware) MultiAuthHandler() func(http.Handler) http.Handler
  • func (b *BasicMiddleware) SessionHandler() func(http.Handler) http.Handler
• type ErrBackendInternal
  • func (e ErrBackendInternal) Error() string
• type ErrDoesNotExist
  • func (e ErrDoesNotExist) Error() string
• type ErrUnauthenticated
  • func (e ErrUnauthenticated) Error() string
• type Factory
• type Middleware
• type Session
• type User
• type UserKey

Functions

func RegisterFactory

func RegisterFactory(s string, f Factory)

RegisterFactory idempotently registers factories for later initialization.

Types

type Authenticator

type Authenticator interface {
	AuthUserPassword(context.Context, string, string) error
	UserGroups(context.Context, string) (map[string]struct{}, error)
	Name() string
}

Authenticator authenticates a user based on some information they have provided. If an authenticator cannot satisfy a given request, it should return non-nil and the next authenticator in the chain will be tried. If no authenticator matches, then the request will be rejected.

func Initialize

func Initialize(s string) (Authenticator, error)

Initialize requests that an authenticator initialize and become ready, to be added to one or more middlewares. This function is exposed so that authenticators can be consumed directly outside of middlewares.

type BasicMiddleware

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

BasicMiddleware inserts HTTP basic auth requirements into the handler chain.

func NewAuth

func NewAuth() (*BasicMiddleware, error)

NewAuth returns a basic auth middleware.

func (*BasicMiddleware) BasicHandler

func (b *BasicMiddleware) BasicHandler(next http.Handler) http.Handler

BasicHandler implements the HTTP handler interface.

func (*BasicMiddleware) LoginFormHandler

func (b *BasicMiddleware) LoginFormHandler(userField, passField, defaultNext string) func(http.ResponseWriter, *http.Request)

LoginFormHandler responds to the form submit and cookies the request.

func (*BasicMiddleware) LoginHandler

func (b *BasicMiddleware) LoginHandler(loginPath string) func(http.Handler) http.Handler

LoginHandler sets up a middleware that handles input from a login form and sets a cookie.

func (*BasicMiddleware) LogoutHandler

func (b *BasicMiddleware) LogoutHandler(nextPath string) func(w http.ResponseWriter, r *http.Request)

LogoutHandler clears the cookie and sends the caller somewhere else.

func (*BasicMiddleware) MultiAuthHandler

func (b *BasicMiddleware) MultiAuthHandler() func(http.Handler) http.Handler

MultiAuthHandler tries to find a valid scheme and then perform auth using a given middleware.

func (*BasicMiddleware) SessionHandler

func (b *BasicMiddleware) SessionHandler() func(http.Handler) http.Handler

SessionHandler does the same verification that the LoginHandler does, but without the redirect.

type ErrBackendInternal

type ErrBackendInternal struct{}

ErrBackendInternal is returned whenever a backend has encountered an internal error that cannot be surfaced to the user.

func (ErrBackendInternal) Error

func (e ErrBackendInternal) Error() string

type ErrDoesNotExist

type ErrDoesNotExist struct{}

ErrDoesNotExist returns when a request is made that does not match a configured resource.

func (ErrDoesNotExist) Error

func (e ErrDoesNotExist) Error() string

type ErrUnauthenticated

type ErrUnauthenticated struct{}

ErrUnauthenticated returns when a request fails authentication

func (ErrUnauthenticated) Error

func (e ErrUnauthenticated) Error() string

type Factory

type Factory func() (Authenticator, error)

A Factory is an initializer that makes a concrete insantiation of an auth method.

type Middleware

type Middleware func(http.Handler) http.Handler

Middleware defines a function that can sit in the handler chain and potentially modify the response.

type Session

type Session struct {
	Expires time.Time
	User    User
}

Session contains the information that is encoded into the session cookie.

type User

type User struct {
	// Identity is whatever was passed as the user identifier.
	// This is a user controlled value, and may not be identical
	// to what was passed into the authentication backend by any
	// of the authenticators.
	Identity string

	// Groups is a map of group names that the user possesses.
	// This will be normalized by a backend as just the name, not
	// any path elements that may be required such as in an LDAP
	// context.
	Groups map[string]struct{}

	// AuthedBy specifies which backend successfully identified
	// this user.
	AuthedBy string
}

User is the normalized type that is returned for any authenticated entity.

type UserKey

type UserKey struct{}

The UserKey type exists purely as a key to insert into the http.Request contxt so that a user can be fished out by applications that want to have access to it later.