middleware

Documentation

Index

• Constants
• Variables
• func Authenticate(opts ...AuthOption) (_ gin.HandlerFunc, err error)
• func Authorize(permissions ...string) gin.HandlerFunc
• func ContextFromRequest(c *gin.Context) (ctx context.Context, err error)
• func DoubleCookie() gin.HandlerFunc
• func GenerateCSRFToken() (_ string, err error)
• func GetAccessToken(c *gin.Context) (tks string, err error)
• func GetClaims(c *gin.Context) (*tokens.Claims, error)
• func SetDoubleCookieToken(c *gin.Context, domain string, expires time.Time) error
• type AuthOption
  • func WithAudience(audience string) AuthOption
  • func WithAuthOptions(opts AuthOptions) AuthOption
  • func WithContext(ctx context.Context) AuthOption
  • func WithIssuer(issuer string) AuthOption
  • func WithJWKSEndpoint(url string) AuthOption
  • func WithMinRefreshInterval(interval time.Duration) AuthOption
  • func WithValidator(validator tokens.Validator) AuthOption
• type AuthOptions
  • func NewAuthOptions(opts ...AuthOption) (conf AuthOptions)
  • func (conf *AuthOptions) Validator() (_ tokens.Validator, err error)

Constants

const (
	ContextUserClaims         = "user_claims"
	ContextAccessToken        = "access_token"
	DefaultKeysURL            = "https://auth.ensign.app/.well-known/jwks.json"
	DefaultAudience           = "https://ensign.app"
	DefaultIssuer             = "https://auth.ensign.app"
	DefaultMinRefreshInterval = 5 * time.Minute
)

const (
	CSRFCookie          = "csrf_token"
	CSRFReferenceCookie = "csrf_reference_token"
	CSRFHeader          = "X-CSRF-TOKEN"
)

Parameters and headers for double-cookie submit CSRF protection

Variables

var (
	ErrUnauthenticated  = errors.New("request is unauthenticated")
	ErrNoClaims         = errors.New("no claims found on the request context")
	ErrNoUserInfo       = errors.New("no user info found on the request context")
	ErrInvalidAuthToken = errors.New("invalid authorization token")
	ErrAuthRequired     = errors.New("this endpoint requires authentication")
	ErrNoPermission     = errors.New("user does not have permission to perform this operation")
	ErrNoAuthUser       = errors.New("could not identify authenticated user in request")
	ErrNoAuthUserData   = errors.New("could not retrieve user data")
	ErrIncompleteUser   = errors.New("user is missing required fields")
	ErrUnverifiedUser   = errors.New("user is not verified")
	ErrCSRFVerification = errors.New("csrf verification failed for request")
	ErrParseBearer      = errors.New("could not parse Bearer token from Authorization header")
	ErrNoAuthorization  = errors.New("no authorization header in request")
	ErrNoRequest        = errors.New("no request found on the context")
)

Functions

func Authenticate

func Authenticate(opts ...AuthOption) (_ gin.HandlerFunc, err error)

Authenticate middleware ensures that the request has a valid Bearer JWT in the Authenticate header of the request otherwise it stops processing of the request and returns a 401 unauthorized error. A valid Bearer JWT means that the access token is supplied as the Bearer token, it is unexpired, and it was issued by Quarterdeck by checking with the Quarterdeck public keys.

In order to perform authorization, this middleware fetches public JSON Web Key Sets (JWKS) from the authorizing Quarterdeck server and then caches them according to the Cache-Control or Expires headers in the response. As Quarterdeck keys are rotated, the cache must refresh the public keys in a background routine in order to correctly authorize incoming JWT tokens. Users can control how the JWKS are fetched and cached using AuthOptions (which are particularly helpful for tests).

func Authorize

func Authorize(permissions ...string) gin.HandlerFunc

Authorize is a middleware that requires specific permissions in an authenticated user's claims. If those permissions do not match or the request is unauthenticated the middleware returns a 401 response. The Authorize middleware must be chained following the Authenticate middleware.

func ContextFromRequest

func ContextFromRequest(c *gin.Context) (ctx context.Context, err error)

ContextFromRequest creates a context from the gin request context, copying fields that may be required for forwarded requests. This method should be called by handlers which need to forward requests to other services and need to preserve data from the original request such as the user's credentials.

func DoubleCookie

func DoubleCookie() gin.HandlerFunc

DoubleCookie is a Cross-Site Request Forgery (CSR/XSRF) protection middleware that checks the presence of an X-CSRF-TOKEN header containing a cryptographically random token that matches a token contained in the CSRF-TOKEN cookie in the request. Because of the same-origin poicy, an attacker cannot access the cookies or scripts of the safe site, therefore the X-CSRF-TOKEN header cannot be forged, and if it is omitted because it is being re-posted by an attacker site then the request will be rejected with a 403 error. Note that this protection requires TLS to prevent MITM.

func GenerateCSRFToken

func GenerateCSRFToken() (_ string, err error)

func GetAccessToken

func GetAccessToken(c *gin.Context) (tks string, err error)

GetAccessToken retrieves the bearer token from the authorization header and parses it to return only the JWT access token component of the header. If the header is missing or the token is not available, an error is returned. TODO: switch to regular expression based parsing.

func GetClaims

func GetClaims(c *gin.Context) (*tokens.Claims, error)

GetClaims fetches and parses Quarterdeck claims from the gin context. Returns an error if no claims exist on the context; panics if the claims are not the correct type -- however the panic should be recovered by middleware.

func SetDoubleCookieToken

func SetDoubleCookieToken(c *gin.Context, domain string, expires time.Time) error

SetDoubleCookieToken is a helper function to set cookies on a gin request.

Types

type AuthOption

type AuthOption func(opts *AuthOptions)

AuthOption allows users to optionally supply configuration to the Authorization middleware.

func WithAudience

func WithAudience(audience string) AuthOption

WithAudience allows the user to specify an alternative audience.

func WithAuthOptions

func WithAuthOptions(opts AuthOptions) AuthOption

WithAuthOptions allows the user to update the default auth options with an auth options struct to set many options values at once. Zero values are ignored, so if using this option, the defaults will still be preserved if not set on the input.

func WithContext

func WithContext(ctx context.Context) AuthOption

WithContext allows the user to specify an external, cancelable context to control the background refresh behavior of the JWKS cache.

func WithIssuer

func WithIssuer(issuer string) AuthOption

WithIssuer allows the user to specify an alternative issuer.

func WithJWKSEndpoint

func WithJWKSEndpoint(url string) AuthOption

WithJWKSEndpoint allows the user to specify an alternative endpoint to fetch the JWKS public keys from. This is useful for testing or for different environments.

func WithMinRefreshInterval

func WithMinRefreshInterval(interval time.Duration) AuthOption

WithMinRefreshInterval allows the user to specify an alternative minimum duration between cache refreshes to control refresh behavior for the JWKS public keys.

func WithValidator

func WithValidator(validator tokens.Validator) AuthOption

WithValidator allows the user to specify an alternative validator to the auth middleware. This is particularly useful for testing authentication.

type AuthOptions

type AuthOptions struct {
	KeysURL            string          // The URL endpoint to the JWKS public keys on the Quarterdeck server
	Audience           string          // The audience to verify on tokens
	Issuer             string          // The issuer to verify on tokens
	MinRefreshInterval time.Duration   // Minimum amount of time the JWKS public keys are cached
	Context            context.Context // The context object to control the lifecycle of the background fetch routine
	// contains filtered or unexported fields
}

AuthOptions is constructed from variadic AuthOption arguments with reasonable defaults.

func NewAuthOptions

func NewAuthOptions(opts ...AuthOption) (conf AuthOptions)

NewAuthOptions creates an AuthOptions object with reasonable defaults and any user supplied input from the AuthOption variadic arguments.

func (*AuthOptions) Validator

func (conf *AuthOptions) Validator() (_ tokens.Validator, err error)

Validator returns the user supplied validator or constructs a new JWKS Cache Validator from the supplied options. If the options are invalid or the validator cannot be created an error is returned.