Authentication Actions Concepts

Authentication is a workflow, where one or more authenticators are used to prove the user's identity. When each of these completes, actions can be run, to customize behavior based on attributes of the user or other runtime data. This enables you to perform tasks such as setting an authenticator dynamically, or linking accounts in order to identify users consistently to your APIs.

Built-in Actions

Actions are part of the authentication profile. The Curity Identity Server provides a number of built-in actions, and the easiest way to manage them is via the Admin UI. All available actions are listed under Actions in the menu of the authentication profile.

These built-in behaviors can be used to customize authentication, and satisfy the majority of use cases, without writing any code. One or more instances of each action can be created, and configured with settings if applicable. When required, it is also possible to implement custom actions as plugins.

Actions can then be applied to authenticators, during login, single sign-on (SSO) or registration. In the following screenshot, a number of actions operate after the user has provided a valid username and password to the HTML form authenticator:

Multiple instances of both authenticators and actions can be created, so that different behaviors can be applied to different client applications when required.

Action Attributes

Actions operate on attributes, which can be stored in one of three locations: 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, as in the following screenshot.

Action attributes 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 attributes might be stored permanently in a data source. Once authentication is complete, subject and context attributes are recorded in the resulting delegation.

Operating on Attributes

Sometimes you need to apply non-trivial logic, in which case a script action can be used, to quickly manipulate attributes via simple Javascript logic. Each script can modify subject, action or context attributes, depending upon which location is configured, and can read attributes from all three locations.

Consider the following example, for a script action configured to uses action attributes. The log statement reads a context attribute, and a new action attribute is set. The updated action attributes are then returned from the script, so that the new value can be used by subsequent actions:

function result(transformationContext) {
  'use strict';

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

  logger.info("acr is " + contextAttributes.acr);

  actionAttributes.subject_info = "Original subject is " + subjectAttributes.subject;
  return actionAttributes;
}

Custom User Account Attributes

You can collect additional data at the time of registration or authentication, then save it against the user account data. The following action types are useful for this type of use case, and can involve the user if required. The authentication actions example provides an end-to-end flow that uses these actions:

• Data Source
• Attribute Prompt
• Update Account

Account Linking

One of the main use cases for actions is to provide choices to users over which primary authentication factor to use, and to manage migrations safely. It is usually essential that doing so does not create a duplicate user account in the identity data, or identify users differently to your APIs.

The main design considerations are explained in the account linking recipes article. See also the Account Linking With Social Identity Providers tutorial, which explains how to use the following actions to link a new foreign accout to an existing local account:

• Resolve Linked Account
• Auto Link Account

Designing Flows

Authentication workflows for applications may need to contain a number of branches. An application might have some users who authenticate via passwords and others who use secure devices to perform passwordless logins. Registration may also need to take alternative paths for different user types. Start by whiteboarding the desired behavior, to produce one or more flow charts:

For more complex flows, it is common to use switch and sequence actions, among others, to represent the flow chart's logic. See the Migrating to Passkeys tutorial for an example of an advanced workflow that supports multiple types of users.

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 actions enable custom behaviors to be applied to authentication workflows, without writing code. The separation of responsibilities into small composable units also enables you to scale the logic to more complex scenarios. All of this gives you complete control, so that you can implement use cases correctly.