ICF 1.5.20.27

Authentication methods (MS Graph API)

The MS Graph API connector lets you read and manage the following multi-factor authentication (MFA) methods from the user resource:

MFA method Supported operations

Email

Create, Update, Delete

Phone

Create, Update, Delete

FIDO2

Delete

Microsoft Authenticator

Delete

Software OATH

Delete

List MFA methods

List the authentication methods with the authenticationMethods user relationship:

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/azuread/user/88080bec-30bd-4026-b5af-5d4607dc7ccc/?_fields=authenticationMethods"
Response
{
  "_id": "88080bec-30bd-4026-b5af-5d4607dc7ccc",
  ...
  "authenticationMethods": [
    {
      "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
      "createdDateTime": "2024-12-11T01:07:44Z",
      "id": "28c10230-6103-485e-b985-444c60001490"
    }
  ]
}

Create or update email MFA method

The create and update requests are identical.
Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "__emailAuthenticationMethod__": "add_email@example.com"
}' \
"http://localhost:8080/openidm/system/azuread/user/a9299a21-c384-4882-b363-8d7427b36fc5"
Response
{
  "_id": "a9299a21-c384-4882-b363-8d7427b36fc5",
  ...
  "authenticationMethods": [
    {
      "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
      "createdDateTime": "2024-12-11T01:07:47Z",
      "id": "28c10230-6103-485e-b985-444c60001490"
    },
    {
      "emailAddress": "add_email@example.com",
      "@odata.type": "#microsoft.graph.emailAuthenticationMethod",
      "id": "3ddfcfc8-9383-446f-83cc-3ab9be4be18f"
    }
  ]
}

Remove email MFA method

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "__emailAuthenticationMethod__": null
}' \
"http://localhost:8080/openidm/system/azuread/user/bfe4b140-3b76-4633-855c-26e21a7517c9"
Response
{
  "_id": "bfe4b140-3b76-4633-855c-26e21a7517c9",
  ...
  "authenticationMethods": [
    {
      "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
      "createdDateTime": "2024-12-11T01:07:56Z",
      "id": "28c10230-6103-485e-b985-444c60001490"
    }
  ]
}

Manage phone MFA method

To manage phone MFA methods, provide an authoritative list of numbers using a PUT request on the user object. Phone numbers use the format {phoneNumber}:{phoneType} under the special user attribute __phoneAuthenticationMethods__. The connector performs a diff between the request and the user’s current list of numbers, and does the following:

  • Adds new numbers.

  • Removes existing numbers not in the request.

  • Replaces non-matching existing numbers for phone types.

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "__phoneAuthenticationMethods__": [
    "+1 7322714703:mobile",
    "+1 7322714705:alternate_mobile",
    "+1 7322714709:office"
  ]
}' \
"http://localhost:8080/openidm/system/azuread/user/00490cf6-4fdd-4b7b-86dd-907e3d613fd0"
Response
{
  "_id": "00490cf6-4fdd-4b7b-86dd-907e3d613fd0",
  ...
  "__phoneAuthenticationMethods__": [
    "+1 7322714709:OFFICE",
    "+1 7322714705:ALTERNATE_MOBILE",
    "+1 7322714703:MOBILE"
  ]
}

Remove Microsoft Authenticator, FIDO2, and software OATH MFA methods

Microsoft’s API only supports the removal of Microsoft Authenticator, FIDO2, and software OATH MFA methods. The connector implements the removal of these MFA methods using the following virtual attributes:

  • __removeMicrosoftAuthenticatorMethods__

  • __removeFido2Methods__

  • __removeSoftwareOathMethods__

The following example removes a Microsoft Authenticator MFA method:

Request
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "__removeMicrosoftAuthenticatorMethods__": [
    "00490cf6-4fdd-4b7b-86dd-907e3d613fd0"
  ]
}' \
"http://localhost:8080/openidm/system/azuread/user/bfe4b140-3b76-4633-855c-26e21a7517c9"
Response
{
  "_id": "bfe4b140-3b76-4633-855c-26e21a7517c9",
  ...
  "authenticationMethods": [
    {
      "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
      "createdDateTime": "2024-12-11T01:07:56Z",
      "id": "28c10230-6103-485e-b985-444c60001490"
    }
  ]
}