ginauth

Documentation

Overview

Package ginauth provides a authentication and authorization middleware for use with a gin server

Index

• Constants
• Variables
• func AbortBecauseOfError(c *gin.Context, err error)
• func NewInvalidSigningKeyError() error
• func NewTokenValidationError(err error) error
• type AuthError
  • func NewAuthenticationError(msg string) *AuthError
  • func NewAuthenticationErrorFrom(err error) *AuthError
  • func NewAuthorizationError(msg string) *AuthError
  • func (ae *AuthError) Error() string
  • func (ae *AuthError) Unwrap() error
• type AuthMeta
• type AuthRequestV1
  • func NewAuthRequestV1FromScopes(scopes []string) *AuthRequestV1
• type AuthResponseV1
• type ClaimMetadata
• type GenericAuthMiddleware
• type MultiTokenMiddleware
  • func NewMultiTokenMiddleware() (*MultiTokenMiddleware, error)
  • func (mtm *MultiTokenMiddleware) Add(middleware GenericAuthMiddleware) error
  • func (mtm *MultiTokenMiddleware) AuthRequired(scopes []string) gin.HandlerFunc
• type RemoteMiddleware
  • func NewRemoteMiddleware(url string, timeout time.Duration) *RemoteMiddleware
  • func (rm *RemoteMiddleware) AuthRequired(scopes []string) gin.HandlerFunc
  • func (rm *RemoteMiddleware) SetMetadata(c *gin.Context, cm ClaimMetadata)
  • func (rm *RemoteMiddleware) VerifyTokenWithScopes(c *gin.Context, scopes []string) (ClaimMetadata, error)
• type SuccessAuthDetailsV1
• type TokenValidationError
  • func (tve *TokenValidationError) Error() string
  • func (tve *TokenValidationError) Unwrap() error

Constants

const (
	// AuthRequestVersion1 defines version 1 of the AuthRequest message format
	AuthRequestVersion1 = "v1"
)

Variables

var (
	// ErrInvalidMiddlewareReference the middleware added was invalid
	ErrInvalidMiddlewareReference = errors.New("invalid middleware")

	// ErrMiddlewareRemote is the error returned when the middleware couldn't contact the remote endpoint
	ErrMiddlewareRemote = errors.New("middleware setup")

	// ErrAuthentication defines a generic authentication error. This specifies that we couldn't
	// validate a token for some reason. This is not to be used as-is but is useful for type
	// comparison with the `AuthError` struct.
	ErrAuthentication = errors.New("authentication error")

	// ErrInvalidSigningKey is the error returned when a token can not be verified because the signing key in invalid
	// NOTE(jaosorior): The fact that this is in this package is a little hacky... but it's to not have a
	// circular dependency with the ginjwt package.
	ErrInvalidSigningKey = errors.New("invalid token signing key")
)

Functions

func AbortBecauseOfError

func AbortBecauseOfError(c *gin.Context, err error)

AbortBecauseOfError aborts a gin context based on a given error

func NewInvalidSigningKeyError

func NewInvalidSigningKeyError() error

NewInvalidSigningKeyError returns an AuthError that indicates that the signing key used to validate the token was not valid

func NewTokenValidationError

func NewTokenValidationError(err error) error

NewTokenValidationError returns a TokenValidationError that wraps the given error

Types

type AuthError

type AuthError struct {
	HTTPErrorCode int
	// contains filtered or unexported fields
}

AuthError represents an auth error coming from a middleware function

func NewAuthenticationError

func NewAuthenticationError(msg string) *AuthError

NewAuthenticationError returns an authentication error which is due to not being able to determine who's the requestor (e.g. authentication error)

func NewAuthenticationErrorFrom

func NewAuthenticationErrorFrom(err error) *AuthError

NewAuthenticationErrorFrom returns an authentication error which is due to not being able to determine who's the requestor (e.g. authentication error). The error is based on another one (it wraps it).

func NewAuthorizationError

func NewAuthorizationError(msg string) *AuthError

NewAuthorizationError returns an authorization error which is due to not being able to determine what the requestor can do (e.g. authorization error)

func (*AuthError) Error

func (ae *AuthError) Error() string

Error ensures AuthenticationError implements the error interface

func (*AuthError) Unwrap

func (ae *AuthError) Unwrap() error

Unwrap ensures that we're able to verify that this is indeed an authentication error

type AuthMeta

type AuthMeta struct {
	Version string `json:"version"`
}

AuthMeta holds metdata for an AuthRequest

type AuthRequestV1

type AuthRequestV1 struct {
	AuthMeta `json:",inline"`
	Scopes   []string `json:"scopes"`
}

AuthRequestV1 holds a simple auth request which asks a remote endpoint for an authorization decision based on the given scopes

func NewAuthRequestV1FromScopes

func NewAuthRequestV1FromScopes(scopes []string) *AuthRequestV1

NewAuthRequestV1FromScopes creates an AuthRequest structure from the given scopes

type AuthResponseV1

type AuthResponseV1 struct {
	AuthMeta `json:",inline"`
	Authed   bool                  `json:"auth"`
	Message  string                `json:"message"`
	Details  *SuccessAuthDetailsV1 `json:"details,omitempty"`
}

AuthResponseV1 holds a simple auth response which denotes the auth decision. Note that the decision will also be reflected in the HTTP status code.

type ClaimMetadata

type ClaimMetadata struct {
	Subject string
	User    string
	Roles   []string
}

ClaimMetadata returns the minimal relevant information so middleware can set the appropriate metadata to a context (e.g. a gin.Context)

type GenericAuthMiddleware

type GenericAuthMiddleware interface {
	VerifyTokenWithScopes(*gin.Context, []string) (ClaimMetadata, error)
	SetMetadata(*gin.Context, ClaimMetadata)
}

GenericAuthMiddleware defines middleware that verifies a token coming from a gin.Context. Note that this can be stacked together using the MultiTokenMiddleware construct.

type MultiTokenMiddleware

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

MultiTokenMiddleware Allows for concurrently verifying a token using different middleware implementations. This relies on implementing the GenericAuthMiddleware interface. Only the first detected success will be taken into account. Note that middleware objects don't have to be of Middleware type, that's only one object that implements the interface.

func NewMultiTokenMiddleware

func NewMultiTokenMiddleware() (*MultiTokenMiddleware, error)

NewMultiTokenMiddleware builds a MultiTokenMiddleware object from multiple AuthConfigs.

func (*MultiTokenMiddleware) Add

func (mtm *MultiTokenMiddleware) Add(middleware GenericAuthMiddleware) error

Add will append another middleware object (or verifier) to the list which we'll use to check concurrently

func (*MultiTokenMiddleware) AuthRequired

func (mtm *MultiTokenMiddleware) AuthRequired(scopes []string) gin.HandlerFunc

AuthRequired is similar to the `AuthRequired` function from the Middleware type in the sense that it'll evaluate the scopes and the token coming from the context. However, this will concurrently evaluate them with the middlewares configured in this struct

type RemoteMiddleware

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

RemoteMiddleware defines middleware that relies on a remote endpoint in order to get an authorization decision

func NewRemoteMiddleware

func NewRemoteMiddleware(url string, timeout time.Duration) *RemoteMiddleware

NewRemoteMiddleware returns an instance of RemoteMiddleware TODO(jaosorior) Pass in TLS parameters

func (*RemoteMiddleware) AuthRequired

func (rm *RemoteMiddleware) AuthRequired(scopes []string) gin.HandlerFunc

AuthRequired provides a middleware that ensures a request has authentication

func (*RemoteMiddleware) SetMetadata

func (rm *RemoteMiddleware) SetMetadata(c *gin.Context, cm ClaimMetadata)

SetMetadata ensures metadata is set in the gin Context

func (*RemoteMiddleware) VerifyTokenWithScopes

func (rm *RemoteMiddleware) VerifyTokenWithScopes(c *gin.Context, scopes []string) (ClaimMetadata, error)

VerifyTokenWithScopes verifies a given token (from the gin Context) against the given scope using a remote server

type SuccessAuthDetailsV1

type SuccessAuthDetailsV1 struct {
	Subject string `json:"subject"`
	User    string `json:"user,omitempty"`
}

SuccessAuthDetailsV1 holds a simple and successful auth response.

type TokenValidationError

type TokenValidationError struct {
	AuthError
}

TokenValidationError specifies that there was an authentication error due to the token being invalid

func (*TokenValidationError) Error

func (tve *TokenValidationError) Error() string

Error ensures AuthenticationError implements the error interface

func (*TokenValidationError) Unwrap

func (tve *TokenValidationError) Unwrap() error

Unwrap allows TokenValidationError to be detected as an AuthError.