Microsoft Entra ID
Authentication

Tutorial Native Authentication Android Sms One Time Passcode Sign In

In brief

The tutorial for adding SMS one-time passcode MFA to Android apps with native authentication was deleted. It covered tenant SMS enablement, client MFA configuration, authentication context, and MFA challenge handling.

What Entra admins need to know

Administrators supporting this scenario should be aware that the documented implementation guidance is no longer available at this URL.

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

Documentation change

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

deleted file mode 100644

title: Add SMS one-time passcode MFA to an Android app using native authentication description: Learn how to add multifactor authentication (MFA) with SMS one-time passcodes to an Android app using Microsoft Entra native authentication.

manager: pmwongera

ms.service: identity-platform ms.subservice: external ms.topic: tutorial ms.date: 01/27/2026 ms.custom: #Customer intent: As a developer, I want to add SMS one-time passcode–based multi-factor authentication (MFA) to an Android app using native authentication, so I can require a second verification step during sign-in and strengthen app security.

Tutorial: Add SMS one-time passcode MFA to your Android app

This tutorial shows you how to add multifactor authentication (MFA) with SMS one-time passcode (OTP) to your Android app using native authentication. MFA adds an extra layer of security by requiring a second verification step during sign-in. We'll also demonstrate how to enhance security during authentication and enforce MFA by using authentication context.

In this tutorial, you learn how to:

  • Sign in a user with SMS one-time passcode MFA
  • Specify an authentication context during sign-in to enforce MFA
  • Handle sign-in with SMS one-time passcode MFA errors

Prerequisites

  1. Complete the steps in Tutorial: Add sign-in and sign-out in Android app by using native authentication.

  2. Enable SMS as an MFA method in your tenant: follow the steps in Enable SMS as an MFA method.

  3. If you'd like to explore our Sign-in with MFA using SMS implementation, take a look at our Code sample before getting started.

Add MFA capabilities to the client configuration file

To support MFA, update the Android client configuration to include the required MFA capabilities.

{
    "client_id": "Enter_the_Application_Id_Here",
    "authorities": [
    {
        "type": "CIAM",
        "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Id_Here/"
    }
    ],
    "challenge_types": ["oob", "password"],
    "capabilities": ["mfa_required"],
    "logging": {
    "pii_enabled": false,
    "log_level": "INFO",
    "logcat_enabled": true
    }
}

Sign in a user with SMS one-time passcode MFA

To sign in a user with SMS one-time passcode multifactor authentication (MFA), after collecting first factor, you need to send an SMS containing a one-time passcode for the user to verify their phone number. When the user enters a valid one-time passcode, the app signs them in.

To sign in a user with SMS one-time passcode MFA, you need to:

  1. Create a user interface (UI) to:

    • Advise the user that MFA is required to sign in (optional).
    • Collect an SMS one-time passcode from the user to fulfill second authenticator factor.
    • Resend one-time passcode (recommended).
  2. Handle MFARequired sign in result:

    is SignInResult.MFARequired -> {
        // Handle "mfa required" result
        val awaitingMFAState = actionResult.nextState
    
        // Select the authentication method from authMethods, either programmatically or through the UI, and assign it to authMethod.
        val authMethod = actionResult.authMethods.first {it.challengeChannel.uppercase() == "SMS"}
        val requestChallengeResult = awaitingMFAState.requestChallenge(authMethod)
    
        // Handle "mfa verification required" result
        if (requestChallengeResult is MFARequiredResult.VerificationRequired) {
            // Next Step: submitChallenge using nextState
        } else {
            // Handle unexpected result as well as errors
        }
    }
    

    When signing in, if MFA is necessary, the system returns SignInResult.MFARequired. At this point, you can advise the user that MFA is required to proceed with the authentication, or you can call the requestChallenge(authMethod) method to send the one-time passcode. In most common scenario requestChallenge(authMethod), returns a result MFARequiredResult.VerificationRequired, which indicates that the SDK expects the app to submit SMS one-time passcode sent to the user's phone.

  3. Handle submitChallenge() result:

    val mfaRequiredState = requestChallengeResult.nextState
    val submitChallengeResult = mfaRequiredState.submitChallenge(code)
    
    when (submitChallengeResult) {
        is SignInResult.Complete -> {
            // Handle sign in success
        }
        is SubmitChallengeError -> {
            // Handle "mfa submit challenge" error
        }
        else -> {
            // Handle unexpected result
        }
    }
    

    The MFARequiredResult.VerificationRequired object contains a new state reference, which you can retrieve through requestChallengeResult.nextState. The new state gives you access to the submitChallenge() method that you can use to submit the MFA challenge. In most common scenario, the submitChallenge() returns a result, SignInResult.Complete, which indicates that the user has been authenticated successfully.

Use authentication context during sign-in

To learn how to use authentication context during sign-in, see authentication context during sign-in is how you can use authentication context during sign-in.

Handle sign-in with SMS one-time passcode MFA errors

To handle errors that occur during MFA, implement error handling logic for both the challenge request and challenge submission:

  1. Handle errors in the requestChallenge method:

    if (requestChallengeResult is MFARequiredResult.Error) {
        if (requestChallengeResult.isBrowserRequired()) {
            showResultText("Browser is required")
        } else {
            showResultText("Unexpected error while requesting challenge: ${requestChallengeResult.errorMessage}")
        }
    }
    
  2. Handle errors in the submitChallenge method:

    if (result is SignInError) {
        if (result.isInvalidChallenge()) {
            // Inform the user that the submitted code was incorrect and ask for a new code
            // Optionally, allow resubmission using newState.submitChallenge(newCode, authMethod)
        } else {
            showResultText("Unexpected error occurred: ${result.errorMessage}")
        }
    }
    

Next steps

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…