IDM 7.3.1

Username retrieval configuration

To set up basic forgotten username configuration, you’ll need at least the following configuration files:

  • selfservice-username.json

    You can find a template version of this file in the following directory: openidm/samples/example-configurations/self-service.

  • ui-configuration.json

    You can find this file in the default IDM project configuration directory, openidm/conf.

To set up forgotten username retrieval, enable the following boolean in ui-configuration.json:

"forgotUsername" : true,

You can include several features with forgotten username retrieval, as shown in the following excerpts of the selfservice-reset.json file:

  • If you’ve activated Google reCAPTCHA for forgotten username retrieval, you’ll refer to the following code block:

        "name" : "captcha",
        "recaptchaSiteKey" : "<siteKey>",
        "recaptchaSecretKey" : "<secretKey>",
        "recaptchaUri" : ""

    As suggested by the code, you’d substitute actual siteKey and secretKey assigned by Google for your domain. For more information, refer to Google reCAPTCHA.

  • For forgotten username retrieval, IDM needs to verify user identities. To ensure that usernames are sent to the right user, include the following code block:

        "name" : "userQuery",
        "validQueryFields" : [
        "identityIdField" : "_id",
        "identityEmailField" : "mail",
        "identityUsernameField" : "userName",
        "identityServiceUrl" : "managed/user"

    This code allows IDM to verify user identities by their username, email address, first name (givenName), or last name (sn, short for surname).

  • If you have included email verification, you must configure an outgoing email server. For details about the required addition to selfservice-registration.json , refer to Email for forgotten username.

  • The following code block, after confirming user identity, allows IDM to display the username:

        "name" : "retrieveUsername"

Configuring Forgotten Username Retrieval From the admin UI

To configure forgotten username retrieval using the admin UI, select Configure > Forgotten Username. When you activate Enable Forgotten Username Retrieval, a Configure Forgotten Username Form window displays, and you can specify:

  • Identity Resource, typically managed/user.

  • Advanced Options, Snapshot Token, typically a JSON Web Token (JWT).

  • Advanced Options, Token Lifetime, with a default of 300 seconds.

You can also add these settings to the selfservice-username.json configuration file. When you modify these settings in the admin UI, IDM creates the file for you.

Copyright © 2010-2024 ForgeRock, all rights reserved.