auth

Documentation

Index

• Variables
• func Append(s Strategy, key string, info Info, r *http.Request) error
• func RequestWithUser(info Info, r *http.Request) *http.Request
• func Revoke(s Strategy, key string, r *http.Request) error
• func SetInfoConstructor(c InfoConstructor)
• type Authenticator
  • func New(paths ...string) Authenticator
• type DefaultUser
  • func NewDefaultUser(name, id string, groups []string, extensions map[string][]string) *DefaultUser
  • func (d *DefaultUser) Extensions() map[string][]string
  • func (d *DefaultUser) Groups() []string
  • func (d *DefaultUser) ID() string
  • func (d *DefaultUser) SetExtensions(exts map[string][]string)
  • func (d *DefaultUser) SetGroups(groups []string)
  • func (d *DefaultUser) UserName() string
• type Info
  • func NewUserInfo(name, id string, groups []string, extensions map[string][]string) Info
  • func User(r *http.Request) Info
• type InfoConstructor
• type Strategy
• type StrategyKey

Examples

• Append
• Revoke

Variables

var (
	// ErrNoMatch is returned by Authenticator when request not authenticated,
	// and all registered Strategies returned errors.
	ErrNoMatch = errors.New("authenticator: No authentication strategy matched")

	// ErrDisabledPath is a soft error similar to EOF.
	// returned by Authenticator when a attempting to authenticate request have a disabled path.
	// Authenticator return DisabledPath only to signal the caller.
	// The caller should continue the request flow, and never return the error to the end users.
	ErrDisabledPath = errors.New("authenticator: Disabled Path")

	// ErrNOOP is a soft error similar to EOF,
	// returned by strategies that have NoOpAuthenticate function to indicate there no op,
	// and signal authenticator to unauthenticate the request.
	ErrNOOP = errors.New("NOOP")
)

var ErrInvalidStrategy = errors.New("Invalid strategy")

ErrInvalidStrategy is returned by Append/Revoke functions, when passed strategy does not implement Append/Revoke.

Functions

func Append

func Append(s Strategy, key string, info Info, r *http.Request) error

Append new Info to a strategy store. if passed strategy does not implement Append type ErrInvalidStrategy returned, Otherwise, nil.

WARNING: Append function does not guarantee safe concurrency, It's natively depends on strategy store.

Example

strategy := &mockStrategy{}
info := NewDefaultUser("1", "2", nil, nil)
token := "90d64460d14870c08c81352a05dedd3465940a7"
r, _ := http.NewRequest("POST", "/login", nil)
// append new token to cached bearer strategy
err := Append(strategy, token, info, r)
fmt.Println(err)

Output:

<nil>

func RequestWithUser

func RequestWithUser(info Info, r *http.Request) *http.Request

RequestWithUser Save user information in request context.

func Revoke

func Revoke(s Strategy, key string, r *http.Request) error

Revoke delete Info from strategy store. if passed strategy does not implement Revoke type ErrInvalidStrategy returned, Otherwise, nil.

WARNING: Revoke function does not guarantee safe concurrency, It's natively depends on strategy store.

Example

strategy := &mockStrategy{}
r, _ := http.NewRequest("GET", "/logout", nil)
// assume token extracted from header
token := "90d64460d14870c08c81352a05dedd3465940a7"
err := Revoke(strategy, token, r)
fmt.Println(err)

Output:

<nil>

func SetInfoConstructor

func SetInfoConstructor(c InfoConstructor)

SetInfoConstructor replace the default InfoConstructor with any function that has the appropriate signature. This allows the developers to create custom user info from their own struct instead of using the DefaultUser that go-guardian expose.

Default is NewDefaultUser

Types

type Authenticator

type Authenticator interface {
	// Authenticate dispatch the request to the registered authentication strategies,
	// and return user information from the first strategy that successfully authenticates the request.
	// Otherwise, an aggregated error returned.
	// if request attempt to visit a disabled path, ErrDisabledPath returned to signal the caller,
	// Otherwise, start the authentication process.
	// See ErrDisabledPath documentation for more info.
	//
	// NOTICE: Authenticate does not guarantee the order strategies run in.
	Authenticate(r *http.Request) (Info, error)
	// EnableStrategy register a new strategy to the authenticator.
	EnableStrategy(key StrategyKey, strategy Strategy)
	// DisableStrategy unregister a strategy from the authenticator.
	DisableStrategy(key StrategyKey)
	// Strategy return a registered strategy, Otherwise, nil.
	Strategy(key StrategyKey) Strategy
	// DisabledPaths return a map[string]struct{} represents a paths disabled from authentication.
	// Typically the paths are given during authenticator initialization.
	DisabledPaths() map[string]struct{}
}

Authenticator carry the registered authentication strategies, and represents the first API to authenticate received requests.

func New

func New(paths ...string) Authenticator

New return new Authenticator and disables authentication process at a given paths. The returned authenticator not safe for concurrent access.

type DefaultUser

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

DefaultUser implement Info interface and provides a simple user information.

func NewDefaultUser

func NewDefaultUser(name, id string, groups []string, extensions map[string][]string) *DefaultUser

NewDefaultUser return new default user

func (*DefaultUser) Extensions

func (d *DefaultUser) Extensions() map[string][]string

Extensions return additional information.

func (*DefaultUser) Groups

func (d *DefaultUser) Groups() []string

Groups returns the names of the groups the user is a member of

func (*DefaultUser) ID

func (d *DefaultUser) ID() string

ID returns a unique value identify a particular user

func (*DefaultUser) SetExtensions

func (d *DefaultUser) SetExtensions(exts map[string][]string)

SetExtensions to contain additional information.

func (*DefaultUser) SetGroups

func (d *DefaultUser) SetGroups(groups []string)

SetGroups set the names of the groups the user is a member of.

func (*DefaultUser) UserName

func (d *DefaultUser) UserName() string

UserName returns the name that uniquely identifies this user among all other active users.

type Info

type Info interface {
	// UserName returns the name that uniquely identifies this user among all
	// other active users.
	UserName() string
	// ID returns a unique value identify a particular user
	ID() string
	// Groups returns the names of the groups the user is a member of
	Groups() []string
	// Extensions can contain any additional information.
	Extensions() map[string][]string
	// SetGroups set the names of the groups the user is a member of.
	SetGroups(groups []string)
	// SetExtensions to contain additional information.
	SetExtensions(exts map[string][]string)
}

Info describes a user that has been authenticated to the system.

func NewUserInfo

func NewUserInfo(name, id string, groups []string, extensions map[string][]string) Info

NewUserInfo implements InfoConstructor and return Info object. Typically called from strategies to create a new user object when its authenticated.

func User

func User(r *http.Request) Info

User return user information from request context.

type InfoConstructor

type InfoConstructor func(name, id string, groups []string, extensions map[string][]string) Info

InfoConstructor define function signature to create new Info object.

type Strategy

type Strategy interface {
	// Authenticate users requests and return user information or error.
	Authenticate(ctx context.Context, r *http.Request) (Info, error)
}

Strategy represents an authentication mechanism or method to authenticate users requests.

type StrategyKey

type StrategyKey string

StrategyKey define a custom type to expose a strategy identifier.