Merge pull request #58 from agilezebra/57-refactor-validation

Added AND and OR logic

Author: agilezebra

README.md

@@ -19,15 +19,15 @@ experimental:
   plugins:
     jwt:
       moduleName: github.com/agilezebra/jwt-middleware
-      version: v1.3.0
+      version: v1.3.1
 ```
 1b. or with command-line options:
 
 ```yaml
 command:
   ...
   - "--experimental.plugins.jwt.modulename=github.com/agilezebra/jwt-middleware"
-  - "--experimental.plugins.jwt.version=v1.3.0"
+  - "--experimental.plugins.jwt.version=v1.3.1"
 ```
 
 2) Configure and activate the plugin as a middleware in your dynamic traefik config:
@@ -85,7 +85,7 @@ Name | Description
 `skipPrefetch` | Don't prefetch keys from `issuers`. This is useful if all the expected secrets are provided in `secrets`, especially in situations where traefik or its services are frequently restarted, to save from hitting the issuer JWKS endpoint unnecessarily.
 `delayPrefetch` | Delay prefetching keys from `issuers` by the given duration (expressed in `time.ParseDuration` format - e.g. "300ms", "5s"). This is particularly useful if your openid server is behind the very traefik service that is loading the plugin and you need to give it time to be ready for your request. This has no effect if `skipPrefetch` is set.
 `refreshKeysInterval` | Arbitrarily refresh all keys from all `issuers` in a background thread every given duration (after any prefetch).
-`require` | A map of zero or more claims that must all be present and match against one or more values. If no claims are specified in `require`, all tokens that are validly signed by the trusted issuers or secrets will pass. If more than one claim is specified, each is required (i.e. an AND relationship exists for all the specified claims). For each claim, multiple values may be specified and the claim will be valid if any matches (i.e. an OR relationship exists for required values within a claim). fnmatch-style wildcards are optionally supported for claims in issued JWTs. If you do not wish to support wildcard claims, simply do not put such wildcards into the JWTs that you issue. See below for examples and the variables available with template interpolation.
+`require` | A map of zero or more claims that must all be present and match against one or more values. If no claims are specified in `require`, all tokens that are validly signed by the trusted issuers or secrets will pass. If more than one claim is specified, each is required (i.e. an AND relationship exists for all the specified claims). For each claim, multiple values may be specified and the claim will be valid if any matches (i.e. a default OR relationship exists for required values within a claim). It is possible to specify alternate logic using `$and` and `$or` operators (see Claim Matching examples below). fnmatch-style wildcards are optionally supported for claims in issued JWTs. If you do not wish to support wildcard claims, simply do not put such wildcards into the JWTs that you issue. See below for examples and the variables available with template interpolation.
 `headerMap` | A map in the form of header -> claim. Headers will be added (or overwritten) to the forwarded HTTP request from the claim values in the token. If the claim is not present, no action for that value is taken (and any existing header will remain unchanged).
 `removeMissingHeaders` | When set to `true`, remove any headers provided in the request that are named in the `headerMap` but are not present in the token as claims. This may be an important security consideration for some uses of headers if your JWT provider cannot be relied upon to provide an expected claim in all situations. Default: `false`.
 `cookieName` | Name of the cookie to retrieve the token from if present. Default: `Authorization`. If token retrieval from cookies must be disabled for some reason, set to an empty string.  If `forwardAuth` is `false`, the cookie will be removed before forwarding to the backend.
@@ -162,6 +162,7 @@ require:
   "iss": "auth.example.com",
   "aud": "*.example.com"
 }
+
 ```
 Note that the wildcard claim is granted to the _user_ in their JWT, not asked for in the requirements. I.e. you are granting a key that can open multiple locks rather than creating a lock that accepts multiple keys. If you don't want to support these optional wildcards, simply do not issue such JWTs.
 
@@ -182,6 +183,43 @@ require:
 }
 ```
 
+#### And logic
+```yaml
+require:
+  role:
+    $and: ["hr", "power"] # both are required
+```
+Note that, similar to MongoDB, the `$and` and `$or` operators are a single-value object with operator as the key and the choices as an array value
+
+```json
+{
+  "role": ["hr", "power"],
+}
+```
+
+
+#### Complex nested logic
+```yaml
+require:
+  role:
+    $or:
+      - $and: ["hr", "power"] # both are required
+      - "admin" # this alone will pass
+```
+Note that mixing yaml array styles here is arbitrary and both are used to enhance clarity of the structure
+
+```json
+{
+  "role": ["hr", "power"],
+}
+```
+
+```json
+{
+  "role": ["admin"],
+}
+```
+
 ### Examples
 
 #### Interactive webserver with redirection to login and error pages

jwt.go

@@ -13,7 +13,6 @@ import (
 	"net/http"
 	"net/url"
 	"os"
-	"reflect"
 	"strings"
 	"sync"
 	"time"
@@ -56,7 +55,7 @@ type JWTPlugin struct {
 	issuers              []string                  // A list of valid issuers that we trust to fetch keys from
 	clients              map[string]*http.Client   // A map of clients for specific issuers that skip certificate verification
 	defaultClient        *http.Client              // A default client for fetching keys with certificate verification, optionally with custom root CAs
-	require              map[string][]Requirement  // A map of requirements for each claim
+	require              Requirement               // A map of requirements for each claim (which we treat simply as a Requirement to be validated)
 	lock                 sync.RWMutex              // Read-write lock for the keys and issuerKeys maps
 	keys                 map[string]any            // A map of key IDs to public keys or shared HMAC secrets
 	issuerKeys           map[string]map[string]any // A map of issuer URLs to key IDs to public keys, for reference counting / purging
@@ -77,23 +76,6 @@ type JWTPlugin struct {
 // This has become a map rather than a struct now because we add the environment variables to it.
 type TemplateVariables map[string]string
 
-// Requirement is a requirement for a claim.
-type Requirement interface {
-	Validate(value any, variables *TemplateVariables) bool
-}
-
-// ValueRequirement is a requirement for a claim that is a known value.
-type ValueRequirement struct {
-	value  any
-	nested any
-}
-
-// TemplateRequirement is a dynamic requirement for a claim that uses a template that needs interpolating per request.
-type TemplateRequirement struct {
-	template *template.Template
-	nested   any
-}
-
 // CreateConfig creates the default plugin configuration.
 func CreateConfig() *Config {
 	return &Config{
@@ -164,14 +146,14 @@ func New(_ context.Context, next http.Handler, config *Config, name string) (htt
 		parser:               jwt.NewParser(jwt.WithValidMethods(config.ValidMethods), jwt.WithJSONNumber()),
 		secret:               key,
 		issuers:              canonicalizeDomains(config.Issuers),
-		clients:              createClients(config.InsecureSkipVerify),
-		defaultClient:        createDefaultClient(config.RootCAs, true),
-		require:              convertRequire(config.Require),
+		clients:              NewClients(config.InsecureSkipVerify),
+		defaultClient:        NewDefaultClient(config.RootCAs, true),
+		require:              NewRequirement(config.Require, "$and"),
 		keys:                 make(map[string]any),
 		issuerKeys:           make(map[string]map[string]any),
 		optional:             config.Optional,
-		redirectUnauthorized: createTemplate(config.RedirectUnauthorized),
-		redirectForbidden:    createTemplate(config.RedirectForbidden),
+		redirectUnauthorized: NewTemplate(config.RedirectUnauthorized),
+		redirectForbidden:    NewTemplate(config.RedirectForbidden),
 		cookieName:           config.CookieName,
 		headerName:           config.HeaderName,
 		parameterName:        config.ParameterName,
@@ -250,7 +232,7 @@ func (plugin *JWTPlugin) fetchRoutine(delayPrefetch time.Duration, refreshKeysIn
 
 // ServeHTTP is the middleware entry point.
 func (plugin *JWTPlugin) ServeHTTP(response http.ResponseWriter, request *http.Request) {
-	variables := plugin.createTemplateVariables(request)
+	variables := plugin.NewTemplateVariables(request)
 	status, err := plugin.validate(request, variables)
 	if err == nil {
 		// Request is valid, pass to the next handler and we're done
@@ -309,17 +291,12 @@ func (plugin *JWTPlugin) validate(request *http.Request, variables *TemplateVari
 		}
 
 		claims := token.Claims.(jwt.MapClaims)
-
-		// Validate that claims match - AND
-		for claim, requirements := range plugin.require {
-			if !plugin.validateClaim(claim, claims, requirements, variables) {
-				err := fmt.Errorf("claim is not valid: %s", claim)
-				// If the token is older than our freshness window, we allow that reauthorization might fix it
-				if plugin.allowRefresh(claims) {
-					return http.StatusUnauthorized, err
-				} else {
-					return http.StatusForbidden, err
-				}
+		err = plugin.require.Validate(map[string]any(claims), variables)
+		if err != nil {
+			if plugin.allowRefresh(claims) {
+				return http.StatusUnauthorized, err
+			} else {
+				return http.StatusForbidden, err
 			}
 		}
 
@@ -365,146 +342,6 @@ func (plugin *JWTPlugin) mapClaimsToHeaders(claims jwt.MapClaims, request *http.
 	}
 }
 
-// Validate checks value against the requirement, calling ourself recursively for object and array values.
-// variables is required in the interface and passed on recusrively but ultimately ignored by ValueRequirement
-// having been already interpolated by TemplateRequirement
-func (requirement ValueRequirement) Validate(value any, variables *TemplateVariables) bool {
-	switch value := value.(type) {
-	case []any:
-		for _, value := range value {
-			if requirement.Validate(value, variables) {
-				return true
-			}
-		}
-	case map[string]any:
-		for value, nested := range value {
-			if requirement.Validate(value, variables) && requirement.ValidateNested(nested) {
-				return true
-			}
-		}
-	case string:
-		required, ok := requirement.value.(string)
-		if !ok {
-			return false
-		}
-		return fnmatch.Match(value, required, 0) || value == fmt.Sprintf("*.%s", required)
-
-	case json.Number:
-		switch requirement.value.(type) {
-		case int:
-			converted, err := value.Int64()
-			return err == nil && converted == int64(requirement.value.(int))
-		case float64:
-			converted, err := value.Float64()
-			return err == nil && converted == requirement.value.(float64)
-		default:
-			log.Printf("unsupported requirement type for json.Number comparison: %T %v", requirement.value, requirement.value)
-			return false
-		}
-	}
-
-	return reflect.DeepEqual(value, requirement.value)
-}
-
-// ValidateNested checks value against the nested requirement
-func (requirement ValueRequirement) ValidateNested(value any) bool {
-	// The nested requirement may be a single required value, or an OR choice of acceptable values. Convert to a slice of values.
-	var required []any
-	switch nested := requirement.nested.(type) {
-	case nil:
-		// If the nested requirement is nil, we don't care about the nested claims that brought us here and the value is always valid.
-		return true
-	case []any:
-		required = nested
-	case any:
-		required = []any{nested}
-	}
-
-	// Likewise, the value may be a single claim value or an array of several granted claims values. Convert to a slice of values.
-	var supplied []any
-	switch value := value.(type) {
-	case []any:
-		supplied = value
-	case any:
-		supplied = []any{value}
-	}
-
-	// If any of the values match any of the nested requirement, the claim is valid.
-	for _, required := range required {
-		for _, supplied := range supplied {
-			if reflect.DeepEqual(required, supplied) {
-				return true
-			}
-		}
-	}
-	return false
-}
-
-// Validate interpolates the requirement template with the given variables and then delegates to ValueRequirement.
-func (requirement TemplateRequirement) Validate(value any, variables *TemplateVariables) bool {
-	var buffer bytes.Buffer
-	err := requirement.template.Execute(&buffer, variables)
-	if err != nil {
-		log.Printf("Error executing template: %s", err)
-		return false
-	}
-	return ValueRequirement{value: buffer.String(), nested: requirement.nested}.Validate(value, variables)
-}
-
-// convertRequire converts the require configuration to a map of requirements.
-func convertRequire(require map[string]any) map[string][]Requirement {
-	converted := make(map[string][]Requirement, len(require))
-	for key, value := range require {
-		switch value := value.(type) {
-		case []any:
-			requirements := make([]Requirement, len(value))
-			for index, value := range value {
-				requirements[index] = createRequirement(value, nil)
-			}
-			converted[key] = requirements
-		case map[string]any:
-			requirements := make([]Requirement, len(value))
-			index := 0
-			for key, value := range value {
-				requirements[index] = createRequirement(key, value)
-				index++
-			}
-			converted[key] = requirements
-		default:
-			converted[key] = []Requirement{createRequirement(value, nil)}
-		}
-
-	}
-	return converted
-}
-
-// createRequirement creates a Requirement of the correct type from the given value (and any nested value).
-func createRequirement(value any, nested any) Requirement {
-	switch value := value.(type) {
-	case string:
-		if strings.Contains(value, "{{") && strings.Contains(value, "}}") {
-			return TemplateRequirement{
-				template: template.Must(template.New("template").Option("missingkey=error").Parse(value)),
-				nested:   nested,
-			}
-		}
-	}
-	return ValueRequirement{value: value, nested: nested}
-}
-
-// validateClaim valideates a single claim against the requirement(s) for that claim (any match with satisfy - OR).
-func (plugin *JWTPlugin) validateClaim(claim string, claims jwt.MapClaims, requirements []Requirement, variables *TemplateVariables) bool {
-	value, ok := claims[claim]
-	if ok {
-		for _, requirement := range requirements {
-			if requirement.Validate(value, variables) {
-				return true
-			}
-		}
-	}
-	return false
-}
-
 // getKey gets the key for the given key ID from the plugin's key cache.
 // If the key isn't present and the iss is valid according to the plugin's configuration, all keys for the iss are refreshed and the key is looked up again.
 func (plugin *JWTPlugin) getKey(token *jwt.Token) (any, error) {
@@ -685,8 +522,8 @@ func pemContent(value string) (string, error) {
 	return string(content), nil
 }
 
-// createDefaultClient returns an http.Client with the given root CAs, or a default client if no root CAs are provided.
-func createDefaultClient(pems []string, useSystemCertPool bool) *http.Client {
+// NewDefaultClient returns an http.Client with the given root CAs, or a default client if no root CAs are provided.
+func NewDefaultClient(pems []string, useSystemCertPool bool) *http.Client {
 	if pems == nil {
 		return &http.Client{}
 	}
@@ -708,8 +545,8 @@ func createDefaultClient(pems []string, useSystemCertPool bool) *http.Client {
 	return &http.Client{Transport: transport}
 }
 
-// createClients reads a list of domains in the InsecureSkipVerify configuration and creates a map of domains to http.Client with InsecureSkipVerify set.
-func createClients(insecureSkipVerify []string) map[string]*http.Client {
+// NewClients reads a list of domains in the InsecureSkipVerify configuration and creates a map of domains to http.Client with InsecureSkipVerify set.
+func NewClients(insecureSkipVerify []string) map[string]*http.Client {
 	// Create a single client with InsecureSkipVerify set
 	transport := &http.Transport{
 		TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
@@ -724,8 +561,8 @@ func createClients(insecureSkipVerify []string) map[string]*http.Client {
 	return clients
 }
 
-// createTemplate creates a template from the given string, or nil if not specified.
-func createTemplate(text string) *template.Template {
+// NewTemplate creates a template from the given string, or nil if not specified.
+func NewTemplate(text string) *template.Template {
 	if text == "" {
 		return nil
 	}
@@ -736,11 +573,11 @@ func createTemplate(text string) *template.Template {
 	return template.Must(template.New("template").Funcs(functions).Option("missingkey=error").Parse(text))
 }
 
-// createTemplateVariables creates a template data map for the given request.
+// NewTemplateVariables creates a template data map for the given request.
 // We start with a clone of our environment variables and add the the per-request variables.
 // The purpose of environment variables is to allow a easier way to set a configurable but then fixed value for a claim
 // requirement in the configuration file (as rewriting the configuration file is harder than setting environment variables).
-func (plugin *JWTPlugin) createTemplateVariables(request *http.Request) *TemplateVariables {
+func (plugin *JWTPlugin) NewTemplateVariables(request *http.Request) *TemplateVariables {
 	// copy the environment variables
 	variables := make(TemplateVariables, len(plugin.environment)+6)
 	for key, value := range plugin.environment {