Valves

A VALVE is a highly specialised building block. In general, it operates on data exposed by the PIPE where the VALVE “lives”. By chaining multiple VALVES one can achieve customised authentication/authorization making the system follow current business requirements but also cater for future requirements changes.

Common configuration

These configuration properties applies to all valves:

Properties

Name	Description	Default	Mandatory
name	Valve name (alias or fully qualified class name).
enabled	Flag to control if valve is enabled (i.e. included in pipe) or not. Use this property to temporary disable a valve.	true
exec_if_expr	Predicate expression controlling if valve should be executed or not in the current context. For details, see execution control.	true
config	Valve specific configuration object. This object is passed to the valve during initialisation and is the configuration the valve has access to.	{}

Example

{
    "name":"<alias>",
    "enabled": true,
    "exec_if_expr": "request.exec === 'true'",
    "config": {

    }
}

Execution control

You can control valve execution in runtime using the exec-if predicate expression (a boolean expression that returns true or false). If expression evaluated to true, the valve is executed (this is the default behaviour).

The actual filter is an ECMA-script (JavaScript) that MUST evaluate to true, false or to a boolean function returning true or false.

// Disable valve 
"exec_if_expr": "false"

// Only execute if session contains a username property
"exec_if_expr": "session.username != null"

During expression evaluation data is made available in scopes. A scope is a map (i.e key-values or hash) where values are accessed using a name and plain dot notation.

In JavaScript dot notation is NOT supported for list/array indexing.

Use the following syntax to address an element in a list:

state.items[0].id

It is also possible to use property expansion in expressions to expand the value before the script is evaluated:

${state.items.0.id}

// Get value of request parameter "username"
request.username

// Get id of current session
session.id

// Get first value of multivalue "roles" stored in session
session.roles[0]

// Get value "otp" from state set by previous valve
state.otp

The following are scopes available:

Name	Description	Case-insensitive
request	The current pipe request
session	The current session
state	The current state
items	The current items
exports	Authenticator globals. Only available if pipe is called in an authentication context (i.e. by an authenticator).