Authentication Actions present a tool for orchestrating what happens after authentication but before the session is committed. In other words. the user has authenticated, but the system hasn’t yet produced an authenticated session, which later can be used for Single Sign-On etc.
Any authenticator can be configured with any number of actions to run after login, or after sso. They are executed in the configured order so they can be chained and depend on each other.
Actions can do the following tasks:
These are just a subset of the general tasks, action plugins can be built to perform advanced orchestration using the above building blocks.
Fig. 95 Authentication Action Overview
There are two swim lanes of actions to configure.
Login actions fire when a new authentication with the current authenticator takes place. The end-result of all actions will be persisted in the Authenticated Session (i.e., an SSO session).
SSO actions fire when there is an existing, valid session for the current authenticator and Single Sign-On will occur. The end-result of the SSO action will not be persisted in the authenticated (SSO) session, but will be returned in the attributes to the client.
Tip
Typically there is no need to have the same actions in both the Login and the SSO swim lanes.
An action plugin is split into two component: the Authentication Action and the optional action completion.
Whenever the action fires it can return one of four states:
The action returns the attribute it has worked on, and those are passed to the next action. Depending on type of action, the attributes may be unchanged. If no more action are configured, the authentication service continues the authentication flow with more authenticators or returns success to the client.
The action decided to deny the user’s access. It is up to the action to decide how this decision is made. Examples are to look for an attribute that must exist, user must belong to a certain group, account is not active, etc.
When an action returns failure the authentication process stops and the user is redirected back to the client or service provider with an error code of access denined.
The action decided to restart the whole action pipeline. All of the actions in the pipeline that was restarted will run again. The restart may cause running the last authenticator again (this is configurable). It’s important to note that some side effects that actions (that had already run) created cannot be undone (e.g. sent email or completed a second factor flow…).
An action may decide that it requires more user action before it can grant access. There are four groups of Completions that may occur.
The action decided that the user needs to authenticate using another factor. It is up to the authenticator to decide why, but it could be that the user has opted into a second factor or for other reasons. When the action requests this completion, the user is prompted with another authentication and once completed the action will resume.
Each action may implement it’s own set of screens that it needs the user to go through. These may be anything from a password update flow to approve terms and conditions to something else entirely. The user will be promted with these and, once completed, the action will resume and can decide if the user has fulfilled the requirement.
In some cases the action will require the user to be redirected elsewhere. It could be that the user needs to follow a sign-up flow on another website or needs to visit her profile to update her address, etc. When that is done, the other site will redirect back, and the action is resumed.
Note
When configuring an action that will redirect off-site, remember to whitelist the redirect URL in the authentication profile configuration.
The action may require the user to register, usually with another factor or additional devices based on the authenticator logic. When the action requests this completion, the user is redirected to the registration page of the configured authenticator and after successful registration the action will resume. Optionally, the action implementation could decide whether to redirect to a different registration endpoint or to ignore any prerequisite for the registration.
Authentication actions process two types of attributes: AuthenticationAttributes and AuthenticationActionAttributes.
AuthenticationAttributes
AuthenticationActionAttributes
AuthenticationAttributes represent the outcome of the authentication process. Initially, they are set with the authenticator result (login swim lane) or the SSO session (SSO swim lane). Then, each action in the swim lane can use and change them, via the returned action result. Finally, the value returned by the last action is used as the result of the overall authentication transaction.
AuthenticationActionAttributes represent an internal set of attributes, used exclusively for communication between actions on the same swim lane. Initially, they start empty. Then, each action in the swim lane can also read and change them, via the returned action result. Finally, the value of these attributes is discarded at the end of the swim lane and not used on the overall authentication result. Also, if an action in the swim lane starts a nested authentication (e.g. a multi-factor authentication action), then the current action attributes will also not be visible in the swim lane of the nested authentication.
Authentication actions receive both AuthenticationAttributes and AuthenticationActionAttributes attribute types via the context argument. They can also change the current value for these attributes via the returned action results, namely sucess and pending completion results. If an action does not explicitly define the AuthenticationActionAttributes on the action result, then the current value will be preserved and used on the next step.
For security reasons, the Curity Identity Server only allows the usage of action prompt pages that belong to the currently active action. Any access to a page belonging to an action that isn’t the current one will result in an error. Unfortunately, this situation can sometimes occur when using the browser’s back-button in the middle of an authentication flow. To recover from these situations, the error page has controls that allow the user to restart the authentication or resume it from the currently valid action. This error page can be customized via the fragments/recover-from-invalid-action.vm template.
fragments/recover-from-invalid-action.vm
By default the error is only shown when the invalid page makes a request to the Curity Identity Server. However, it is also possible to preemptively detect a navigation to an invalid page and immediately present a dialog with some recovery options. The $enableDetectInvalidAuthnActionPage template setting can be used to enable this feature and the fragments/invalid-authn-action-dialog.vm template can be used to customize the user interface.
$enableDetectInvalidAuthnActionPage
fragments/invalid-authn-action-dialog.vm
The Front-End Development chapter contains information about the templating system, including on how to change settings and override templates.