How do I check what MFA devices are registered to a user in Identity Cloud and AM (All versions)?
The purpose of this article is to provide information on checking which multi-factor authentication (MFA) devices are registered to a user in ForgeRock Identity Cloud and AM. This includes devices registered for WebAuthn, Push and OATH.
1 reader recommends this article
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
- 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:
- In the Identity Cloud admin UI, go to Identities > Manage and search for the user whose device details you want to view.
- Click on the user's name to display the user details.
- 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
Note
Writing scripts for end user journeys is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.
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:
- Log in to the End User UI.
- Click Edit Your Profile.
- 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:
- Click the ... menu next to the required device and select Edit Name.
- Enter a new name and click Save.
- Remove a device:
- Click the ... menu next to the required device and select Delete.
- Click Delete device to confirm.
- Change the device name:
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)