ICF 1.5.20.34

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

Managing authentication methods requires the following Microsoft Graph application permissions on your Azure app registration:

  • UserAuthenticationMethod.Read.All: Required to list authentication methods.

  • UserAuthenticationMethod.ReadWrite.All: Required to create, update, or delete authentication methods.

Learn more in the Microsoft documentation:

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

Limitations

The Microsoft Graph API enforces the following constraints on phone authentication methods:

  • A user must have a mobile phone number before you can add an alternate_mobile number.

  • You can’t change a phone number’s type directly. To change the type, add a new number with the desired type, then delete the number with the original type.

  • To remove a mobile number from a user that also has an alternate_mobile number, first update the mobile number to the new number, then delete the alternate_mobile number.

  • If a user is enabled to use SMS sign-in, changing the mobile number triggers re-registration of the number for SMS sign-in.

Learn more in phoneAuthenticationMethod resource type.

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