httpauth

Documentation

Overview

Package httpauth provides authorization middleware for HTTP.

Index

• func GetSessionData(c *gin.Context) (any, bool)
• func MustGetSessionData(c *gin.Context) any
• type Middleware
  • func NewBearerTokenMiddleware(verifyToken VerifyTokenFunc, opts ...MiddlewareOpt) Middleware
  • func NewSessionCookieMiddleware(cookieName string, verifyCookie VerifyCookieFunc, opts ...MiddlewareOpt) Middleware
• type MiddlewareOpt
  • func AccessDeniedHandler(handler func(c *gin.Context)) MiddlewareOpt
  • func ErrorHandler(handler func(c *gin.Context, err error)) MiddlewareOpt
  • func UnverifiedHandler(handler func(c *gin.Context)) MiddlewareOpt
• type VerificationResult
• type VerifyCookieFunc
• type VerifyTokenFunc

Functions

func GetSessionData

func GetSessionData(c *gin.Context) (any, bool)

GetSessionData tries to extract session data set by middleware from the request's context.

func MustGetSessionData

func MustGetSessionData(c *gin.Context) any

MustGetSessionData extracts session data set by middleware from the request's context, or panics.

Types

type Middleware

type Middleware interface {
	// Authenticated enables access to all authenticated clients, no matter the roles.
	Authenticated() gin.HandlerFunc

	// AnyOfRoles enables access to only those clients who have at least one of the given roles associated with them.
	AnyOfRoles(allowedRoles ...string) gin.HandlerFunc

	// AllOfRoles enables access to only those clients who have all specified roles associated with them.
	AllOfRoles(requiredRoles ...string) gin.HandlerFunc
}

Middleware is an interface that represents a generic authorization middleware. It provides user-friendly API that can be easily integrated with existing Gin request handlers. Underlying implementation might utilize Basic Auth, Bearer-Token or other mechanisms but this API is transparent.

func NewBearerTokenMiddleware

func NewBearerTokenMiddleware(verifyToken VerifyTokenFunc, opts ...MiddlewareOpt) Middleware

NewBearerTokenMiddleware creates new bearer-token based Middleware. This middleware reads Authorization header and expects it to begin with "Bearer" string.

func NewSessionCookieMiddleware

func NewSessionCookieMiddleware(cookieName string, verifyCookie VerifyCookieFunc, opts ...MiddlewareOpt) Middleware

NewSessionCookieMiddleware creates new cookie-based Middleware. This middleware reads a cookie specified by cookieName argument and calls verifyCookie with its value.

type MiddlewareOpt

type MiddlewareOpt func(*middlewareHandlers)

MiddlewareOpt is an option to be specified when creating new middleware.

func AccessDeniedHandler

func AccessDeniedHandler(handler func(c *gin.Context)) MiddlewareOpt

AccessDeniedHandler sets an access denied handler for the middleware.

func ErrorHandler

func ErrorHandler(handler func(c *gin.Context, err error)) MiddlewareOpt

ErrorHandler sets an error handler for the middleware.

func UnverifiedHandler

func UnverifiedHandler(handler func(c *gin.Context)) MiddlewareOpt

UnverifiedHandler sets an unverified handler for the middleware.

type VerificationResult

type VerificationResult struct {
	// Verified tells the middleware whether given request has been authorized or not.
	// Returning false value for this field will immediately finish request with 401.
	Verified bool

	// Roles is a set of permissions associated with the entity identified by the credentials.
	// Roles are expected to be returned only if Verified is equal to true.
	Roles []string

	// SessionData is an optional field that associates some arbitrary value with the current session.
	// Request handlers are able to extract this value later by calling GetSessionData() / MustGetSessionData().
	SessionData any
}

VerificationResult is a structure returned by the user-provided token/cookie verification functions.

type VerifyCookieFunc

type VerifyCookieFunc = func(c *gin.Context, cookie string) (*VerificationResult, error)

VerifyCookieFunc is a user-provided function that is called in able to validate given cookie value.

type VerifyTokenFunc

type VerifyTokenFunc = func(c *gin.Context, token string) (*VerificationResult, error)

VerifyTokenFunc is a user-provided function that is called in able to validate given API token.