Authenticate with Firebase on Android using a Phone Number

You can use Firebase Authentication to sign in a user by sending an SMS message to the user's phone. The user signs in using a one-time code contained in the SMS message.

The easiest way to add phone number sign-in to your app is to use FirebaseUI , which includes a drop-in sign-in widget that implements sign-in flows for phone number sign-in, as well as password-based and federated sign-in. This document describes how to implement a phone number sign-in flow using the Firebase SDK.

Before you begin

1. If you haven't already, add Firebase to your Android project .
2. In your module (app-level) Gradle file (usually <project>/<app-module>/build.gradle.kts or <project>/<app-module>/build.gradle ), add the dependency for the Firebase Authentication library for Android. We recommend using the Firebase Android BoM to control library versioning.

    dependencies 
     
    { 
     
     // Import the BoM 
   for the Firebase platform 
     
    implementation 
    ( 
    platform 
    ( 
    "com.google.firebase:firebase-bom:34.2.0" 
    )) 
     
     // Add the dependency for the Firebase Authentication 
   library 
     
    // When using the BoM 
   , you don't specify versions in Firebase library dependencies 
     
     implementation 
    ( 
    "com.google.firebase:firebase-auth" 
    ) 
    } 
   

   By using the Firebase Android BoM , your app will always use compatible versions of Firebase Android libraries.

   (Alternative)   Add Firebase library dependencies  without  using the BoM

   If you choose not to use the Firebase BoM , you must specify each Firebase library version in its dependency line.

   Note that if you use multiple Firebase libraries in your app, we strongly recommend using the BoM to manage library versions, which ensures that all versions are compatible.

    dependencies 
     
    { 
     
     // Add the dependency for the Firebase Authentication 
   library 
     
    // When NOT using the BoM 
   , you must specify versions in Firebase library dependencies 
     
     implementation 
    ( 
    "com.google.firebase:firebase-auth:24.0.1" 
    ) 
    } 
   

3. If you haven't yet connected your app to your Firebase project, do so from the Firebase console .
4. If you haven't already set your app's SHA-1 hash in the Firebase console , do so. See Authenticating Your Client for information about finding your app's SHA-1 hash.

Security concerns

Authentication using only a phone number, while convenient, is less secure than the other available methods, because possession of a phone number can be easily transferred between users. Also, on devices with multiple user profiles, any user that can receive SMS messages can sign in to an account using the device's phone number.

If you use phone number based sign-in in your app, you should offer it alongside more secure sign-in methods, and inform users of the security tradeoffs of using phone number sign-in.

Enable Phone Number sign-in for your Firebase project

To sign in users by SMS, you must first enable the Phone Number sign-in method for your Firebase project:

1. In the Firebase console , open the Authentication section.
2. On the Sign-in Method page, enable the Phone Number sign-in method.
3. Optional : On the Settings page, set a policy on the regions to which you want to allow or deny SMS messages to be sent. Setting an SMS region policy can help protect your apps from SMS abuse.

Enable app verification

To use phone number authentication, Firebase must be able to verify that phone number sign-in requests are coming from your app. There are three ways Firebase Authentication accomplishes this:

• Play Integrity API : If a user has a device with Google Play services installed, and Firebase Authentication can verify the device as legitimate with the Play Integrity API , phone number sign-in can proceed. The Play Integrity API is enabled on a Google-owned project by Firebase Authentication , not on your project. This does not contribute to any Play Integrity API quotas on your project. Play Integrity Support is available with the Authentication SDK v21.2.0+ ( Firebase BoM v31.4.0+).

  To use Play Integrity, if you haven't yet specified your app's SHA-256 fingerprint, do so from the Project settings of the Firebase console. Refer to Authenticating Your Client for details on how to get your app's SHA-256 fingerprint.

• reCAPTCHA verification : In the event that Play Integrity cannot be used, such as when a user has a device without Google Play services installed, Firebase Authentication uses a reCAPTCHA verification to complete the phone sign-in flow. The reCAPTCHA challenge can often be completed without the user having to solve anything. Note that this flow requires that a SHA-1 is associated with your application. This flow also requires your API Key to be unrestricted or allowlisted for PROJECT_ID .firebaseapp.com .

  Some scenarios where reCAPTCHA is triggered:

  • If the end-user's device does not have Google Play services installed.
  • If the app is not distributed through Google Play Store (on Authentication SDK v21.2.0+ ).
  • If the obtained SafetyNet token was not valid (on Authentication SDK versions < v21.2.0).

  When SafetyNet or Play Integrity is used for App verification, the %APP_NAME% field in the SMS template is populated with the app name determined from Google Play Store . In the scenarios where reCAPTCHA is triggered, %APP_NAME% is populated as PROJECT_ID .firebaseapp.com .

Troubleshooting

• "Missing initial state" error when using reCAPTCHA for app verification

  This can occur when the reCAPTCHA flow completes successfully but does not redirect the user back to the native application. If this occurs, the user is redirected to the fallback URL PROJECT_ID .firebaseapp.com/__/auth/handler . On Firefox browsers, opening native app links is disabled by default. If you see the above error on Firefox, follow the steps in Set Firefox for Android to open links in native apps to enable opening app links.

Send a verification code to the user's phone

To initiate phone number sign-in, present the user an interface that prompts them to type their phone number. Legal requirements vary, but as a best practice and to set expectations for your users, you should inform them that if they use phone sign-in, they might receive an SMS message for verification and standard rates apply.

Then, pass their phone number to the PhoneAuthProvider.verifyPhoneNumber method to request that Firebase verify the user's phone number. For example:

 val 
  
 options 
  
 = 
  
 PhoneAuthOptions 
 . 
 newBuilder 
 ( 
 auth 
 ) 
  
 . 
 setPhoneNumber 
 ( 
 phoneNumber 
 ) 
  
 // Phone number to verify 
  
 . 
 setTimeout 
 ( 
 60L 
 , 
  
 TimeUnit 
 . 
 SECONDS 
 ) 
  
 // Timeout and unit 
  
 . 
 setActivity 
 ( 
 this 
 ) 
  
 // Activity (for callback binding) 
  
 . 
 setCallbacks 
 ( 
 callbacks 
 ) 
  
 // OnVerificationStateChangedCallbacks 
  
 . 
 build 
 () 
 PhoneAuthProvider 
 . 
 verifyPhoneNumber 
 ( 
 options 
 ) 
 
  PhoneAuthActivity 
 . 
 kt 
 
 

 PhoneAuthOptions 
  
 options 
  
 = 
  
  
 PhoneAuthOptions 
 . 
 newBuilder 
 ( 
 mAuth 
 ) 
  
  
 . 
 setPhoneNumber 
 ( 
 phoneNumber 
 ) 
  
 // Phone number to verify 
  
 . 
 setTimeout 
 ( 
 60L 
 , 
  
 TimeUnit 
 . 
 SECONDS 
 ) 
  
 // Timeout and unit 
  
 . 
 setActivity 
 ( 
 this 
 ) 
  
 // (optional) Activity for callback binding 
  
 // If no activity is passed, reCAPTCHA verification can not be used. 
  
 . 
 setCallbacks 
 ( 
 mCallbacks 
 ) 
  
 // OnVerificationStateChangedCallbacks 
  
 . 
 build 
 (); 
  
 PhoneAuthProvider 
 . 
 verifyPhoneNumber 
 ( 
 options 
 ); 
  
 
  PhoneAuthActivity 
 . 
 java 
 
 

The verifyPhoneNumber method is reentrant: if you call it multiple times, such as in an activity's onStart method, the verifyPhoneNumber method will not send a second SMS unless the original request has timed out.

You can use this behavior to resume the phone number sign in process if your app closes before the user can sign in (for example, while the user is using their SMS app). After you call verifyPhoneNumber , set a flag that indicates verification is in progress. Then, save the flag in your Activity's onSaveInstanceState method and restore the flag in onRestoreInstanceState . Finally, in your Activity's onStart method, check if verification is already in progress, and if so, call verifyPhoneNumber again. Be sure to clear the flag when verification completes or fails (see Verification callbacks ).

To easily handle screen rotation and other instances of Activity restarts, pass your Activity to the verifyPhoneNumber method. The callbacks will be auto-detached when the Activity stops, so you can freely write UI transition code in the callback methods.

The SMS message sent by Firebase can also be localized by specifying the auth language via the setLanguageCode method on your Auth instance.

 auth 
 . 
 setLanguageCode 
 ( 
 "fr" 
 ) 
 // To apply the default app language instead of explicitly setting it. 
 // auth.useAppLanguage() 
 MainActivity.kt