signature_jwt

Documentation

Overview

Package signature_jwt implements signature verification for MessageBird webhooks.

To use define a new validator using your MessageBird Signing key. Can be retrieved from https://dashboard.messagebird.com/developers/settings. This is NOT your API key.

You can use the ValidateRequest method, just pass the request and base url as parameters:

    validator := signature_jwt.NewValidator([]byte("your signing key"))
	baseUrl := "https://yourdomain.com"
    if err := validator.ValidateRequest(r, baseUrl); err != nil {
        // handle error
    }

Or use the handler as a middleware for your server:

http.Handle("/path", validator.Validate(YourHandler, baseUrl))

It will reject the requests that contain invalid signatures.

For more information, see https://developers.messagebird.com/docs/verify-http-requests

Index

• Variables
• type Claims
  • func (c Claims) Valid() error
• type Validator
  • func NewValidator(signingKey string, opts ...ValidatorOption) *Validator
  • func (v *Validator) Validate(h http.Handler, baseURL string) http.Handler
  • func (v *Validator) ValidateRequest(r *http.Request, baseURL string) error
  • func (v *Validator) ValidateSignature(signature, url string, payload []byte) (jwt.Claims, error)
• type ValidatorOption
  • func SkipURLValidation() ValidatorOption

Variables

var TimeFunc = time.Now

TimeFunc provides the current time same as time.Now but can be overridden for testing.

Types

type Claims

type Claims struct {
	Issuer         string `json:"iss"`
	NotBefore      int64  `json:"nbf"`
	ExpirationTime int64  `json:"exp"`
	JWTID          string `json:"jti"`
	URLHash        string `json:"url_hash"`
	PayloadHash    string `json:"payload_hash,omitempty"`
	// contains filtered or unexported fields
}

Claims replaces jwt.StandardClaims as it checks all aspects of the the JWT token that have been specified by the MessageBird RFC.

func (Claims) Valid

func (c Claims) Valid() error

Valid is called by jwt-go after the Claims struct has been filled. If an error is returned, it means that the JWT should not be trusted.

type Validator

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

Validator type represents a MessageBird signature validator.

func NewValidator

func NewValidator(signingKey string, opts ...ValidatorOption) *Validator

NewValidator returns a signature validator object. Signing key can be retrieved from https://dashboard.messagebird.com/developers/settings. Note that this is NOT your API key.

func (*Validator) Validate

func (v *Validator) Validate(h http.Handler, baseURL string) http.Handler

Validate is a handler wrapper that takes care of the signature validation of incoming requests and rejects them if invalid or pass them on to your handler otherwise.

func (*Validator) ValidateRequest

func (v *Validator) ValidateRequest(r *http.Request, baseURL string) error

ValidateRequest is a method that takes care of the signature validation of incoming requests.

func (*Validator) ValidateSignature

func (v *Validator) ValidateSignature(signature, url string, payload []byte) (jwt.Claims, error)

ValidateSignature returns the signature token claims when the signature is validated successfully. Otherwise, an error is returned. The provided url is the raw url including the protocol, hostname and query string, e.g. https://example.com/?example=42.

type ValidatorOption

type ValidatorOption func(*Validator)

func SkipURLValidation

func SkipURLValidation() ValidatorOption

SkipURLValidation instructs Validator to not validate url_hash claim. It is recommended to not skip URL validation to ensure high security. but the ability to skip URL validation is necessary in some cases, e.g. your service is behind proxy or when you want to validate it yourself. Note that if enabled, no query parameters should be trusted.