Daily.Entra.News
Aboutmerill.net
Microsoft Entra ID
Authentication

Set Up Sms Voice Api

2 November 2026Doc update+0 / −253 lines

In brief

The article describing CYOT provider purchase, Azure integration deployment, permissions, policy configuration, and testing is no longer documented at this location.

What Entra admins need to know

Administrators relying on this article for CYOT setup instructions may need to find the updated documentation.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

deleted file mode 100644

title: Set up SMS and voice description: Deploy your telecom integration, validate evaluation mode, and gradually roll out SMS and voice delivery by using CYOT APIs. ms.topic: how-to ms.date: 10/30/2026 ai-usage: ai-assisted

Customer intent: As an identity administrator, I want to deploy a telecom integration and configure SMS and voice delivery through Microsoft Graph.

Set up SMS and voice

Use Choose Your Own Telephony Provider (CYOT) to deliver SMS and voice authentication through your organization's telephony provider. With CYOT, you purchase a supported provider offer through Microsoft Security Store, deploy the integration in your Azure subscription, and configure Microsoft Entra to route SMS or voice authentication through your provider.

This article walks you through the end-to-end setup, including purchasing your provider offer, deploying the integration, configuring the authentication method policy, and testing the experience before moving to production.

How the integration works

CYOT uses an Azure Function in your Azure subscription to connect Microsoft Entra with your telephony provider. The Azure Function processes SMS or voice requests from Microsoft Entra and sends them to your provider for delivery.

:::image type="content" source="media/concept-phone-providers/telephony-provider-integration-diagram.jpeg" alt-text="Diagram of the CYOT integration connecting Microsoft Entra to a telephony provider through an Azure Function in your Azure subscription.":::

Prerequisites

Before you begin, prepare:

  • A Microsoft Entra workforce tenant.
  • An Azure subscription with a valid payment method to host the integration and subscribe to your provider. See Security Store purchasing prerequisites.
  • Azure Cloud Shell in PowerShell mode (recommended), or PowerShell 7.0+ with Azure CLI 2.61+ for integration deployment.
  • A test user with a phone number registered for SMS or voice authentication.

Required permissions

Use accounts with the following permissions:

TaskRequired accessWhy it's needed
Create the applicationPermission to register applications in the customer tenantLets setup create the application that securely connects Microsoft Entra to your integration.
Deploy Azure resourcesSubscription Owner, or Contributor + Role Based Access Control Administrator at the required scopeLets setup deploy the integration in your subscription.
Grant directory access during deploymentPrivileged Role AdministratorLets setup grant the directory permissions that Microsoft Entra needs to route requests to your integration.
Read authentication method policyDelegated Policy.Read.AuthenticationMethod permission and a supported role, such as Authentication Policy AdministratorAllows setup to read the existing SMS or voice authentication method configuration.
Update authentication method policyAuthentication Policy Administrator and delegated Policy.ReadWrite.AuthenticationMethod permissionAllows setup to configure the SMS or voice authentication method to use the integration.

Step 1: Purchase and activate your telecom provider

  1. Purchase your provider's offer from Microsoft Security Store. For detailed purchasing instructions, see Purchase and deploy a SaaS solution from Security Store.
  2. After you Place Order, select Configure Account Now and follow your provider's registration instructions.
  3. Keep this page available and continue to step 2. You'll complete registration in step 3 with the application ID from the deployment summary.

Step 2: Deploy the integration

Use Azure Cloud Shell in PowerShell mode to run the setup script for the telecom provider you select.

What the setup script does

The setup script deploys everything needed to connect Microsoft Entra ID to your telecom provider, so you don't have to create Azure resources by hand. It walks you through a few choices, then shows the full deployment plan. Nothing is created until you approve it.

After you approve, the script creates the Microsoft Entra application, deploys and secures the Azure resources, and applies your provider's configuration. Deployment usually takes a few minutes.

Costs

Run the setup script

  1. Sign in to the Azure portal and select the Cloud Shell icon (>_) in the top toolbar. You can also go directly to https://shell.azure.com.

  2. Select PowerShell. If Cloud Shell opens in Bash, select Switch to PowerShell in the toolbar.

  3. If this is your first time, select No storage account required, choose your subscription, and then select Apply.

  4. Download and review the setup script:

    Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/Azure-Samples/ExternalPhoneProvider-AzureFunction-Sample/main/setup/Setup-Epp.ps1' `
    -OutFile '.\Setup-Epp.ps1'

  5. Run the script.

    .\Setup-Epp.ps1

  6. Follow the prompts to select the customer tenant, hosting subscription, Azure region, telecom provider, runtime, and hosting plan, then approve the deployment plan.

  7. Save the deployment summary, including its tenant ID, endpoint URL, and Application (client) ID. You need these values to complete provider registration and configure your profile.

Step 3: Complete telecom provider registration

After deployment completes, return to your telecom provider's registration page to complete the provider setup.

  1. Provide the Application (client) ID from your Microsoft Entra application when requested by your telecom provider.
  2. Complete any additional registration steps required by the provider.
  3. In Microsoft Security Store, go to Management > My Solutions and confirm that the Subscription status is 'Subscribed' before continuing.

Step 4: Update the authentication method policy

Configure each channel with the endpoint URL and application client ID from the deployment summary. Start in evaluation mode, validate the integration, and then gradually move delivery to your telecom provider.

Read the current policy

Use Microsoft Graph Explorer to read and update the policy. Confirm that you're signed in to the tenant whose ID matches the Tenant ID in the deployment summary.

Use these request URLs for the corresponding channel:

ChannelRequest URL
SMShttps://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/Sms
Voicehttps://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/Voice
  1. Set the request method to GET and enter the corresponding channel's request URL.
  2. Open Modify permissions and consent to Policy.Read.AuthenticationMethod.
  3. Select Run query and save the complete JSON response as a record of the existing policy.
  4. Repeat for the other channel if you're configuring both SMS and voice.

Configure CYOT settings

Configure these properties:

Property Value
telecomProviderSettings.url Endpoint URL from the deployment summary.
telecomProviderSettings.appId Integration application client ID.
telecomProviderSettings.isEvaluationModeEnabled Set to true for evaluation mode or false to enable telecom provider delivery.
telecomProviderSettings.migrationPercentage Percentage of eligible authentication requests sampled during evaluation, or routed to your telecom provider when evaluation mode is disabled.
includeTargets Preserve the existing production configuration. These targets are shared with the existing SMS or voice authentication method policy.

Start in evaluation mode

Start in evaluation mode to validate the integration before moving authentication delivery to your telecom provider.

Use migrationPercentage to set the evaluation sampling percentage.

  1. Use the tested SMS or voice JSON example provided below in Request body.
  2. Replace the endpoint URL and application client ID with the values for your deployment.
  3. Set isEvaluationModeEnabled to true.
  4. For production tenants, preserve the existing includeTargets from your saved policy configuration. Do not replace existing production targeting for CYOT testing.
  5. Open Modify permissions, consent to Policy.ReadWrite.AuthenticationMethod, and send the PATCH request to the corresponding channel's URL.
  6. Read the policy again with GET and verify the endpoint URL, application client ID, evaluation-mode setting, migration percentage, and existing targets.
  7. Complete the evaluation-mode tests in step 5.

For SMS:

{
  "@odata.type": "#microsoft.graph.smsAuthenticationMethodConfiguration",
  "state": "enabled",
  "telecomProviderSettings": {
    "url": "<YOUR-ENDPOINT-URL>",
    "appId": "<YOUR-APPLICATION-CLIENT-ID>",
    "isEvaluationModeEnabled": false,
    "migrationPercentage": 100
  }
}

For Voice:

{
  "@odata.type": "#microsoft.graph.voiceAuthenticationMethodConfiguration",
  "state": "enabled",
  "includeTargets": [
    {
      "verificationMode": "voiceOneTimePasscode"
    }
  ],
  "telecomProviderSettings": {
    "url": "<YOUR-ENDPOINT-URL>",
    "appId": "<YOUR-APPLICATION-CLIENT-ID>",
    "isEvaluationModeEnabled": false,
    "migrationPercentage": 100
  }
}

Move to production mode

After evaluation succeeds:

  1. Set telecomProviderSettings.isEvaluationModeEnabled to false.
  2. Set telecomProviderSettings.migrationPercentage to your initial traffic percentage.
  3. Keep the existing production includeTargets unchanged.
  4. Submit the policy update.
  5. Read the configuration again and verify the endpoint URL, application client ID, evaluation mode, migration percentage, and targets.
  6. Test telecom provider delivery before increasing traffic.

Increase traffic gradually

  1. Keep isEvaluationModeEnabled set to false.
  2. Increase migrationPercentage in increments until you reach 100.
  3. Keep the endpoint URL, application client ID, and existing includeTargets unchanged while changing the migration percentage.
  4. Validate authentication and telecom provider delivery after each change.
  5. Increase the percentage after each stage validates successfully. To investigate an issue, hold at the current percentage and see Monitor and troubleshoot.

Step 5: Test the integration

Use a test user with a phone number registered for SMS or voice.

Test in Evaluation

  1. In an InPrivate browser session, sign in as the test user and complete an SMS or voice authentication.
  2. In the Azure portal, go to your Function App > SendOtp > Invocations and open the latest transaction. In Invocation details, confirm Evaluation request completed with HTTP 200.
  3. In the Microsoft Entra admin center, go to Monitoring & health > Audit logs and filter by Service: Azure MFA. Open the latest entry and confirm DeliveryMethod is CyotEvaluation.

Test provider delivery

After evaluation succeeds, set isEvaluationModeEnabled to false and configure your initial migrationPercentage.

  1. In a new InPrivate browser session, sign in as the test user. Confirm the SMS or voice code arrives and authentication completes.
  2. In the Azure portal, go to your Function App > Invocations and open the latest transaction. In Invocation details, confirm the request completed with HTTP 200.
  3. In the Microsoft Entra admin center, go to Audit logs and filter by Service: Azure MFA. Open the latest entry and confirm Delivery Method is Cyot.
  4. In your provider's portal, confirm the message was delivered.

At a partial percentage, only some requests route through your provider, so make a few attempts. If something doesn't look right, see Monitor and troubleshoot your own telephony provider.

Troubleshooting

To diagnose integration issues, use the troubleshooting guide to identify whether the issue is with the Microsoft Entra configuration, Azure Function, telecom provider, or authentication flow.

See Monitor and troubleshoot your own telephony provider for diagnostic steps, logs, common issues, and remediation guidance.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…