ICF 1.5.20.28

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"
    }
  ]
}
json

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"
    }
  ]
}
json

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"
    }
  ]
}
json

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"
  ]
}
json

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"
    }
  ]
}
json