Switch Action¶

The Switch action allows the conditional execution of inner actions, based on conditions over the input authentication attributes.

A Switch action is configured with a list of switch cases, where each case is composed by:

A JavaScript boolean expression over the input authentication and client attributes.
The identifier for the action to execute if the previous expression evaluates to true.

When the Switch Action is executed, it sequentially evaluates the conditions for each case and calls the action of the first case that evaluates to true. At most one inner action is called, even if there are more than one case with an expression evaluating to true.

A Switch Action instance can be interpreted as a sequence of one if(condition(attributes)) {action(attributes)} followed by zero or more else if(condition(attributes)){action(attributes)}.

If no case expression evaluates to true, then one of two things happens:

if the fail-if-no-match configuration flag is true (the default value), then the Switch action ends with a failure result, and the login or SSO does not succeed.
if the fail-if-no-match configuration flag is false, then the Switch action ends successfully, returning the input authentication attributes.

Each switch case can reference any other action, including another Switch action. The only limitation is that a Switch action can not reference itself, directly or indirectly, since that could result in an endless loop. Only direct self-references are checked during configuration, however indirect references are checked during execution.

If a case needs to have more than one action, then a Sequence Action can be used to wrap multiple actions into a single one.

Conditions¶

A Switch Action case condition is a JavaScript boolean expression, where the attributes identifier refers to a map containing the following fields:

subject - Subject Attributes in the action’s input Authentication Attributes.
context - Context Attributes in the action’s input Authentication Attributes.
client - Client Attributes from the requesting client.
action - action’s input Action Attributes.

The following table presents some examples for these conditions.

Condition	Description
`true`	Always `true`.
`attributes.subject.username === 'Alice'`	`true` if `username` subject attribute is Alice
`attributes.context.location.country === 'Sweden'`	`true` if the `location` context attribute is an object an has the `country` set to `Sweden`.
`attributes.context.riskLevel > 2 && attributes.context.riskLevel < 5`	`true` if the `riskLevel` context attribute is a number between `2` and `5`.
`/.*@example\.com/.test(attributes.subject.email \|\| attributes.subject['e-post'])`	`true` if the `email` (or the `e-post` if absent) contextual attribute has an `example.com` domain.
`attributes.client.properties.group === 'external'`	`true` if the requesting client has a property `group` with the value of `external`.
`attributes.client.id === 'my-good-client'`	`true` if the requesting client has the `client_id` `my-good-client`.
`attributes.action.someInternalAttribute === 42`	`true` if the action attributes contain an `someInternalAttribute` attribute with the value `42`.

See Client Object for the available client properties.

Configuration¶

Configuration	Mandatory	Description
case	yes	A list with at least one switch case.
fail-if-no-match	no	If `true` (default value), then the Switch Action fails if not case condition matches the authentication attributes.

Each case list item has the following elements

Configuration	Mandatory	Description
name	yes	An unique name for this case, distinct form the other cases in the same switch.
condition-script	yes	The case condition JavaScript expression.
action	yes	The identifier for the case action.

When using the programmatic configuration interfaces, the condition-script needs to be encoded in Base64. When using the administration graphical interface, this encoding is done automatically.

As an example, the following XML excerpt

<authentication-action>
  <id>switch-1</id>
  <switch xmlns="https://curity.se/ns/ext-conf/switch">
      <case>
          <name>low-risk</name>
          <!-- "attributes.context.riskLevel < 2" -->
          <condition-script>YXR0cmlidXRlcy5jb250ZXh0LnJpc2tMZXZlbCA8IDI=</condition-script>
          <action>action-0</action>
      </case>
      <case>
          <name>high-risk</name>
          <!-- "attributes.context.riskLevel >= 2" -->
          <condition-script>YXR0cmlidXRlcy5jb250ZXh0LnJpc2tMZXZlbCA+PSAy</condition-script>
          <action>action-1</action>
      </case>
  </switch>
</authentication-action>

defines the switch-0 sequence action, which when executed:

Calls action-0 if the riskLevel contextual attribute is less than 2.
Otherwise, calls action-1 if the riskLevel contextual attribute is greater or equal than 2.
Fails the authentication if none of the previous conditions match (e.g. riskLevel is not defined), because the fail-if-no-match default is true.