--- title: Authentication methods (MS Graph API) description: The MS Graph API connector lets you read and manage the following multi-factor authentication (MFA) methods from the user resource: component: openicf page_id: openicf:connector-reference:msgraph-authentication-methods canonical_url: https://docs.pingidentity.com/openicf/connector-reference/msgraph-authentication-methods.html section_ids: list_mfa_methods: List MFA methods create_or_update_email_mfa_method: Create or update email MFA method remove_email_mfa_method: Remove email MFA method manage_phone_mfa_method: Manage phone MFA method limitations: Limitations remove_microsoft_authenticator_fido2_and_software_oath_mfa_methods: Remove Microsoft Authenticator, FIDO2, and software OATH MFA methods --- # 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 ```json { "_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 ```json { "_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 ```json { "_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](msgraph-conf.html#procedure-prepare-azuread) 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:- [phoneAuthenticationMethod resource type](https://learn.microsoft.com/en-us/graph/api/resources/phoneauthenticationmethod?view=graph-rest-1.0) - [Microsoft Entra authentication methods API overview](https://learn.microsoft.com/en-us/graph/api/resources/authenticationmethods-overview?view=graph-rest-1.0) | 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 ```json { "_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](https://learn.microsoft.com/en-us/graph/api/resources/phoneauthenticationmethod?view=graph-rest-1.0). ## 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 ```json { "_id": "bfe4b140-3b76-4633-855c-26e21a7517c9", ... "authenticationMethods": [ { "@odata.type": "#microsoft.graph.passwordAuthenticationMethod", "createdDateTime": "2024-12-11T01:07:56Z", "id": "28c10230-6103-485e-b985-444c60001490" } ] } ```