ginjwt

Documentation

Overview

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

Index

• Variables
• func CreateScopes(items ...string) []string
• func DeleteScopes(items ...string) []string
• func GetSubject(c *gin.Context) string
• func GetUser(c *gin.Context) string
• func NewMultiTokenMiddlwareFromConfigs(cfgs ...AuthConfig) (*ginauth.MultiTokenMiddleware, error)
• func ReadScopes(items ...string) []string
• func RegisterViperOIDCFlags(v *viper.Viper, cmd *cobra.Command)
• func UpdateScopes(items ...string) []string
• func ViperBindFlag(name string, flag *pflag.Flag)
• type AuthConfig
  • func GetAuthConfigFromFlags(v *viper.Viper) (AuthConfig, error)
  • func GetAuthConfigsFromFlags(v *viper.Viper) ([]AuthConfig, error)
• type Middleware
  • func NewAuthMiddleware(cfg AuthConfig) (*Middleware, error)
  • func (m *Middleware) AuthRequired(scopes []string) gin.HandlerFunc
  • func (m *Middleware) SetMetadata(c *gin.Context, cm ginauth.ClaimMetadata)
  • func (m *Middleware) VerifyToken(c *gin.Context, scopes []string) (ginauth.ClaimMetadata, error)

Variables

var (
	// ErrInvalidAudience is the error returned when the audience of the token isn't what we expect
	ErrInvalidAudience = errors.New("invalid JWT audience")

	// ErrInvalidIssuer is the error returned when the issuer of the token isn't what we expect
	ErrInvalidIssuer = errors.New("invalid JWT issuer")

	// ErrMissingIssuerFlag is an error eturned when the issuer isn't provided via a command line flag.
	ErrMissingIssuerFlag = errors.New("issuer wasn't provided")

	// ErrMissingJWKURIFlag is an error eturned when the JWK URI isn't provided via a command line flag.
	ErrMissingJWKURIFlag = errors.New("JWK URI wasn't provided")

	// ErrIssuersDontMatchJWKURIs is the error returned when the number of issuers given
	// as command line flags don't match the number of JWK URIs given.
	ErrIssuersDontMatchJWKURIs = errors.New("the number of issuers doesn't match the number of JWK URIs")
)

Functions

func CreateScopes

func CreateScopes(items ...string) []string

CreateScopes will return a list of scopes allowed for creating the items that are passed in

func DeleteScopes

func DeleteScopes(items ...string) []string

DeleteScopes will return a list of scopes allowed for deleting the items that are passed in.

func GetSubject

func GetSubject(c *gin.Context) string

GetSubject will return the JWT subject that is saved in the request. This requires that authentication of the request has already occurred. If authentication failed or there isn't a user, an empty string is returned. This returns whatever value was in the JWT subject field and might not be a human readable value

func GetUser

func GetUser(c *gin.Context) string

GetUser will return the JWT user that is saved in the request. This requires that authentication of the request has already occurred. If authentication failed or there isn't a user an empty string is returned.

func NewMultiTokenMiddlwareFromConfigs

func NewMultiTokenMiddlwareFromConfigs(cfgs ...AuthConfig) (*ginauth.MultiTokenMiddleware, error)

NewMultiTokenMiddlwareFromConfigs builds a MultiTokenMiddleware object from multiple AuthConfigs.

func ReadScopes

func ReadScopes(items ...string) []string

ReadScopes will return a list of scopes allowed for creating the items that are passed in.

func RegisterViperOIDCFlags

func RegisterViperOIDCFlags(v *viper.Viper, cmd *cobra.Command)

RegisterViperOIDCFlags ensures that the given Viper and cobra.Command instances have the following command line/configuration flags registered:

* `oidc`: Enables/disables OIDC Authentication * `oidc-aud`: Specifies the expected audience for the JWT token * `oidc-issuer`: Specifies the expected issuer for the JWT token (can be more than one value) * `oidc-jwksuri`: Specifies the JSON Web Key Set (JWKS) URI (can be more than one value). * `oidc-roles-claim`: Specifies the roles to be accepted for the JWT claim. * `oidc-username-claim`: Specifies a username to use for the JWT claim

A call to this would normally look as follows:

ginjwt.RegisterViperOIDCFlags(viper.GetViper(), serveCmd)

Note that when specifying multiple issuers and JWK URIs, the amounts must match (e.g. there must be as many issuers as there are JWK URIs). The order of how these are specified matters too, the first issuer will match the first JWK URI when building an AuthConfig.

func UpdateScopes

func UpdateScopes(items ...string) []string

UpdateScopes will return a list of scopes allowed for updating the items that are passed in.

func ViperBindFlag

func ViperBindFlag(name string, flag *pflag.Flag)

ViperBindFlag provides a wrapper around the viper bindings that handles error checks

Types

type AuthConfig

type AuthConfig struct {
	Enabled       bool
	Audience      string
	Issuer        string
	JWKSURI       string
	LogFields     []string
	RolesClaim    string
	UsernameClaim string
}

AuthConfig provides the configuration for the authentication service

func GetAuthConfigFromFlags

func GetAuthConfigFromFlags(v *viper.Viper) (AuthConfig, error)

GetAuthConfigFromFlags builds an AuthConfig object from flags provided by the viper tooling. This utility function assumes that the `RegisterViperOIDCFlags` function was called beforehand.

A call to this would normally look as follows:

ginjwt.GetAuthConfigFromFlags(viper.GetViper())

Note that when using this function, this will retrieve the first issuer and JWK URI.

func GetAuthConfigsFromFlags

func GetAuthConfigsFromFlags(v *viper.Viper) ([]AuthConfig, error)

GetAuthConfigsFromFlags builds AuthConfig objects from flags provided by the viper tooling. This utility function assumes that the `RegisterViperOIDCFlags` function was called beforehand.

A call to this would normally look as follows:

ginjwt.GetAuthConfigsFromFlags(viper.GetViper())

Note that this function will retrieve as many AuthConfigs as the number of issuers and JWK URIs given (which must match)

type Middleware

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

Middleware provides a gin compatible middleware that will authenticate JWT requests

func NewAuthMiddleware

func NewAuthMiddleware(cfg AuthConfig) (*Middleware, error)

NewAuthMiddleware will return an auth middleware configured with the jwt parameters passed in

func (*Middleware) AuthRequired

func (m *Middleware) AuthRequired(scopes []string) gin.HandlerFunc

AuthRequired provides a middleware that ensures a request has authentication

func (*Middleware) SetMetadata

func (m *Middleware) SetMetadata(c *gin.Context, cm ginauth.ClaimMetadata)

SetMetadata sets the needed metadata to the gin context which came from the token

func (*Middleware) VerifyToken

func (m *Middleware) VerifyToken(c *gin.Context, scopes []string) (ginauth.ClaimMetadata, error)

VerifyToken verifies a JWT token gotten from the gin.Context object against the given scopes. This implements the GenericMiddleware interface