The Authentication Actions Toolbox

The Authentication Actions Toolbox

Intro

Authentication is a workflow, where one or more authenticators prove the user's identity. When each of these completes, Actions can run, to customize behavior based on attributes of the user or context, or values that have been input. This enables you to perform tasks such as prompting for custom data to further verify the user's identity, account linking to identify the user consistently to your APIs, or changing authentication behavior based on runtime conditions.

Attribute Sources

Attributes can some from three sources, or locations, named subject, context or action. When information needs to be passed between actions during Login and Single Sign On (SSO) workflows, action attributes should be used. They are created before the first action runs, passed between actions, then dropped when the last action after the last authenticator has completed. Action attributes contain only temporary values, whereas subject and context attributes are recorded in the resulting delegation.

Example Workflow

Consider an example scenario where there are regional regulations or preferences on how Multi-factor Authentication (MFA) should be applied. For an application with exising internet users, it might then be necessary to prompt the user for their region when they next sign in, then run some custom logic. This might result in a workflow similar to the following being designed, where only one of the MFA condition actions evaluates to true at runtime:

Authentication Workflow

In this example, the debug action is not a permanent part of the authentication workflow. Instead it is used temporarily during development and testing, to visualize the current state of attributes.

Using Action Attributes

For this use case, all actions use a source of action-attributes, as for the following prompt action configuration:

Prompt Action Setup

When the action runs, each user then supplies their own runtime value:

Prompt Action

The script action is also configured to use action attributes, to enable it to read the input value, then create its own output values:

New Script Action

The script applies some custom logic to calculate a second factor. This logic could be non-trivial, though the following example just sets an attribute based on a simple condition. The output value then feeds into the MFA condition actions:

function result(transformationContext) {
    'use strict';

    var actionAttributes = transformationContext.attributeMap;

    if (actionAttributes.countryCode == 'SV') {
        actionAttributes.secondFactor = 'factorA';
    } else {
        actionAttributes.secondFactor = 'factorB';
    }

    return actionAttributes;
}

Attributes can continue to feed between actions like this, until the workflow completes. Once all stages complete, the debug action of the example workflow renders the final attributes. The action attributes shown are then discarded and are not saved against the delegation:

Debug Action

The Script Action

The script action is one of the most powerful authentication actions, since it allows you to update attributes in arbitrary ways, as described in the Scripting Guide. A script procedure can modify subject, action or context attributes, depending upon which is selected for the attributes-location. All three types of attribute are available for reading though, and multiple script actions can also be chained together if required, if you need to adjust attributes from more than one location.

function result(transformationContext) {
  'use strict';

  var subjectAttributes = transformationContext.subjectAttributeMap;
  var contextAttributes = transformationContext.contextAttributeMap;
  var actionAttributes = transformationContext.actionAttributeMap;

  logger.info("acr is " + context.contextAttributeMap.acr);
  logger.info("Original subject is " + context.subjectAttributeMap.subject);

  actionAttributes.companyEmail = subjectAttributes.subject + '@example.com';
  return actionAttributes;
}

Claims From Authentication

Once authentication has completed, custom attributes from the delegation can be used during token issuing and returned to applications in tokens, as described in the Claims from Authentication tutorial. Action attributes cannot be used here, and you should instead use subject or context attributes to pass information to claims value providers.

Conclusion

Authentication is not a one-size-fits-all solution. Instead, behaviors are composed together to form a workflow. As well as proving the user's identity with one or more factors, it is common to need to manipulate data. In the Curity Identity Server this is done using actions, which enable you to inject any logic you need, to build your desired behavior.