Retrieving Forgotten Usernames

The AM UI includes pages for users to recover their forgotten usernames. You can, however, create a RESTful application to leverage the user self-service features.

Forgotten Username Flow (UI)

To Retrieve a Forgotten Username (REST)

When performing user self-service functions, you can enable one or more security methods, such as email validation, Google reCAPTCHA, knowledge-based authentication, or custom plugins. Each configured security method requires requests to be sent from AM to the client, and completed responses returned to AM to verify.

A unique token is provided in the second request to the client that must be used in any subsequent responses, so that AM can maintain the state of the user self-service process.

Create a GET request to the /selfservice/forgottenUsername endpoint. Notice that the request does not require any form of authentication.

$ curl \
--header "Accept-API-Version: resource=1.0" \
https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername
{
  "type": "captcha",
  "tag": "initial",
  "requirements": {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "description": "Captcha stage",
     "type": "object",
     "required": [
       "response"
     ],
     "properties": {
       "response": {
         "recaptchaSiteKey": "6Lfr1...cIqbd",
         "description": "Captcha response",
         "type": "string"
       }
      }
  }
}

In this example, the Google reCAPTCHA plugin is enabled, so the first request is of the captcha type.

Create a POST response back to the /selfservice/forgottenUsername endpoint with a query string containing _action=submitRequirements. In the POST data, include an input element in the JSON structure, which should contain values for each element in the required array of the request.
In this example, a response value was requested, which should be the user input as provided after completing the Google reCAPTCHA challenge.
```
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--data \
'{
    "input": {
        "response": "03AHJ...qiE1x4"
    }
}' \
https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername?_action=submitRequirements
{
    "type": "userQuery",
    "tag": "initial",
    "requirements": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Find your account",
        "type": "object",
        "required": [
            "queryFilter"
        ],
        "properties": {
            "queryFilter": {
                "description": "filter string to find account",
                "type": "string"
            }
        }
    },
    "token": "eyAicHis...PIF-lN4s"
}
```
If the response was accepted, AM continues with the username retrieval process and sends the next request for information. In this example, the Google reCAPTCHA was verified and AM is requesting details about the account name to retrieve, which must be provided in a queryFilter element.
The value of the token element should be included in this and all subsequent responses to AM for this retrieval process.

Create a POST response to AM with a queryFilter value in the POST data containing the user's email address associated with their account:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--data \
'{
    "input": {
        "queryFilter": "mail eq \"demo.user@example.com\""
    },
    "token": "eyAicHis...PIF-lN4s"
}' \
https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername?_action=submitRequirements
{
    "type": "kbaSecurityAnswerVerificationStage",
    "tag": "initial",
    "requirements": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Answer security questions",
        "type": "object",
        "required": [
            "answer1"
        ],
        "properties": {
            "answer1": {
                "systemQuestion": {
                    "en": "What was the model of your first car?"
                },
                "type": "string"
            }
        }
    },
    "token": "eyAicHis...PIF-lN4s"
}

If a single subject is located that matches the provided query filter, the retrieval process continues.

If KBA is enabled, AM requests answers to the configured number of KBA questions, as in this example.

For more information on query filters, see "Query".

If a subject is not found, an HTTP 400 Bad Request status is returned, and an error message in the JSON data:

{
    "code": 400,
    "reason": "Bad Request",
    "message": "Unable to find account"
}

Return a POST response with the answers as values of the elements specified in the required array, in this example answer1. Ensure the same token value is sent with each response.
```
$ curl \
--request POST \
--header "Content-Type: application/json" \
--data \
'{
    "input": {
        "answer1": "Mustang"
    },
    "token": "eyAicHis...PIF-lN4s"
}' \
https://openam.example.com:8443/openam/json/realms/root/selfservice/forgottenUsername?_action=submitRequirements
{
    "type": "retrieveUsername",
    "tag": "end",
    "status": {
        "success": true
    },
    "additions": {
        "userName": "demo"
    }
}
```
When the process is complete, the tag element has a value of end. If the success element in the status element has a value of true, then username retrieval is complete and the username is emailed to the registered address.
If the Show Username option is enabled for username retrieval, the username retrieved is also returned in the JSON response as the value of the userName element, as in the example above.