goth

README

👻 Goth

A fiber 🚀 middleware to integrate authentication to your application. It uses lightweight adapters and providers interfaces to integrate with multi-providers.

Installation

$ go get github.com/zeiss/fiber-goth

Examples

See examples to understand the provided interfaces

License

MIT

Documentation

Index

• Variables
• func ContextWithProvider(ctx *fiber.Ctx, provider string) *fiber.Ctx
• func DecryptCookie(value, key string) (string, error)
• func EncryptCookie(value, key string) (string, error)
• func GenerateKey() string
• func GetStateFromContext(ctx *fiber.Ctx) string
• func NewBeginAuthHandler(config ...Config) fiber.Handler
• func NewCompleteAuthHandler(config ...Config) fiber.Handler
• func NewLogoutHandler(config ...Config) fiber.Handler
• func NewProtectMiddleware(config ...Config) fiber.Handler
• func NewProtectedHandler(handler fiber.Handler, config ...Config) fiber.Handler
• func NewSessionHandler(config ...Config) fiber.Handler
• func ProviderFromContext(c *fiber.Ctx) string
• func SessionFromContext(c *fiber.Ctx) (adapters.GothSession, error)
• func TokenFromContext(c *fiber.Ctx) string
• func TokenFromCookie(param string) func(c *fiber.Ctx) (string, error)
• type BeginAuthHandler
  • func (BeginAuthHandler) New(cfg Config) fiber.Handler
• type CompleteAuthCompleteHandler
  • func (CompleteAuthCompleteHandler) New(cfg Config) fiber.Handler
• type Config
• type Error
  • func NewError(code int, message ...string) *Error
  • func (e *Error) Error() string
• type GothHandler
• type LogoutHandler
  • func (LogoutHandler) New(cfg Config) fiber.Handler
• type Params
  • func (p *Params) Get(key string) string
• type ProtectMiddleware
• type ProtectedHandler
• type SessionHandler
  • func (SessionHandler) New(cfg Config) fiber.Handler

Variables

var (
	// ErrMissingProviderName is thrown if the provider cannot be determined.
	ErrMissingProviderName = NewError(http.StatusBadRequest, "missing provider name in request")
	// ErrMissingSession is thrown if there is no active session.
	ErrMissingSession = NewError(http.StatusBadRequest, "could not find a matching session for this request")
	// ErrBadSession is thrown if the session is invalid.
	ErrBadSession = NewError(http.StatusBadRequest, "session is invalid")
	// ErrMissingUser is thrown if the user is missing.
	ErrMissingUser = NewError(http.StatusBadRequest, "missing user")
	// ErrMissingCookie is thrown if the cookie is missing.
	ErrMissingCookie = NewError(http.StatusBadRequest, "missing session cookie")
	// ErrBadRequest is thrown if the request is invalid.
	ErrBadRequest = NewError(http.StatusBadRequest, "bad request")
)

var ConfigDefault = Config{
	ErrorHandler:        defaultErrorHandler,
	BeginAuthHandler:    BeginAuthHandler{},
	CompleteAuthHandler: CompleteAuthCompleteHandler{},
	LogoutHandler:       LogoutHandler{},
	SessionHandler:      SessionHandler{},
	IndexHandler:        defaultIndexHandler,
	Encryptor:           EncryptCookie,
	Decryptor:           DecryptCookie,
	Expiry:              "7h",
	CookieName:          "fiber_goth.session",
	Extractor:           TokenFromCookie("fiber_goth.session"),
	CookieSameSite:      fasthttp.CookieSameSiteLaxMode,
	CompletionURL:       "/",
	LoginURL:            "/login",
	LogoutURL:           "/logout",
	CallbackURL:         "/auth",
}

ConfigDefault is the default config.

Functions

func ContextWithProvider

func ContextWithProvider(ctx *fiber.Ctx, provider string) *fiber.Ctx

ContextWithProvider returns a new request context containing the provider.

func DecryptCookie

func DecryptCookie(value, key string) (string, error)

DecryptCookie Decrypts a cookie value with specific encryption key

func EncryptCookie

func EncryptCookie(value, key string) (string, error)

EncryptCookie Encrypts a cookie value with specific encryption key

func GenerateKey

func GenerateKey() string

GenerateKey Generates an encryption key

func GetStateFromContext

func GetStateFromContext(ctx *fiber.Ctx) string

GetStateFromContext return the state that is returned during the callback.

func NewBeginAuthHandler

func NewBeginAuthHandler(config ...Config) fiber.Handler

NewBeginAuthHandler creates a new middleware handler to start authentication.

func NewCompleteAuthHandler

func NewCompleteAuthHandler(config ...Config) fiber.Handler

NewBeginCompleteAuthHandler creates a new middleware handler to complete authentication.

func NewLogoutHandler

func NewLogoutHandler(config ...Config) fiber.Handler

NewLogoutHandler returns a new default logout handler.

func NewProtectMiddleware

func NewProtectMiddleware(config ...Config) fiber.Handler

NewProtectMiddleware returns a new default protect handler.

nolint:gocyclo

func NewProtectedHandler

func NewProtectedHandler(handler fiber.Handler, config ...Config) fiber.Handler

NewProtectedHandler returns a new default protected handler.

func NewSessionHandler

func NewSessionHandler(config ...Config) fiber.Handler

NewSessionHandler returns a new default session handler.

func ProviderFromContext

func ProviderFromContext(c *fiber.Ctx) string

ProviderFromContext returns the provider from the request context.

func SessionFromContext

func SessionFromContext(c *fiber.Ctx) (adapters.GothSession, error)

Session from the request context.

func TokenFromContext

func TokenFromContext(c *fiber.Ctx) string

TokenFromContext returns the token from the request context.

func TokenFromCookie

func TokenFromCookie(param string) func(c *fiber.Ctx) (string, error)

TokenFromCookie returns a function that extracts token from the cookie header.

Types

type BeginAuthHandler

type BeginAuthHandler struct{}

BeginAuthHandler is the default handler to begin the authentication process.

func (BeginAuthHandler) New

func (BeginAuthHandler) New(cfg Config) fiber.Handler

New creates a new handler to begin authentication.

type CompleteAuthCompleteHandler

type CompleteAuthCompleteHandler struct{}

CompleteAuthComplete is the default handler to complete the authentication process.

func (CompleteAuthCompleteHandler) New

func (CompleteAuthCompleteHandler) New(cfg Config) fiber.Handler

New creates a new handler to complete authentication.

type Config

type Config struct {
	// Next defines a function to skip this middleware when returned true.
	Next func(c *fiber.Ctx) bool

	// BeginAuthHandler is the handler to start authentication.
	BeginAuthHandler GothHandler

	// CompleteAuthHandler is the handler to complete the authentication.
	CompleteAuthHandler GothHandler

	// LogoutHandler is the handler to logout.
	LogoutHandler GothHandler

	// SessionHandler is the handler to manage the session.
	SessionHandler GothHandler

	// IndexHandler is the handler to display the index.
	IndexHandler fiber.Handler

	// ProtectedHandler is the handler to protect the route.
	ProtectedHandler fiber.Handler

	// CompletionFilter that is executed when responses need to returned.
	CompletionFilter func(c *fiber.Ctx) error

	// Secret is the secret used to sign the session.
	Secret string

	// Expiry is the duration that the session is valid for.
	Expiry string

	// CookieName is the name of the cookie used to store the session.
	CookieName string

	// CookieSameSite is the SameSite attribute of the cookie.
	CookieSameSite fasthttp.CookieSameSite

	// CookiePath is the path of the cookie.
	CookiePath string

	// CookieDomain is the domain of the cookie.
	CookieDomain string

	// CookieHTTPOnly is the HTTPOnly attribute of the cookie.
	CookieHTTPOnly bool

	// Encryptor is the function used to encrypt the session.
	Encryptor func(decryptedString, key string) (string, error)

	// Decryptor is the function used to decrypt the session.
	Decryptor func(encryptedString, key string) (string, error)

	// Adapter is the adapter used to store the session.
	// Adapter adapters.Adapter
	Adapter adapters.Adapter

	// LoginURL is the URL to redirect to when the user is not authenticated.
	LoginURL string

	// LogoutURL is the URL to redirect to when the user logs out.
	LogoutURL string

	// CallbackURL is the URL to redirect to when the user logs out.
	CallbackURL string

	// CompletionURL is the default url after completion
	CompletionURL string

	// ErrorHandler is executed when an error is returned from fiber.Handler.
	//
	// Optional. Default: DefaultErrorHandler
	ErrorHandler fiber.ErrorHandler

	// Extractor is the function used to extract the token from the request.
	Extractor func(c *fiber.Ctx) (string, error)
}

Config caputes the configuration for running the goth middleware.

type Error

type Error struct {
	Code    int
	Message string
}

Error is the default error type for the goth middleware.

func NewError

func NewError(code int, message ...string) *Error

NewError creates a new Error instance with an optional message

func (*Error) Error

func (e *Error) Error() string

Error makes it compatible with the `error` interface.

type GothHandler

type GothHandler interface {
	New(cfg Config) fiber.Handler
}

GothHandler is the interface for defining handlers for the middleware.

type LogoutHandler

type LogoutHandler struct{}

LogoutHandler is the default handler for the logout process.

func (LogoutHandler) New

func (LogoutHandler) New(cfg Config) fiber.Handler

New creates a new handler to logout.

type Params

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

Params maps the parameters of the Fiber context to the gothic context.

func (*Params) Get

func (p *Params) Get(key string) string

Get returns the value of a query paramater.

type ProtectMiddleware

type ProtectMiddleware struct{}

ProtectMiddleware is the default handler for the protection process.

type ProtectedHandler

type ProtectedHandler struct{}

ProtectedHandler is the default handler for the validation process.

type SessionHandler

type SessionHandler struct{}

SessionHandler is the default handler for the session.

func (SessionHandler) New

func (SessionHandler) New(cfg Config) fiber.Handler

New creates a new handler to manage the session.