Authentication Actions are a powerful way to perform additional abilities on top of user authentication. Authentication Actions occur after credential validation but before the authentication concludes. For example, an HTML form authenticator could validate user credentials. Next, Actions could manipulate attributes related to the subject or trigger a second factor, which may be necessary if the subject is authenticating from a new country or outside office hours.
Actions can use the attributes which were fetched or manipulated by preceding Actions. In this way, you can create workflows by using multiple, simple Actions. You can also use these attributes in tokens later on. In this tutorial, we will create a simple workflow using three Actions.
You will need an installation of Curity Identity Server with the basic setup completed. You can achieve this by following our Getting Started Guides. Alternatively, if you have a system up and running with your own configuration, you can use that as well. Just be aware that you probably have different names set for certain components.
In this tutorial we will also use another authenticator, Google Authenticator, for a second factor. However, you can use any authenticator.
Say you have a user authenticating with a username and password — this is one factor. For user accounts registered with an internal email, you want to introduce a second authentication factor, Google Authenticator.
To enable this, you can set up Actions to:
- Fetch all attributes belonging to the Account
- Trigger Google Authenticator if the domain of the email is
The diagram below shows how it would be setup:
To fetch the attributes, we will use the
Data Source Action. It uses the attribute query configured for that data source, so we need to set it up. To do so, enter the Admin UI and click on Facilities->Data Sources->default-datasource. Here, set the
Attribute Query to
SELECT * FROM "accounts" WHERE "username" = :subject. NOTE: This query will fetch all attributes, but you can be more specific.
When that is done, open Actions in your authentication profile and click on the New Action button. Give the Action a name and click on the Data Source action.
Here, select the Attribute Data Source to be
default-datasource. Finish by clicking on Close.
Next, we must add a second action. This time, add a Multi-Factor Condition action. This action can filter which factor the user should authenticate with. All MFA users should use the same second factor so our filter should match everyone. Set the Condition to
subject-condition to filter based upon our subject. Next, press Add to create a new condition. The pattern is a regular expression pattern. Since we want all MFA users to use the same Authenticator we set the pattern to
.*, which matches all subjects. Then, click Select authenticator and select
Google-Authenticator. Finish by clicking on Close.
/.*@email.example\.com$/.test(attributes.subject.email) which means that we will determine if
subject attributes ends with
@email.example.com. Set Execute to our
MFA action. Set the else case to
Succeed if no conditions match to let users with other email domains in without a second factor.
Now we will assign these actions to your Authenticator. Open Authenticators and click on the username-password authenticator. To the right, we have actions. Click on the plus sign next to Login to add an action. The actions will be executed in order. First, we add the user_account to fetch the attributes, and then we add the switch. The switch action will take care of running the MFA, so we should not add that one.
You can now try out the
username-password login and see how the system behaves when a user attempts to authenticate with or without the
email.example.com domain. You will also notice that the
subject is changed to reflect the email in your issued tokens. For information on how to register new accounts, visit the
Try It Out section of the Getting Started Guides.
In this guide, we quickly looked at using Authentication Actions to achieve MFA. We used a Switch action to select which users that should use a second factor based upon their email. Feel free to explore other conditions you can use. As we have seen, it is also possible to fetch additional attributes and use them in subsequent Actions. A powerful way to manipulate attributes is by using Script Action.
The Curity Identity Server ships with about 20 pluggable Actions, and more are available on GitHub. You can also create your own Action with the Curity SDK. This guide also explains how to implement your own Authentication Action.
In this article, we focused on using Actions in the
login flow. You can use the same actions in the
sso flow as well.