Simple password reset flow example

Requirements

Component

Requirement

Comments

Airlock IAM

Airlock IAM 7.5 or newer.

Intended solution environment

This example shows how to configure and use the Loginapp password reset REST API for a simple password reset – flow based on sending an OTP to the end-user via email.

Goal

  • Understand how the password reset feature works in general.
  • Be able to configure and try out a simple password reset flow.

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.
  • The Loginapp REST API is configured.

Configuration and REST calls

The flow is configured as a public self-service flow:
Loginapp >> Public Self-Service Flows >> a flow implementing password reset.

The flow steps configured for this example and a high-level view of the REST calls is shown in the diagram below.

Note that there is a similar flow example in the demo configuration template.

Public-Self-Service-Password-Reset-Simple

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

Send an OTP to the end user's email address and verify OTP entered by the end user.

C

Set a new password.

This step persists the new password if it passes the password policy.

Detailed REST call sequence example

  1. The password reset flow is started by selecting the corresponding public self-service flow (the flow ID in this example is password-reset):
    2. copy
    POST /rest/public/self-service/flows/password-reset/select

    Response:

    copy
    200 OK
 
{
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-03-02T21:25:22.970+01:00"
   },
   "data":{
      "type":"public-self-service.session",
      "id":"703084279749574292",
      "attributes":{
         "nextStep":"USERNAME_REQUIRED"
      }
   }
}
  2. The first request in the selected flow identifies the user (2):
    3. copy
    POST /rest/public/self-service/username/identify/
{
    "username": "jdoe"
}
  3. A successful response indicates EMAIL_OTP_REQUIRED as the next step:
    4. copy
    HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-03-02T21:26:22.970+01:00"
    },
    "data": {
        "type": "public-self-service.session",
        "id": "703084279749574292",
        "attributes": {
            "nextStep": "EMAIL_OTP_REQUIRED"
        }
    }
}

    The email Email Identity Verification Step is automatically started and an email with an OTP token is sent to the user without waiting for user interaction.

  4. To check the OTP sent to the user, use the following request (3):
    5. copy
    POST /rest/public/self-service/verification/email/otp/check/
{
    "otp" : "12345678"
}
  5. A successful response will indicate NEW_PASSWORD_REQUIRED as the next step:
    6. copy
    HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-03-02T21:27:22.970+01:00"
    },
    "data": {
        "type": "public-self-service.session",
        "id": "703084279749574292",
        "attributes": {
            "nextStep": "NEW_PASSWORD_REQUIRED"
        }
    }
}
  6. To set the new password, use the request (4):
    7. copy
    POST /rest/public/self-service/password/set
{
    "newPassword" : "secret123!"
}
  7. If all went well, the response is like the following:
    8. copy
    HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-03-02T21:28:22.970+01:00"
    },
    "data": {
        "type": "public-self-service.session",
        "id": "703084279749574292",
        "attributes": {}
    }
}

    The following alternative response indicates that the password policy was not met:

    copy
    HTTP/1.1 400 Bad Request
 
{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2021-03-02T21:29:22.970+01:00",
        "nextStep": "NEW_PASSWORD_REQUIRED"
    },
    "errors": [
        {
            "code": "PASSWORD_POLICY_VIOLATED",
            "source": {
                "pointer": "/newPassword"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "SAME_AS_OLD"
            }
        }
    ]
}