Use case: Use email address as the username in ForgeRock Identity Cloud

Use case overview

Many organizations, particularly those in the Consumer Identity & Access Management (CIAM) space, want to enable a slick low friction experience for their customers. One easy way to achieve this is by using the email address as the username, rather than customers having to remember words or a set of characters.

Steps to achieve this use case

A key feature and differentiator of ForgeRock Identity Cloud is its flexibility. You can take advantage of this flexibility to configure the email address as the userName attribute in three quick and easy steps.

Step 1: Apply an email policy to the userName attribute

  1. Sign in to the Identity Cloud admin UI using your admin tenant URL, in the format https://<tenant-name>/am/XUI/?realm=/#/.

  2. Go to Native Consoles > Identity Management > Configure > Managed Objects > Alpha_user and click userName.

  3. Update Readable Title to Email Address.

  4. On the Validation tab, click Add Policy.

  5. Enter valid-email-address-format in the Policy Id field and click Add.

The configuration should look similar to this:

A valid email address will now be required for the userName attribute.

NOTE: Unlike the mail attribute, the userName attribute has a uniqueness check, which is essential to avoid duplicate entries. This is the reason why you would change the userName attribute rather than changing the mail attribute directly.

Step 2: Auto provision the mail attribute

Since some features rely on the mail attribute, you’ll need to silently set the mail attribute whenever the userName attribute is set.

  1. Staying in the userName property configuration, on the Scripts tab, select onStore and click Add Script.

  2. Add the following script, which silently sets the mail attribute based on the userName:

     object.mail = object.userName.toLowerCase();
  3. Click Save.

Step 3: Hide the mail attribute

For a better user experience and to keep things clean and tidy, we recommend making the mail attribute non-viewable or editable by end users.

  1. In Native Consoles > Identity Management, go to Configure > Managed Objects > Alpha_user and click mail.

  2. On the Details tab, click Show advanced options.

  3. Toggle Viewable and User Editable to off.

  4. Click Save.


The login experience for Identity Cloud end users will be similar to this:


Use case variations

Changing the User Name field name to “Email Address”

To make it clear to end users that an email address is required for sign in, you may wish to change the User Name field name to Email Address on the Sign In screen, similar to this:

To change the User Name field name to Email Address in the Sign In screen:

  1. In the Identity Cloud admin UI, go to Journeys > Login > Edit.

  2. Click on the Platform Username node.

  3. In the node properties:

    • Select the Validate username option.

    • Enter mail in the Username Attribute field.

    The configuration should look like this:

  4. Click Save to save the journey.

The User Name field name in the end user Sign In screen is now Email Address.

Additional resources