---
title: Username retrieval configuration
description: To set up basic forgotten username configuration, you'll need at least the following configuration files:
component: pingidm
version: 7.5
page_id: pingidm:self-service-reference:uss-username-config
canonical_url: https://docs.pingidentity.com/pingidm/7.5/self-service-reference/uss-username-config.html
keywords: ["JSON", "Rest", "Configuration", "Authentication", "Self-Service", "User Self-Service"]
section_ids:
  uss-username-ui: Configuring Forgotten Username Retrieval From the admin UI
---

# 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:

  ```json
  {
      "name" : "captcha",
      "recaptchaSiteKey" : "<siteKey>",
      "recaptchaSecretKey" : "<secretKey>",
      "recaptchaUri" : "https://www.google.com/recaptcha/api/siteverify"
  },
  ```

  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](recaptcha.html).

* 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:

  ```json
  {
      "name" : "userQuery",
      "validQueryFields" : [
          "mail",
          "givenName",
          "sn"
      ],
      "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](../external-services-guide/email.html). For details about the required addition to `selfservice-registration.json` , refer to [Email for forgotten username](uss-email-forgotten.html).

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

  ```json
  {
      "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.