• Airlock Secure Access Hub
  • About this document
  • About Airlock IAM
  • IAM 8.3 release notes
  • Security best practices
  • Installation and upgrade
  • Operation
  • Initial configuration
  • Configuration management
  • Authentication
  • Self-services
  • Target applications
  • OAuth and OIDC
  • SAML
  • API access control
  • Flows (Airlock IAM concept)
  • Loginapp Configuration
    • Loginapp REST API
      • Service overview
      • Authentication REST API
      • User self-registration REST API
      • Public self-services
        • Password reset
          • Simple password reset
          • Complex password reset
          • Email link password reset
          • Reset locked users
          • Secret questions
        • Self-unlock
        • Failed factor attempts
        • User enumeration protection
        • Flow Continuation Step
        • Initialize next authentication flow
        • CAPTCHAs
      • Protected self-services
      • SAML IDP setup
      • SAML SP setup
      • Cleanup on user lock
      • Customizing non-UI text elements
      • Additional attributes
      • JWKS endpoint
    • Loginapp UI
    • One-Shot authentication
    • OAuth / OIDC
    • HTTP Basic Auth access
    • Event notification
  • Adminapp Configuration
  • Service Container Configuration
  • Transaction Approval Configuration
  • IAM REST APIs
  • Customizing UIs and texts
  • Third-party licenses
  1. Loginapp Configuration
  2. Loginapp REST API
  3. Public self-services
  4. Password reset
  5. Email link password reset

Email link password reset flow example (using flow continuation)

Requirements

Component

Requirement

Comments

Airlock IAM

  • Airlock IAM 7.7 or newer.

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.
 
Info

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.
 
Notice

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:

  1. Go to:
    Loginapp >> Public Self-Services
  2. 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:

  1. Go to:
    Loginapp >> Public Self-Services
  2. 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:

  1. Go to:
    Loginapp >> Public Self-Services >> Flows >> <flow with ID password-reset-continue> >> Steps
  2. In section Basic Settings of the Flow Continuation Step, disable the Immediate Token Consumption option.
  3. 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.
  4. (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.
  5. (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.
  6. Add the Flow Continuation Token Consumption Step right after the additional verification step (here the Scriptable Step), to ensure the flow will continue.
  7. 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.

Further information and links

  • Using the Flow Continuation Step in public self-service flows
  • Simple password reset flow example
  • Complex password reset flow example
  • User enumeration protection in the public self-service flows
  • Loginapp REST API Reference
  • General information about Airlock IAM flows