> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/automation/runbooks/runbook-references/user/security/set-or-remove-mobile-phone-mfa.md). # Set Or Remove Mobile Phone Mfa ### Description Adds, updates, or removes the user's mobile phone authentication method. This runbook manages phone numbers as regular MFA factors (call/text verification). Important: The Microsoft Graph phoneMethods API does not offer a way to add a phone number as "MFA only" without triggering an automatic SMS Sign-In registration attempt. If the user is enabled by the tenant's Authentication Methods Policy for SMS Sign-In, Graph will automatically try to register the number for SMS Sign-In after creating or updating the phone method. If the number is already used by another user for SMS Sign-In, Graph returns a 409 Conflict with error code "phoneNumberNotUnique". However, the phone method itself (for regular MFA) is typically created or updated successfully despite this error. The smsSignInState property is read-only and cannot be controlled via the create/update request. SMS Sign-In can only be explicitly managed via the separate enableSmsSignIn and disableSmsSignIn endpoints. This runbook verifies the actual state after such errors and reports success if the MFA method was assigned, with a warning about the SMS Sign-In conflict. If the assignment truly failed, it searches for the user holding the number. ### Activate user notification This runbook can optionally send a notification email to the target user informing them that their mobile phone MFA method was added, updated, or removed by an administrator. To enable this, you need to activate user notification in the runbook customization. The json configuration for this is as follows: ```json "rjgit-user_security_set-or-remove-mobile-phone-mfa": { "parameters": { "UserId": { "Hide": true }, "NotifyUser": { "Default": true, "Hide": true }, "EmailFrom": { "Hide": true }, "ServiceDeskDisplayName": { "Hide": true }, "ServiceDeskEmail": { "Hide": true }, "ServiceDeskPhone": { "Hide": true }, "ServiceDeskPortalUrl": { "Hide": true }, "ServiceDeskTicketUrl": { "Hide": true }, "LanguageOverride": { "Hide": true }, "CallerName": { "Hide": true } } } ``` For more information on how to customize runbooks, please refer to the [Runbook Customization Guide](https://docs.realmjoin.com/automation/runbooks/runbook-customization). ### Setup regarding email sending Sending a notification email is optional and only happens when `NotifyUser` is enabled. The sender address is taken from the `RJReport.EmailSender` tenant setting. This runbook sends emails using the Microsoft Graph API. To send emails via Graph API, you need to configure an existing email address in the runbook customization. See the [RealmJoin Report Settings documentation](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings) for details. #### Email branding The report email honors the optional `RJReport.Branding.*` tenant settings: a custom header image, a custom footer image (public HTTPS URLs, PNG/JPEG/GIF, max. 200 KB each), a custom footer link, and custom accent and text colors (6-digit hex values, e.g. `#0052cc`). When these settings are not configured, the default RealmJoin graphics and colors are used. A branding image that cannot be downloaded or validated, or a color value that is not a valid hex color, never prevents the report email - the corresponding default is used instead. See the [RealmJoin Report Settings documentation](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings) for setup details. ### Location User → Security → Set Or Remove Mobile Phone MFA **Full Runbook name** rjgit-user\_security\_set-or-remove-mobile-phone-MFA ### Details | Property | Value | | ---------------- | --------------------------------------------------------------------------------------- | | Version | 2.3.0 | | Required modules |

RealmJoin.RunbookHelper (>= 0.8.9)
Microsoft.Graph.Authentication (>= 2.39.0)

| | Schedulable | no | ### Notes Permissions (managed identity, application): * UserAuthenticationMethod.ReadWrite.All - manage phone authentication methods * User.Read.All - resolve target user * Organization.Read.All - read tenant display name for the email body * Mail.Send - only required when NotifyUser is enabled ### Permissions #### Application permissions * **Type**: Microsoft Graph * AuditLog.Read.All * *Queries userRegistrationDetails to find which user holds a conflicting SMS sign-in number* * User.Read.All * *Resolves the target user and batch-reads other users' phone methods for conflict checks* * UserAuthenticationMethod.ReadWrite.All * *Sets, updates or removes the user's mobile phone authentication method* * Mail.Send *(optional — feature: Email report)* * *Mails the user that an admin changed their MFA phone when NotifyUser is enabled* * Organization.Read.All *(optional — feature: Email notification)* * *Reads the tenant display name for the notification email when NotifyUser is enabled* ### Parameters #### UserId Object ID of the target user. | Property | Value | | ---------------- | -------------------------------------- | | Required | true | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### phoneNumber Mobile phone number in international E.164 format (e.g., +491701234567). | Property | Value | | ------------------- | ------------------- | | Required | true | | Default Value | | | Type | String | | Portal display name | Mobile Phone Number | #### Remove "Set/Update Mobile Phone MFA Method" (final value: $false) or "Remove Mobile Phone MFA Method" (final value: $true) can be selected as action to perform. If set to true, the runbook will remove the mobile phone MFA method for the user. If set to false, it will add or update the mobile phone MFA method with the provided phone number. | Property | Value | | ------------------- | ------------------------------------- | | Required | false | | Default Value | False | | Type | Boolean | | Portal display name | Add or Remove Mobile Phone MFA Method | **Portal options** | Portal option | Value | | -------------------------------------------- | ----- | | Add this number as Mobile Phone MFA factor | false | | Remove this number / mobile phone MFA factor | true | #### NotifyUser When enabled, sends a notification email to the target user informing them that their mobile phone MFA method was added or removed by an administrator. Default is disabled. | Property | Value | | ------------------- | -------------------------------------- | | Required | false | | Default Value | False | | Type | Boolean | | Portal display name | Notify user via email | | Hidden in portal | yes (preset via runbook customization) | #### EmailFrom Sender email address for the optional notification mail. Sourced from the RealmJoin tenant setting RJReport.EmailSender. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### BrandingHeaderImageUrl Optional public HTTPS URL of a custom header image (PNG/JPEG/GIF, max. 200 KB) for the report email. Sourced from the RJReport.Branding.HeaderImageUrl tenant setting. When empty, the default RealmJoin header graphic is used. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### BrandingFooterImageUrl Optional public HTTPS URL of a custom footer image (PNG/JPEG/GIF, max. 200 KB) for the report email. Sourced from the RJReport.Branding.FooterImageUrl tenant setting. When empty, the default RealmJoin footer graphic is used. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### BrandingFooterLink Optional URL the footer image links to. Sourced from the RJReport.Branding.FooterLink tenant setting. When empty, the default link () is used. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### BrandingAccentColor Optional accent color override (6-digit hex, e.g. '#0052cc') for the report email template. Sourced from the RJReport.Branding.AccentColor tenant setting. When empty or invalid, the default RealmJoin accent color is used. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### BrandingTextColor Optional text color override (6-digit hex) for the report email template. Sourced from the RJReport.Branding.TextColor tenant setting. When empty or invalid, the default RealmJoin text color is used. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### ServiceDeskDisplayName Service Desk display name for user contact information (optional). Sourced from the RealmJoin tenant setting RJReport.ServiceDesk\_DisplayName. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### ServiceDeskEmail Service Desk email address for user contact information (optional). Sourced from the RealmJoin tenant setting RJReport.ServiceDesk\_EMail. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### ServiceDeskPhone Service Desk phone number for user contact information (optional). Sourced from the RealmJoin tenant setting RJReport.ServiceDesk\_Phone. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### ServiceDeskPortalUrl Service Desk portal URL for user contact information, rendered as a clickable link (optional). Sourced from the RealmJoin tenant setting RJReport.ServiceDesk\_PortalUrl. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### ServiceDeskTicketUrl Direct link to the Service Desk ticket related to this request, rendered as a clickable link (optional). Empty by default, so no ticket link is added. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | #### LanguageOverride Overrides the language used for the notification email. Accepted values are 'DE' (German) or 'EN' (English). If left empty, the language is determined automatically based on the target user's usage location. | Property | Value | | ---------------- | -------------------------------------- | | Required | false | | Default Value | | | Type | String | | Hidden in portal | yes (preset via runbook customization) | [Back to Runbook Reference overview](/automation/runbooks/runbook-references.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/automation/runbooks/runbook-references/user/security/set-or-remove-mobile-phone-mfa.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.