auth

Documentation

Overview

Package auth contains types for authenticating and authorizing requests.

Index

• Constants
• Variables
• func UserFromContext(ctx context.Context) *empire.User
• func WithSession(ctx context.Context, session *Session) context.Context
• type Auth
  • func (a *Auth) Authenticate(ctx context.Context, username, password, otp string, strategies ...string) (context.Context, error)
  • func (a *Auth) PrependAuthenticator(name string, authenticator Authenticator) *Auth
• type Authenticator
  • func Anyone(user *empire.User) Authenticator
  • func MultiAuthenticator(authenticators ...Authenticator) Authenticator
  • func StaticAuthenticator(username, password, otp string, user *empire.User) Authenticator
  • func WithMaxSessionDuration(auth Authenticator, exp func() time.Time) Authenticator
• type AuthenticatorFunc
  • func (fn AuthenticatorFunc) Authenticate(username, password, otp string) (*Session, error)
• type Authorizer
  • func CacheAuthorization(a Authorizer, expiration time.Duration) Authorizer
• type AuthorizerFunc
  • func (fn AuthorizerFunc) Authorize(user *empire.User) error
• type Session
  • func NewSession(user *empire.User) *Session
  • func SessionFromContext(ctx context.Context) *Session
• type Strategies
  • func (s Strategies) AuthenticatorFor(strategies ...string) Authenticator
• type Strategy
• type UnauthorizedError
  • func (e *UnauthorizedError) Error() string

Constants

const (
	StrategyUsernamePassword = "UsernamePassword"
	StrategyAccessToken      = "AccessToken"
)

Some common names for strategies.

Variables

var (
	// ErrForbidden can be returned from Authenticator implementations when
	// the user provides invalid credentials.
	ErrForbidden = errors.New("auth: forbidden")

	// ErrTwoFactor can be returned by an Authenticator implementation when
	// a two factor code is either invalid or required.
	ErrTwoFactor = errors.New("auth: two factor code required or invalid")
)

Functions

func UserFromContext

func UserFromContext(ctx context.Context) *empire.User

UserFromContext returns a user from a context.Context if one is present.

func WithSession

func WithSession(ctx context.Context, session *Session) context.Context

WithSession embeds the authentication Session in the context.Context.

Types

type Auth

type Auth struct {
	Strategies Strategies
	Authorizer Authorizer
}

Auth provides a simple wrapper around, authenticating the user, pre-authorizing the request, then embedding a set of ACL policy to authorize the action.

func (*Auth) Authenticate

func (a *Auth) Authenticate(ctx context.Context, username, password, otp string, strategies ...string) (context.Context, error)

Authenticate authenticates the request using the named strategy, and returns a new context.Context with the user embedded. The user can be retrieved with UserFromContext.

func (*Auth) PrependAuthenticator

func (a *Auth) PrependAuthenticator(name string, authenticator Authenticator) *Auth

AddAuthenticator returns a shallow copy of the Auth object with the given authentication method added.

type Authenticator

type Authenticator interface {
	// Authenticate should check the credentials and return a login Session.
	Authenticate(username, password, twofactor string) (*Session, error)
}

Authenticator represents something that, given a username, password and OTP can authenticate an Empire user.

func Anyone

func Anyone(user *empire.User) Authenticator

Anyone returns an Authenticator that let's anyone in and sets them as the given user.

func MultiAuthenticator

func MultiAuthenticator(authenticators ...Authenticator) Authenticator

MultiAuthenticator returns an Authenticator that tries each Authenticator until one succeeds or they all fail.

It will proceed to the next authenticator when the error returned is ErrForbidden. Any other errors are bubbled up (e.g. ErrTwoFactor).

func StaticAuthenticator

func StaticAuthenticator(username, password, otp string, user *empire.User) Authenticator

StaticAuthenticator returns an Authenticator that returns the provided user when the given credentials are provided.

func WithMaxSessionDuration

func WithMaxSessionDuration(auth Authenticator, exp func() time.Time) Authenticator

WithMaxSessionDuration wraps an Authenticator to ensure that sessions always have a maximum lifetime. If the Session already has an expiration that will expire before d, the existing expiration is left in tact.

type AuthenticatorFunc

type AuthenticatorFunc func(string, string, string) (*Session, error)

AuthenticatorFunc is a function signature that implements the Authenticator interface.

func (AuthenticatorFunc) Authenticate

func (fn AuthenticatorFunc) Authenticate(username, password, otp string) (*Session, error)

Authenticate calls the AuthenticatorFunc.

type Authorizer

type Authorizer interface {
	// Authorize should check that the user has access to perform the
	// action. If not, ErrUnauthorized should be returned.
	Authorize(*empire.User) error
}

Authorizer represents something that can perform an authorization check.

func CacheAuthorization

func CacheAuthorization(a Authorizer, expiration time.Duration) Authorizer

CacheAuthorization wraps an Authorizer in an in memory cache that expires after the given expiration. Only positive authorizations will be cached.

type AuthorizerFunc

type AuthorizerFunc func(*empire.User) error

func (AuthorizerFunc) Authorize

func (fn AuthorizerFunc) Authorize(user *empire.User) error

type Session

type Session struct {
	// The authenticated User.
	User *empire.User

	// When this Session will expire. The zero value means no expiration.
	ExpiresAt *time.Time
}

Session represents an authenticated Session.

func NewSession

func NewSession(user *empire.User) *Session

NewSession returns a new Session for the user.

func SessionFromContext

func SessionFromContext(ctx context.Context) *Session

SessionFromContext returns the embedded Session in the context.Context.

type Strategies

type Strategies []*Strategy

Strategies wraps a slice of *Strategy with helpers for authenticating with a specific strategy.

func (Strategies) AuthenticatorFor

func (s Strategies) AuthenticatorFor(strategies ...string) Authenticator

AuthenticatorFor builds an Authenticator using the given strategies (by name). If no strategies are provided, all strategies will be used. If a strategy is not found, a fake strategy will be returned that will return an error when used.

type Strategy

type Strategy struct {
	Authenticator

	// The name of this strategy.
	Name string

	// When true, disables using this strategy by default, unless the
	// strategy is explicitly requested.
	Disabled bool
}

Strategy wraps an authenticator with a name.

type UnauthorizedError

type UnauthorizedError struct {
	// A user friendly message for why the user isn't authorized.
	Reason string
}

UnauthorizedError can be returned from Authorizer implementations when the user is not authorized to perform an action.

func (*UnauthorizedError) Error

func (e *UnauthorizedError) Error() string