lambda_jwt

Documentation

Overview

Package lambda_jwt appends critical libraries necessary for using JWTs (Json Web Tokens) within AWS Lambda through API Gateway proxy requests / integration. It adds multiple middleware functions for checking and validating permissions based on user type and has multiple examples of appending information from the caller's JWT directly into the golang context object so other handler functions can utilize the information. If you wish to use the standard 7 JWT values as defined by Auth0 at https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims then you want to use the jwt.StandardClaims object. If you wish to use an expanded claim set with a few additional helpful values like email and usertype then check out the ExpandedClaims object. If you wish to provide your own totally custom claim values and object then check out ExtractCustom.

Index

• Constants
• Variables
• func AllowOptionsMW(next lambda_router.Handler) lambda_router.Handler
• func DecodeExpanded(next lambda_router.Handler) lambda_router.Handler
• func DecodeStandard(next lambda_router.Handler) lambda_router.Handler
• func ExtendExpanded(claims ExpandedClaims) jwt.MapClaims
• func ExtendStandard(claims jwt.StandardClaims) jwt.MapClaims
• func ExtractCustom(mapClaims jwt.MapClaims, val any) error
• func ExtractJWT(headers map[string]string) (jwt.MapClaims, int, error)
• func ExtractStandard(mapClaims jwt.MapClaims, standardClaims *jwt.StandardClaims) error
• func GenerateEmptyErrorHandler() lambda_router.Handler
• func GenerateEmptySuccessHandler() lambda_router.Handler
• func InjectLambdaContextMW(next lambda_router.Handler) lambda_router.Handler
• func LogRequestMW(next lambda_router.Handler) lambda_router.Handler
• func Sign(mapClaims jwt.MapClaims) (string, error)
• func VerifyJWT(userJWT string) (jwt.MapClaims, error)
• type ExpandedClaims

Constants

const (
	AudienceKey  = "aud"
	EmailKey     = "email"
	ExpiresAtKey = "exp"
	FirstNameKey = "firstName"
	FullNameKey  = "fullName"
	IDKey        = "jti"
	IssuedAtKey  = "iat"
	IssuerKey    = "iss"
	LevelKey     = "level"
	NotBeforeKey = "nbf"
	SubjectKey   = "sub"
	UserTypeKey  = "userType"
)

Use these const values to populate your own custom claim values

const MethodKey = "method"

const MultiParamsKey = "multiParams"

const PathKey = "path"

const PathParamsKey = "pathParams"

const QueryParamsKey = "queryParams"

const RequestIDKey = "requestId"

Variables

var ErrBadClaimsObject = errors.New("lambda_jwt_router: the provided object to extract claims into is not compatible with the default claim set and its types")

var ErrInvalidJWT = errors.New("lambda_jwt_router: the provided JWT is invalid")

var ErrInvalidToken = errors.New("lambda_jwt_router: the provided jwt was unable to be parsed into a token")

var ErrInvalidTokenClaims = errors.New("lambda_jwt_router: the provided jwt was unable to be parsed for map claims")

var ErrNoAuthorizationHeader = errors.New("no Authorization header value set")

var ErrNoBearerPrefix = errors.New("missing 'Bearer ' prefix for Authorization header value")

var ErrUnableToSignToken = errors.New("lambda_jwt_router: the provided claims were unable to be signed")

var ErrUnsupportedSigningMethod = errors.New("lambda_jwt_router:the provided signing method is unsupported. HMAC only allowed")

var ErrVerifyJWT = errors.New("unable to verify JWT to retrieve claims. try logging in again to ensure it is not expired")

Functions

func AllowOptionsMW

func AllowOptionsMW(next lambda_router.Handler) lambda_router.Handler

AllowOptionsMW is a helper middleware function that will immediately return a successful request if the method is OPTIONS. This makes sure that HTTP OPTIONS calls for CORS functionality are supported.

func DecodeExpanded

func DecodeExpanded(next lambda_router.Handler) lambda_router.Handler

DecodeExpanded attempts to parse a Json Web Token from the request's "Authorization" header. If the Authorization header is missing, or does not contain a valid Json Web Token (JWT) then an error message and appropriate HTTP status code will be returned. If the JWT is correctly set and contains an instance of ExpandedClaims then the values from that standard claim will be added to the context object for others to use during their processing.

func DecodeStandard

func DecodeStandard(next lambda_router.Handler) lambda_router.Handler

DecodeStandard attempts to parse a Json Web Token from the request's "Authorization" header. If the Authorization header is missing, or does not contain a valid Json Web Token (JWT) then an error message and appropriate HTTP status code will be returned. If the JWT is correctly set and contains a StandardClaim then the values from that standard claim will be added to the context object for others to use during their processing.

func ExtendExpanded

func ExtendExpanded(claims ExpandedClaims) jwt.MapClaims

ExtendExpanded returns an instance of jwt.MapClaims which you can freely extend with your own custom fields. It uses ExpandedClaims as the base struct to start with and returns a jwt.MapClaims which is just a wrapper for a map so you can add as many custom fields as you would like while still getting the 7 standard JWT fields and the 4 non-standard fields defined in this library.

func ExtendStandard

func ExtendStandard(claims jwt.StandardClaims) jwt.MapClaims

ExtendStandard returns an instance of jwt.MapClaims which you can freely extend with your own custom fields. It uses jwt.StandardClaims as the base struct to start with and returns a jwt.MapClaims which is just a wrapper for a map so you can add as many custom fields as you would like while still getting the 7 standard JWT fields.

func ExtractCustom

func ExtractCustom(mapClaims jwt.MapClaims, val any) error

ExtractCustom takes in a generic claims map that can have any values set and attempts to pull out whatever custom struct you should have previously used to create the claims originally. An error will be returned if the generic map that stores the claims can't be converted to the struct of your choice through JSON marshalling.

func ExtractJWT

func ExtractJWT(headers map[string]string) (jwt.MapClaims, int, error)

ExtractJWT will attempt to extract the JWT value and retrieve the map claims from an events.APIGatewayProxyRequest object. If there is an error that will be returned along with an appropriate HTTP status code as an integer. If everything goes right then error will be nil and the int will be http.StatusOK

func ExtractStandard

func ExtractStandard(mapClaims jwt.MapClaims, standardClaims *jwt.StandardClaims) error

ExtractStandard accepts a generic claims map that can have any values set and attempts to pull out a standard jwt.StandardClaims object from the claims map. The input claims should have been generated originally by a jwt.StandardClaims instance so they can be cleanly extracted back into an instance of jwt.StandardClaims.

func GenerateEmptyErrorHandler

func GenerateEmptyErrorHandler() lambda_router.Handler

func GenerateEmptySuccessHandler

func GenerateEmptySuccessHandler() lambda_router.Handler

func InjectLambdaContextMW

func InjectLambdaContextMW(next lambda_router.Handler) lambda_router.Handler

InjectLambdaContextMW with do exactly that - inject all appropriate lambda values into the local context so that other users down the line can query the context for things like HTTP method or Path

func LogRequestMW

func LogRequestMW(next lambda_router.Handler) lambda_router.Handler

LogRequestMW is a standard middleware function that will log every incoming events.APIGatewayProxyRequest request and the pertinent information in it.

func Sign

func Sign(mapClaims jwt.MapClaims) (string, error)

Sign accepts a final set of claims, either jwt.StandardClaims, ExpandedClaims, or something entirely custom that you have created yourself. It will sign the claims using the HMAC value loaded from environment variables and return the signed JWT if no error, otherwise the empty string and an error. To convert a GoLang struct to a claims object use ExtendStandard or ExtendExpanded to get started.

func VerifyJWT

func VerifyJWT(userJWT string) (jwt.MapClaims, error)

VerifyJWT accepts the user JWT from the Authorization header and returns the MapClaims or nil and an error set.

Types

type ExpandedClaims

type ExpandedClaims struct {
	Audience  string `json:"aud"`
	Email     string `json:"email"`
	ExpiresAt int64  `json:"exp"`
	FirstName string `json:"firstName"`
	FullName  string `json:"fullName"`
	ID        string `json:"jti"`
	IssuedAt  int64  `json:"iat"`
	Issuer    string `json:"iss"`
	Level     string `json:"level"`
	NotBefore int64  `json:"nbf"`
	Subject   string `json:"sub"`
	UserType  string `json:"userType"`
}