request signature allows skipping url_hash claim validation

Author: khanh.nguyen

signature_jwt/claims.go

@@ -23,6 +23,7 @@ type Claims struct {
 	receivedTime       time.Time
 	correctPayloadHash string
 	correctURLHash     string
+	skipURLValidation  bool
 
 	Issuer         string `json:"iss"`
 	NotBefore      int64  `json:"nbf"`
@@ -53,7 +54,7 @@ func (c Claims) Valid() error {
 		errs = append(errs, "claim jti is empty or missing")
 	}
 
-	if c.correctURLHash != "" && c.correctURLHash != c.URLHash {
+	if !c.skipURLValidation && c.correctURLHash != c.URLHash {
 		errs = append(errs, "claim url_hash is invalid")
 	}
 

signature_jwt/signature.go

@@ -2,7 +2,7 @@
 Package signature_jwt implements signature verification for MessageBird webhooks.
 
 To use define a new validator using your MessageBird Signing key. Can be
-retrieved through https://dashboard.messagebird.com/developers/settings.
+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:
@@ -18,6 +18,8 @@ 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
 */
 package signature_jwt
 
@@ -53,26 +55,53 @@ var allowedMethods = []string{
 type Validator struct {
 	parser jwt.Parser
 	keyFn  jwt.Keyfunc
+
+	skipURLValidation bool
+}
+
+type ValidatorOption func(*Validator)
+
+// 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.
+func SkipURLValidation() ValidatorOption {
+	return func(c *Validator) {
+		c.skipURLValidation = true
+	}
 }
 
 // NewValidator returns a signature validator object.
-func NewValidator(signingKey string) *Validator {
-	return &Validator{
+// Signing key can be retrieved from
+// https://dashboard.messagebird.com/developers/settings.
+// Note that this is NOT your API key.
+func NewValidator(signingKey string, opts ...ValidatorOption) *Validator {
+	validator := &Validator{
 		parser: jwt.Parser{
 			ValidMethods: allowedMethods,
 		},
 		keyFn: func(*jwt.Token) (interface{}, error) { return []byte(signingKey), nil },
 	}
+
+	for _, opt := range opts {
+		opt(validator)
+	}
+
+	return validator
 }
 
-// ValidateSignature is a method that takes care of the signature validation of
-// incoming requests.
-func (v *Validator) ValidateSignature(signature, url string, payload []byte) (*jwt.Token, 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.
+func (v *Validator) ValidateSignature(signature, url string, payload []byte) (jwt.Claims, error) {
 	claims := Claims{
-		receivedTime: TimeFunc(),
+		receivedTime:      TimeFunc(),
+		skipURLValidation: v.skipURLValidation,
 	}
 
-	if url != "" {
+	if !v.skipURLValidation && url != "" {
 		claims.correctURLHash = sha256Hash([]byte(url))
 	}
 	if payload != nil && len(payload) != 0 {
@@ -82,7 +111,7 @@ func (v *Validator) ValidateSignature(signature, url string, payload []byte) (*j
 	if token, err := v.parser.ParseWithClaims(signature, &claims, v.keyFn); err != nil {
 		return nil, fmt.Errorf("invalid jwt: %w", err)
 	} else {
-		return token, nil
+		return token.Claims, nil
 	}
 }
 
@@ -95,7 +124,7 @@ func (v *Validator) ValidateRequest(r *http.Request, baseURL string) error {
 	}
 
 	var fullURL string
-	if baseURL != "" {
+	if !v.skipURLValidation && baseURL != "" {
 		base, err := url.Parse(baseURL)
 		if err != nil {
 			return fmt.Errorf("error parsing base url: %v", err)

signature_jwt/signature_test.go

@@ -110,9 +110,10 @@ func TestValidSignature(t *testing.T) {
 			}
 
 			v := NewValidator(tc.Secret)
-			_, err := v.ValidateSignature(tc.Token, tc.Url, []byte(tc.Payload))
+			claims, err := v.ValidateSignature(tc.Token, tc.Url, []byte(tc.Payload))
 			if tc.Valid {
 				assert.NoError(t, err)
+				assert.NotEmpty(t, claims)
 				return
 			}
 			assert.EqualError(t, err, tc.Reason)