How do I check what MFA devices are registered to a user in Identity Cloud and AM (All versions)?

Overview

You can use REST to retrieve a list of MFA devices registered to a particular user or you can use a Scripted authentication node to retrieve the MFA devices for a user within a journey or tree, depending on your use case. Alternatively, a user can view their own MFA devices via the platform End User UI; this is different from the standalone AM UI.

See the following sections for further information:

• Using the REST API to list MFA devices registered to a user
  • Web Authentication (WebAuthn)
  • Push
  • Open AuTHentication (OATH)
• Retrieving a list of MFA devices in a script
• Viewing MFA devices via the End User UI

Prerequisites

Identity Cloud

Before you can make any of the REST calls detailed in this article for Identity Cloud, you will need:

• The session cookie name and a tenant administrator's session token. See Access global settings and Authenticate to Identity Cloud REST API with session token for further information.
• The _id of the user you want to view devices for. You can find this as follows:
  1. In the Identity Cloud admin UI, go to Identities > Manage and search for the user whose device details you want to view.
  2. Click on the user's name to display the user details.
  3. Select Raw JSON and copy the profile ID value displayed in the “_id” field.

AM

Before you can make any of the REST calls detailed in this article for AM, you will need to authenticate as an admin user. For example: $ curl -X POST -H "X-OpenAM-Username: amadmin" -H "X-OpenAM-Password: cangetinam" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" https://am.example.com:8443/am/json/realms/root/authenticate?authIndexType=service&authIndexValue=adminconsoleserviceExample response: { "tokenId": "AQIC5wM2LY4SfcxsuvGEjcsppDSFR8H8DYBSouTtz3m64PI.*AAJTSQACMDIAAlNLABQtNTQwMTU3NzgxODI0NzE3OTIwNAEwNDU2NjE0*", "successUrl": "/am/console", "realm": "/" }Please observe the following when constructing REST calls:

• Make the REST call to the actual AM server URL (not lb).
• Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
• Set this session cookie header to the token returned when you authenticated.
• Ensure the Accept-API-Version header contains valid resource versions.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

Using the REST API to list MFA devices registered to a user

WebAuthn

You can retrieve a list of WebAuthn devices associated with a user by making a call to the users/<user-id>/devices/2fa/webauthn endpoint.

For example:

• Identity Cloud:$ curl --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/<user-id>/devices/2fa/webauthn?_prettyPrint=true&_queryFilter=true' \ --header '<session-cookie-name>: <session-token>' \ --header 'Accept-API-Version: resource=1.0'Where <tenant-env-fqdn> is your Identity Cloud tenant name, <user-id> is the _id of the user and <session-cookie-name>: <session-token> is the cookie name and session token.
• AM:$ curl --request GET 'https://am.example.com:8443/am/json/realms/root/users/<username>/devices/2fa/webauthn?_prettyPrint=true&_queryFilter=true' \ --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \ --header 'Accept-API-Version: resource=1.0'Where <username> is the username of the user.

Example response:{  "result" : [ {     "_id" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "_rev" : "172031596",     "deviceName" : "New Security Key",     "uuid" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "deviceManagementStatus" : false   } ],   "resultCount" : 1,   "pagedResultsCookie" : null,   "totalPagedResultsPolicy" : "NONE",   "totalPagedResults" : -1,   "remainingPagedResults" : -1 }

Push

You can retrieve a list of Push devices associated with a user by making a call to the users/<user-id>/devices/2fa/push endpoint.

For example:

• Identity Cloud:$ curl --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/<user-id>/devices/2fa/push?_prettyPrint=true&_queryFilter=true' \ --header '<session-cookie-name>: <session-token>' \ --header 'Accept-API-Version: resource=1.0'Where <tenant-env-fqdn> is your Identity Cloud tenant name, <user-id> is the _id of the user and <session-cookie-name>: <session-token> is the cookie name and session token.
• AM:$ curl --request GET 'https://am.example.com:8443/am/json/realms/root/users/<username>/devices/2fa/push?_prettyPrint=true&_queryFilter=true' \ --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \ --header 'Accept-API-Version: resource=1.0'Where <username> is the username of the user.

Example response:{  "result" : [ {     "_id" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "_rev" : "172031596",     "deviceName" : "Push Device",     "uuid" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "deviceManagementStatus" : false   } ],   "resultCount" : 1,   "pagedResultsCookie" : null,   "totalPagedResultsPolicy" : "NONE",   "totalPagedResults" : -1,   "remainingPagedResults" : -1 }

OATH

You can retrieve a list of OATH devices associated with a user by making a call to the users/<user-id>/devices/2fa/oath endpoint.

For example:

• Identity Cloud:$ curl --request GET 'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/users/<user-id>/devices/2fa/oath?_prettyPrint=true&_queryFilter=true' \ --header '<session-cookie-name>: <session-token>' \ --header 'Accept-API-Version: resource=1.0'Where <tenant-env-fqdn> is your Identity Cloud tenant name, <user-id> is the _id of the user and <session-cookie-name>: <session-token> is the cookie name and session token.
• AM:$ curl --request GET 'https://am.example.com:8443/am/json/realms/root/users/<username>/devices/2fa/oath?_prettyPrint=true&_queryFilter=true' \ --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" \ --header 'Accept-API-Version: resource=1.0'Where <username> is the username of the user.

Example response:{  "result" : [ {     "_id" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "_rev" : "172031596",     "deviceName" : "OATH Device",     "uuid" : "b36da956-9ecf-47dc-a1b9-6b69b0cd9e2a",     "deviceManagementStatus" : false   } ],   "resultCount" : 1,   "pagedResultsCookie" : null,   "totalPagedResultsPolicy" : "NONE",   "totalPagedResults" : -1,   "remainingPagedResults" : -1 }

Retrieving a list of MFA devices in a script

MFA details are stored in the following profile attributes:

• WebAuthn: webauthnDeviceProfiles
• Push: pushDeviceProfiles
• OATH: oathDeviceProfiles

This means you can access these attributes in scripts in the same way that you access other profile attributes. See Access profile data for further information.

For example, using a method such as:idRepository.getAttribute(username,"webauthnDeviceProfiles")

Viewing MFA devices via the End User UI

A user can view their own MFA devices via the platform End User UI as follows:

1. Log in to the End User UI.
2. Click Edit Your Profile.
3. In the Sign-in & Security section, click Change next to 2-Step Verification; this shows a user all the devices that have been registered for MFA on their account. From here, they can:
   • Change the device name:
     1. Click the ... menu next to the required device and select Edit Name.
     2. Enter a new name and click Save.
   • Remove a device:
     1. Click the ... menu next to the required device and select Delete.
     2. Click Delete device to confirm.

See Also

Identity Cloud:

• MFA: Web authentication (WebAuthn)
• MFA: Push authentication
• MFA: Open Authentication (OATH)
• Use case: Configure passwordless login in ForgeRock Identity Cloud

AM:

• How is MFA data stored in AM?
• MFA: Web Authentication (WebAuthn)
• MFA: Push authentication
• MFA: Open AuTHentication (OATH)

Related Training

N/A

Related Issue Tracker IDs

issue_OPENAM-18790 (Allow exposing OATH/Push/WebAuthn Device profile attributes via REST)

issue_OPENAM-17105 (Provide customers with the ability to customise information stored about Push/OATH Devices )