Authentication Action Base Configuration#
The Authentications Actions Home Page provides an overview of the main authentication action behaviors. All authentication actions have a number of base configuration settings. In the Admin UI you can view these settings by navigating to Profiles → Authentication Service → Authentication Actions, editing the properties of an action and selecting the Advanced option.
Template Area#
Authentication actions can show screens to the users for interaction. This is done by using the built in Templating System of the Curity Identity Server. Authentication action forms can have their own look and feel, i.e. a per instance template. This is useful when different applications need the Authentication Service to look according to their brand or layout. By configuring two instances of the same type of authentication action, but with different template areas, this can be achieved.
The template area configuration is defined in the configuration reference.
Whitelist Attributes#
Each action form can be granted whitelisted access to attributes for use in templates. For example, an action form’s template can render the given_name field from an external identity provider (IDP). To do so it can use a velocity variable of $_subjectAttributes.givenName.
Request Validation#
Authentication actions that use forms can use custom JavaScript validation of request data. For example, in an Attribute Prompt Action or a Signup Action you can us JavaScript to enforce your own required fields, as well as assert that the fields conform to your own custom requirements.
More information on how to write a request validation procedure is documented in the Developer’s Scripting Guide’s section Validation Procedures .
Authentication Action Plugin Interface#
Authentication actions are implemented with a plugin interface from the Curity Identity Server’s Java SDK. The ability to write plugins means you are never blocked when you face deeper custom requirements.
If you develop a custom authentication action plugin it also has access to the base configuration settings. To understand how a plugin can use configuration settings it can be useful to browse some example plugin implementations. The Curity Website contains a number of example authentication action plugins for particular use cases. You can read the learning resources to understand the development approach:
The example plugins links to GitHub repositories whose code you can study. Browse plugin code to understand how frontend HTML is generated from velocity templates that can use template-related configuration settings.
An action plugin is split into two components: the Authentication Action and the optional action completion. Whenever the action fires it can return one of four states:
Success#
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.
Failure#
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.
Restart#
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…).
Pending Completion#
An action may decide that it requires more user action before it can grant access. There are four groups of Completions that may occur.
Require Authentication#
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.
Require Prompt#
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.
Require Redirect#
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.
When configuring an action that will redirect off-site, remember to whitelist the redirect URL in the authentication profile configuration.
Require Registration#
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.
Action Prompts and Backwards Navigation#
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.
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.
The Front-End Development chapter contains information about the templating system, including on how to change settings and override templates.