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.