REST API for Oracle Identity Cloud Service

Fetch Enrolled Factors of a User

This use case provides a step-by-step example of using the Oracle Identity Cloud Service Verification API to fetch the factors that a user is enrolled in.

Note:

See the Oracle Identity Cloud Service Authentication API Postman collection for extensive authentication use case examples. Download the collection and the global variables file from the idcs-factor-enrollment-api folder within GitHub and then import them into Postman.

The step to follow in this use case depends on whether you want to request via userGUID or User Name:

Note:

These steps assume that relevant factors of MFA are enabled using Configure Multi-Factor Authentication Settings .

Step 1: Get Enrolled Factors for a User by userGUID

This step gets the enrolled factors for a user based on the userGUID or User name.

Request Example

GET {{HOST}}/mfa/v1/users/{{userGUID}}/factors

Response Example

The following example shows the contents of the response in JSON format:


{
    "userGUID": "7b3d902ab05b4214bae6b2924ca6be21",
    "status": "success",
    "preferredFactorId": "b3e04149d958437b9b801fa70c33ca70",
    "preferredMethod": "EMAIL",
    "factors": [
        {
            "factorId": "SecurityQuestions",
            "methods": [
                "SECURITY_QUESTIONS"
            ]
        },
        {
            "displayName": "+155XXXXX555",
            "factorId": "83889faeacaf4592a964405f87506fc6",
            "methods": [
                "SMS"
            ]
        },
        {
            "displayName": "uxxr1@example.com",
            "factorId": "b3e04149d958437b9b801fa70c33ca70",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        }
    ]
}

The response contains the userGUID, the preferred factor, and the enrolled factor details.

Step 2: Get Enrolled Factors for a User by Using Filters

You can get enrolled factors for a user by using either User Name or User GUID. The following userIdType values are accepted:

USER_GUID - For example, here userId should contain USER_GUID such as "7b3d902ab05b4214"
USER_NAME - For example, here userId should contain USER_NAME such as John.

Request Example to fetch the enrolled factors based on User Name

The following example shows the request example to get the enrolled factors for a user based on their User Name in JSON format:


GET {{HOST}}/mfa/v1/users?userId=user1@example.com&userIdType=USER_NAME&attributes=factors

Response Example

The following example shows the contents of the response in JSON format:

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

The response contains the userGUID, the preferred factor, and the enrolled factor details.

Request Example to fetch the enrolled factors based on User GUID

The following example shows the request example to get the enrolled factors for a user based on their User GUID in JSON format:


GET {{HOST}}/mfa/v1/users?userId=589879c55b7340518141eab82493f0cc&userIdType=USER_GUID&attributes=factors

Response Example

The following example shows the contents of response in JSON format:

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

The response contains the userGUID, the preferred factor, and the enrolled factor details.