Get multifactor authentication status

Verifies whether it is possible to reset multifactor authentication (MFA) of the specified users, and retrieves authenticator apps activated by those users in Adaxes.

POST ~/api/directoryObjects/resetMfa/getStatus

Request parameters

This request has no parameters.

Request headers

  • Name

  • Required

  • Description

  • Adm-Authorization

  • True

  • Specify an access token.

  • Content-Type

  • True

  • Use application/json as the value of this header.

Request body

The request body is a JSON object with the following data structure:

{
    "directoryObjects": [
        "<objectId1>",
        "<objectId2>",
        ...
    ],
    "options": {
        "need365Status": <true|false>,
        "needAdaxesStatus": <true|false>
    }
}

directoryObjects string array

An array of identifiers of user accounts whose MFA status you want to check. You can use:

 Distinguished name (DN)
# Example
CN=John Smith,CN=Users,DC=example,DC=com
 Globally unique identifier (GUID)
# Example
a7b63270-b8a4-4c34-b830-7e0d09f2e021
 Security identifier (SID)
# Example
S-1-5-21-3625849556-2655411187-3268999566-9847

If you want to check the MFA status of a single user, the parameter value must be an array with a single element.

options GetResetMfaStatusOptions

Specifies whether to check the MFA status in Microsoft 365, Adaxes, or both.

 Show attributes

options.need365Status bool, optional

Set to true check whether Microsoft 365 MFA can be reset for any user specified in directoryObjects.

options.needAdaxesStatus bool, optional

Set to true to get all authenticator apps activated for Adaxes web interface or password self-service by the users specified in directoryObjects.

Responses

If successful, returns 200 OK status code and a ResetMFAStatus object the response body. Otherwise, returns one of the common HTTP error codes and an error description in the response body.

ResetMFAStatus is a JSON object with the following data structure:

{
    "canResetInM365": <true|false>,
    "adaxesActivatedApps": [ 
        <appId1>, 
        <appId2>, 
        ...
    ]
}

canResetInM365 bool

Returns true if Microsoft 365 MFA can be reset for any user specified in directoryObjects.

A value of true does not confirm that any user has secondary authentication methods enabled – it only means that at least one user has a Microsoft 365 account and MFA reset in Microsoft 365 can be attempted.

appsInAdaxesToReset AuthApps array

An array of authenticator apps activated in Adaxes by at least one user from those specified in directoryObjects.

 Show possible enum values
Google       = 0,    // Google Authenticator
Authy        = 1,    // Authy
Microsoft    = 2,    // Microsoft Authenticator
Okta         = 3,    // Okta Verify
OneLogin     = 4,    // OneLogin Protect
Duo          = 5,    // Duo Mobile
Auth0        = 6     // Auth0 Guardian

Examples

 Get multifactor authentication status of a user

The following code sample checks whether MFA can be reset for user John Smith and returns authenticator apps that John Smith activated in Adaxes.

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/resetMfa/getStatus"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-ACCESS-TOKEN}
$requestBody = ConvertTo-Json @{
    "directoryObjects" = @("CN=John Smith,CN=Users,DC=example,DC=com");
    "options" = @{
        "need365Status"   = $true;
        "needAdaxesStatus" = $true
    }
}

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/resetMfa/getStatus";

        // Create JSON request body
        string jsonRequest = @"
        {
            ""directoryObjects"": [
                ""CN=John Smith,CN=Users,DC=example,DC=com""
            ],
            ""options"": {
                ""need365Status"": true,
                ""needAdaxesStatus"": true
            }
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-ACCESS-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl --header 'Adm-Authorization: YOUR-ACCESS-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/resetMfa/getStatus' \
--data-raw '{
    "directoryObjects": [
        "CN=John Smith,CN=Users,DC=example,DC=com"
    ],
    "options": {
        "need365Status": true,
        "needAdaxesStatus": true
    }
}'
node.js
async function getMfaStatus() {
    // Request parameters
    const baseUrl = "https://host.example.com/restapi";
    const endpoint = "/api/directoryObjects/resetMfa/getStatus";
    const requestPath = `${baseUrl}${endpoint}`;

    // Create JSON request body
    const requestBody = {
        directoryObjects: ["CN=John Smith,CN=Users,DC=example,DC=com"],
        options: {
            need365Status: true,
            needAdaxesStatus: true
        }
    };

    // Make request
    const response = await fetch(requestPath, {
        method: "POST",
        headers: {
            "Adm-Authorization": "YOUR-ACCESS-TOKEN",
            "Content-Type": "application/json"
        },
        body: JSON.stringify(requestBody)
    });

    if (!response.ok) {
        throw new Error(`Request failed with status ${response.status}`);
    }

    const result = await response.json();
    console.log(result);
}

getMfaStatus();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/resetMfa/getStatus"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": "YOUR-ACCESS-TOKEN"}
requestBody = {
    "directoryObjects": [
        "CN=John Smith,CN=Users,DC=example,DC=com"
    ],
    "options": {
        "need365Status": True,
        "needAdaxesStatus": True
    }
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "canResetInM365": true,
    "adaxesActivatedApps": [ 2, 5 ]
}

See also

© Softerra 2022. All rights reserved.
Send feedback