Ensure Variables

The GSL filter definition for this filter is gsl.#EnsureVariablesFilter.

Configuration

#EnsureVariablesFilter

#EnsureVariablesFilter: {
  #options: #EnsureVariablesConfig
}

#options

The root of the filter configuration.

#EnsureVariablesConfig

#EnsureVariablesConfig: {
	rules?: [...#EnsureVariablesConfig_Rule]
}

rules

Array of rules to enforce on the incoming request.

#EnsureVariablesConfig_Rule

#EnsureVariablesConfig_Rule: {
	key?:                 string
	location?:            #LocationType
	metadataFilter?:      string
	enforce?:             bool
	enforceResponseCode?: int32
	removeOriginal?:      bool
	value?:               #EnsureVariablesConfig_Rule_Value
	copyTo?: [...#EnsureVariablesConfig_Rule_CopyTo]
}

key

The key name in the request to check.

location

The location of the key specified in the key field. Can be one of: “header”, “cookie”, “queryString”, or “metadata”.

metadataFilter

The name of the filter to ready dynamic metadata from. If the location is set to metadata then this field is required.

enforce

Default: false

If set to true, the filter will reject the request if the rule fails to find the key.

enforceResponseCode

Default: 403

Specifies the HTTP status code to return in the case of a rule failure.

removeOriginal

Default: false

If set to true, the filter will strip the matched key and value from the request.

value

If set, the filter will perform additional key/value pair matching based on the values set.

copyTo

If set, the filter will copy the matched key and value into each one of these specified locations.

#EnsureVariablesConfig_Rule_Value

#EnsureVariablesConfig_Rule_Value: {
	matchType:   "exact" | "prefix" | "suffix" | "regex"
	matchString: string
}

matchType

Default: exact

The type of matching performed by the filter on the key/value pair.

matchString

The string used to match the key’s value with.

#EnsureVariablesConfig_Rule_CopyTo

#EnsureVariablesConfig_Rule_CopyTo: {
	location?:      "header" | "cookie" | "queryString" | "metadata"
	key?:           string
	direction?:     "request" | "response" | "both"
	cookieOptions?: #CookieOptions
}

location

Default: header

Specifies where the filter will create the new key. Can be one of header, cookie, queryString, metadata.

key

The newly copied key name.

direction

Specifies whether the filter copies the key/value pair into the request, response, or both. Can be one of request, response, both.

cookieOptions

Specifies the cookie options if copying into a cookie.

CookieOptions

#CookieOptions: {
	httpOnly?: bool
	secure?:   bool
	domain?:   string
	path?:     string
	maxAge?:   string
}

httpOnly

Default: false

Sets the httpOnly cookie security policy.

secure

Default: false

Sets the secure cookie security policy.

domain

Specifies the hosts allowed to access the created cookie. If unspecified, it defaults to the host of the current document location, excluding subdomains. If it is specified, then subdomains are always included.

path

Specifies a URL path that must exist in the requested URL in order to send the Cookie header. The %x2F (“/”) character is considered a directory separator, and subdirectories will match as well.

maxAge

Specifies the value of the Max-Age cookie attribute. The string value must be formatted in a signed sequence of decimal numbers with an optional fraction and time unit suffix.

For example:

• "300ms"
• "-1.5h"
• "2h45m"

The supported unit suffixes are: “s”, “m”, and “h”. If this value is not set, the cookie will expire at the end of the session.

Examples

Enforcing a header

Assert that requests must have an Authorization: Bearer header, otherwise return a 401.

gsl.#EnsureVariablesFilter & {
  #options: {
    rules: [{
      key: "Authorization"
      location: "header"
      enforce: true
      enforceResponseCode: 401
      value: {
        matchType: "regex"
        matchString: "Bearer\s+(\S+).*"
      }
    }]
  }
}

Checking a header and copying it to a cookie

Check that an Authorization header exists on the request. If it does, copy the value to an httpOnly cookie and set on the request and response. If not, let the request pass through.

gsl.#EnsureVariablesFilter & {
  #options: {
    rules: [{
      key: "Authorization"
      location: "header"
      enforce: false
      value: {
        matchType: "regex"
        matchString: "Bearer\s+(\S+).*"

      }
      copyTo: [{
        location: "cookie"
        key: "access_key"
        direction: "both"
        cookieOptions: {
          httpOnly: true
        }
      }]
    }]
  }
}

Enforcing a query string

Rejects all requests that don’t have a query string with a key of username and a value prefixed with jane.

gsl.#EnsureVariablesFilter & {
  #options: {
    rules: [{
      key: "username"
      location: "queryString"
      enforce: true
      value: {
        matchType: "prefix"
        matchString: "jane"
      }
    }]
  }
}

Enforcing a cookie and then removing it

Checks for a cookie with a user_dn value that exactly matches matchString and then removes the cookie from the browser.

gsl.#EnsureVariablesFilter & {
  #options: {
    rules: [{
      key: "user_dn"
      location: "cookie"
      enforce: true
      removeOriginal: true
      value: {
        matchType: "exact"
        matchString: "C=US,ST=Virginia,L=Alexandria,O=greymatter.io,OU=Engineering,CN=*.greymatter.svc.cluster.local"
      }
    }]
  }
}

Setting multiple CopyTo locations

Checks for the existence of an id_token query string. If it exists, it is copied to a response cookie with a key of userinfoCookie. It also copies this value to a header on the request and response with a key of x-userinfo.

gsl.#EnsureVariablesFilter & {
  #options: {
    rules: [{
      key: "id_token"
      location: "queryString"
      enforce: true
      enforceStatusCode: 404
      copyTo: [
        {
          location: "cookie"
          key: "userinfoCookie"
        },
        {
          location: "cookie"
          key: "x-userinfo"
          direction: "both"
        }
      ]
    }]
  }
}