Email link password reset flow example (using flow continuation)
Requirements
Component | Requirement | Comments |
|---|---|---|
Airlock IAM |
| None. |
Intended solution environment
This example shows how to configure and use the Loginapp REST API to implement a password reset flow using the flow continuation concept.
This example meets the following requirements:
- User identification is verified by using the user's email address and sending a link to the user.
- After clicking on the link, the user can set a new password.
Note that the example can easily be combined with a 2nd factor as shown in Complex password reset flow example.
Goal
- Understand how the password reset feature works in general.
- Understand how to use the flow continuation concept to build a password reset flow using the Send Email Link Step.
- Be able to configure and try out flow continuation.
All following procedures are exemplary and will vary according to your setup or needs.
Prerequisites
- The user account used in the example exists in the IAM database.
- An email address is stored in the user account.
- The Loginapp REST API is configured.
Notes on the configuration
To implement a password reset flow using the Send Email Link Step, two flows must be configured:
Flows to configure:
- Initiating flow: A flow that lets the user enter the username and sends an email with a link to the user.
- Continuation flow: A flow that verifies the Flow Continuation Token from the link, identifies the user with it and lets the user set the new password.
See Using the Flow Continuation Step in public self-service flows for more information on the flow continuation concept.
Initiating flow configuration and REST calls
The flow is configured as a public self-service flow.
Proceed as follows:
- Go to:
Loginapp >> Public Self-Services - In property Flows, create and edit a new flow with ID
password-reset-init.
The flow steps configured for this example and a high-level view of the REST calls is shown in the diagram below.
Step | Purpose | Comment |
|---|---|---|
A | Provide the name of the user for which the password reset flow should be executed. | This step is required to start the flow and to select the user. By default, this step will complete with 200 OK, even if the user cannot be found, the account is locked or invalid. This is done to provide protection against user enumeration attacks. To change this, adapt the configuration of the Default Password Reset Restrictions plugin or define your own password restriction settings using the plugin Custom Public Self-Service Restrictions |
B | Sends an email with a link to the user. | Note that the configuration of this step contains the ID of the continuation flow described below. It embeds the flow ID in the link sent to the user. This ensures that the correct continuation flow is selected when the link is clicked. The step stores information about the user in the IAM database such that the continuing flow can access it (even on a new HTTP session). |
Continuation flow configuration and usage
As the initiating flow, this flow is also configured as a public self-service flow.
Proceed as follows:
- Go to:
Loginapp >> Public Self-Services - In property Flows, create a new flow with ID
password-reset-continue.
Step | Purpose | Comment |
|---|---|---|
A | Validate the flow continuation token to identify the user for the flow. | When clicking on the link in the email (sent by the Send Email Link Step), a flow continuation token is sent in the HTTP header when selecting the flow (1). This step extracts the Flow Continuation Token and looks it up in the IAM database. With the token, it identifies the user for the rest of the flow. If this step is successful, the email address of the user has been verified. |
B | Set the new password. | This step persists the new password if it passes the password policy. |
C | Clears all open OAuth sessions. | For security reasons, all open OAuth sessions (e.g., logged-in apps) are logged out. |
D | Logs out all remembered browsers/devices. | For security reasons, all logged-in browsers/devices (remember-me feature) are logged out. |
Continuation flow configuration with manual token consumption
To demonstrate the manual token consumption option, we add an additional verification requirement the user must met before they can reset their password. Since the outcome of this verification step is uncertain, we do not want to consume the Flow Continuation Token immediately, but only after the verification step returns successfully.
The following instructions show how to add the additional verification step, how to configure the user interaction, and how to manage the Flow Continuation Token.
Proceed as follows:
- Go to:
Loginapp >> Public Self-Services >> Flows >> <flow with IDpassword-reset-continue> >> Steps - In section Basic Settings of the Flow Continuation Step, disable the Immediate Token Consumption option.
- Add the additional verification step right after the Flow Continuation Step. For example, add a Scriptable Step to check password reset eligibility with a third-party system.
- (Optionally) add an Acknowledge Message Step to inform the user about the failed verification. This step should have a skip condition if the additional verification step (here the Scriptable Step) was successful.
- (Optionally) add an Abort Step to fail the entire flow. This step should have a skip condition if the additional verification step (here the Scriptable Step) was successful.
- Add the Flow Continuation Token Consumption Step right after the additional verification step (here the Scriptable Step), to ensure the flow will continue.
- If the additional verification step was succesful, the user will be able to use the continuation URL and the flow will proceed normally. If the additional verification step failed, the user will be informed and the flow will be aborted.