github.com/goadesign/goa/middleware/security/jwt

jwt

import "github.com/goadesign/goa/middleware/security/jwt"

Overview

Index

Package files

context.go error.go jwt.go resolver.go

Variables

var (
    // ErrEmptyHeaderName is returned when the header value given to the standard key resolver
    // constructor is empty.
    ErrEmptyHeaderName = errors.New("header name must not be empty")

    // ErrInvalidKey is returned when a key is not of type string, []string, *rsa.PublicKey or
    // []*rsa.PublicKey.
    ErrInvalidKey = errors.New("invalid parameter, the only keys accepted " +
        "are *rsa.publicKey, []*rsa.PublicKey (for RSA-based algorithms) or a " +
        "signing secret string, []string (for HS algorithms)")

    // ErrKeyDoesNotExist is returned when a key cannot be found by the provided key name.
    ErrKeyDoesNotExist = errors.New("key does not exist")

    // ErrJWTError is the error returned by this middleware when any sort of validation or
    // assertion fails during processing.
    ErrJWTError = goa.NewErrorClass("jwt_security_error", 401)
)

func ContextJWT

func ContextJWT(ctx context.Context) *jwt.Token

ContextJWT retrieves the JWT token from a context that went through our security middleware.

func New

func New(resolver KeyResolver, validationFunc goa.Middleware, scheme *goa.JWTSecurity) goa.Middleware

New returns a middleware to be used with the JWTSecurity DSL definitions of goa. It supports the scopes claim in the JWT and ensures goa-defined Security DSLs are properly validated.

The steps taken by the middleware are:

1. Extract the "Bearer" token from the Authorization header or query parameter
2. Validate the "Bearer" token against the key(s)
   given to New
3. If scopes are defined in the design for the action, validate them
   against the scopes presented by the JWT in the claim "scope", or if
   that's not defined, "scopes".

The exp (expiration) and nbf (not before) date checks are validated by the JWT library.

validationKeys can be one of these:

* []byte
* string
* an *rsa.PublicKey
* an *ecdsa.PublicKey
* a slice of any of the above

Keys of type string or []byte are interpreted according to the signing method defined in the JWT token’s typ header element: HS, RS, ES, etc.

You can define an optional function to do additional validations on the token once the signature and the claims requirements are proven to be valid. Example:

validationHandler, _ := goa.NewMiddleware(func(ctx context.Context, w http.ResponseWriter, r *http.Request) error {
    token := jwt.ContextJWT(ctx)
    claims, ok := token.Claims.(jwtgo.MapClaims)
    if !ok {
        return jwt.ErrJWTError("unsupported claims shape")
    }
    if val, ok := claims["is_uncle"].(string); !ok || val != "ben" {
        return jwt.ErrJWTError("you are not uncle ben's")
    }
    return nil
})

Mount the middleware with the generated UseXX function where XX is the name of the scheme as defined in the design, e.g.:

jwtResolver, _ := jwt.NewSimpleResolver("secret")
app.UseJWT(jwt.New(jwtResolver, validationHandler, app.NewJWTSecurity()))

func WithJWT

func WithJWT(ctx context.Context, t *jwt.Token) context.Context

WithJWT creates a child context containing the given JWT.

type GroupResolver

type GroupResolver struct {
    *sync.RWMutex
    // contains filtered or unexported fields
}

GroupResolver is a key resolver that switches on the value of a specified request header for selecting the key group used to authorize the incoming request.

func NewResolver

func NewResolver(keys map[string][]Key, header string) (*GroupResolver, error)

NewResolver returns a GroupResolver that uses the value of the request header with the given name to select the key group used for authorization. keys contains the initial set of key groups indexed by name.

func (*GroupResolver) AddKeys

func (kr *GroupResolver) AddKeys(name string, keys Key) error

AddKeys can be used to add keys to the resolver which will be referenced by the provided name. Acceptable types for keys include string, []string, *rsa.PublicKey or []*rsa.PublicKey. Multiple keys are allowed for a single key name to allow for key rotation.

func (*GroupResolver) GetAllKeys

func (kr *GroupResolver) GetAllKeys() []Key

GetAllKeys returns a list of all the keys stored in the resolver.

func (*GroupResolver) GetKeys

func (kr *GroupResolver) GetKeys(name string) ([]Key, error)

GetKeys returns a list of all the keys stored in the resolver under the provided name.

func (*GroupResolver) RemoveAllKeys

func (kr *GroupResolver) RemoveAllKeys()

RemoveAllKeys removes all keys from the resolver.

func (*GroupResolver) RemoveKey

func (kr *GroupResolver) RemoveKey(name string, key Key)

RemoveKey removes only the provided key stored under the provided name from the resolver.

func (*GroupResolver) RemoveKeys

func (kr *GroupResolver) RemoveKeys(name string)

RemoveKeys removes all keys from the resolver stored under the provided name.

func (*GroupResolver) SelectKeys

func (kr *GroupResolver) SelectKeys(req *http.Request) []Key

SelectKeys returns the keys in the group with the name identified by the request key selection header. If the header does value does not match a specific group then all keys are returned.

type Key

type Key interface{}

Key represents a public key used to validate the incoming token signatures. The value must be of type *rsa.PublicKey, *ecdsa.PublicKey, []byte or string. Keys of type []byte or string are interpreted depending on the incoming request JWT token method (HMAC, RSA, etc.).

type KeyResolver

type KeyResolver interface {
    // SelectKeys returns the group of keys to be used for the incoming request.
    SelectKeys(req *http.Request) []Key
}

KeyResolver allows the management of keys used by the middleware to verify the signature of incoming requests. Keys are grouped by name allowing the authorization algorithm to select a group depending on the incoming request state (e.g. a header). The use of groups enables key rotation.

func NewSimpleResolver

func NewSimpleResolver(keys []Key) KeyResolver

NewSimpleResolver returns a simple resolver.

Generated by godoc2md