Example configuration for protected self-service flow

The e-mail address change is used in this example since it is a typical self-service flow, where a user provides information that must be validated before it is persisted.

0. Such flows very often contain the following steps:
1. Obtain the information from the user. In this case the e-mail address.
2. Validate the information provided by the user. In this case, sending an e-mail message to the user and verifying the receipt.
3. Persist the information provided. In this case, store the new e-mail address in the user account.

After configuring the IAM flow, the corresponding UI must also be configured.

1. Create a new plugin of type Self Service Flow under:
   Loginapp >> Protected Self-Services >> Protected Self-Service Flows
2. Create a plugin for the Flow ID to create a name for this flow. This name identifies the flow and it will be used by client applications to start an instance of this flow.

In this example, the flow has the ID: email-change.

The first step is to create a User Data Edit Step plugin. It allows the user to enter context data and it can be configured which data items the user may supply.

The details of the configuration of the data edit step for the email address very much depend on the requirements and on the desired user experience.

In our example, we use the email address as an alias for the username and we require all users to use the alias so that we can use an internal identifier for the username.

To support this use case, the User Data Edit Step is configured as follows:

• Required – enabled, to enforce providing an e-mail address.
• Unique – enabled, to prevent duplicate conflicts in the alias' of different users.
• Enable Stealth Mode – enabled, to protect against e-mail enumeration.
• Maximum Input Length – the default is 100 characters.
• The validator is empty because the default validator already checks for a well-formed e-mail address. Configure a regex validator if you require additional validation.

The next step will validate the information provided by the user.

This example validates the e-mail address by sending an e-mail message to this address. The E-Mail Change Verification Step plugin will do just that.

• It requires some configuration:
• E-Mail Item - This is the same plugin as was used in the User Data Edit step. It is required here to ensure that the stealth mode configuration is honored correctly in the verification step.
• E-Mail Address Provider - To verify the e-mail address supplied by the user in the first step. Use the Changed E-Mail Address Provider.
• E-Mail Service - Provide an SMTP Emal Service Plugin to send out the verification e-mail message.
• OTP Generator - Verification requires the user to manually enter a code obtained from the e-mail message sent. Configure the generator for this code in this plugin.
• E-Mail Message Provider - configures the e-mail message to be sent to the user. Subject and Body used here are the default values for the E-Mail Address Change flow. In the value providers, the Context Data Map should be configured to address the user with his name and the Value Provider Map is used to inject the correct value for new_email into the message.

The last step of the flow is the persistence of the newly provided and successfully validated e-mail address.

• This works as follows:
• Create a new step with an Apply Changes Step.
• In this step choose the Apply E-Mail Change as the handler.
• In the plugin select the 'email' entry for the Context Data Name.

Once the flow has been created it can be used by clients through the REST interface. To enable the flow in the Loginapp, the UI Settings must be adapted as well.

Create a new Protected Self-Service UI plugin in the Loginapp >> UI Settings >> Protected Self-Service UIs.

• When you configure this plugin, you have the following options:
• Select the flow ID for which the UI should be generated.
• Provide customized UIs for particular steps (optional)
• Decide if Cancel or Goto buttons should be visible to the user
• Configure a maintenance message UI (if required)

• Also in the UI configuration, you may choose where the UI will redirect the user:
• on successful completion of the flow
• on cancellation of the flow

Care should be taken when configuring self-registration flows for accounts with alias usernames without verification steps. Such setups are subject to race conditions and it may be possible for an attacker to generate multiple user accounts with the same alias. While such accounts are unusable and will not affect the normal operation of Airlock IAM, it is not desirable for an attacker to be able to create them.

To avoid this problem, it is possible to configure a unique index on the database to force all attributes in the username alias to be unique.

• Internal links:
• Loginapp UI