Phone authentication allows users to sign in to Firebase using their phone as the authenticator. An SMS message is sent to the user (using the provided phone number) containing a unique code. Once the code has been authorized, the user is able to sign into Firebase.
Phone numbers that end users provide for authentication will be sent and stored by Google to improve spam and abuse prevention across Google service, including to, but not limited to Firebase. Developers should ensure they have the appropriate end-user consent prior to using the Firebase Authentication phone number sign-in service.authentication
Firebase Phone Authentication is not supported in all countries. Please see their FAQs for more information.
Before starting with Phone Authentication, ensure you have followed these steps:
- Enable Phone as a Sign-In method in the Firebase console.
- Android: 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.
- iOS: In Xcode, enable push notifications for your project & ensure your APNs authentication key is configured with Firebase Cloud Messaging (FCM). To view an in-depth explanation of this step, view the Firebase iOS Phone Auth documentation.
- Web: Ensure that you have added your applications domain on the Firebase console, under OAuth redirect domains.
Note; Phone number sign-in is only available for use on real devices and the web. To test your authentication flow on device emulators, please see Testing.
FlutterFire provides two individual ways to sign a user in with their phone number. Native (e.g. Android & iOS) platforms provide different functionality to validating a phone number than the web, therefore two methods exist for each platform exclusively:
On native platforms, the user's phone number must be first verified and then the user can either sign-in or link their account with a
First you must prompt the user for their phone number. Once provided, call the
There are 4 separate callbacks that you must handle, each will determine how you update the application UI:
- verificationCompleted: Automatic handling of the SMS code on Android devices.
- verificationFailed: Handle failure events such as invalid phone numbers or whether the SMS quota has been exceeded.
- codeSent: Handle when a code has been sent to the device from Firebase, used to prompt users to enter the code.
- codeAutoRetrievalTimeout: Handle a timeout of when automatic SMS code handling fails.
This handler will only be called on Android devices which support automatic SMS code resolution.
When the SMS code is delivered to the device, Android will automatically verify the SMS code without
requiring the user to manually input the code. If this event occurs, a
PhoneAuthCredential is automatically provided which can be
used to sign-in with or link the user's phone number.
If Firebase returns an error, for example for an incorrect phone number or if the SMS quota for the project has exceeded,
FirebaseAuthException will be sent to this handler. In this case, you would prompt your user something went wrong depending on the error
When Firebase sends an SMS code to the device, this handler is triggered with a
Once triggered, it would be a good time to update your application UI to prompt the user to enter the SMS code they're expecting.
Once the SMS code has been entered, you can combine the verification ID with the SMS code to create a new
By default, Firebase will not re-send a new SMS message if it has been recently sent. You can however override this behaviour
by re-calling the
verifyPhoneNumber method with the resend token to the
If successful, the SMS message will be resent.
On Android devices which support automatic SMS code resolution, this handler will be called if the device has not automatically resolved an SMS message within a certain timeframe. Once the timeframe has passed, the device will no longer attempt to resolve any incoming messages.
By default, the device waits for 30 seconds however this can be customized with the
On web platforms, users can sign-in by confirming they have access to a phone by entering the SMS code sent to the provided phone number. For added security and spam prevention, users are requested to prove they are human by completing a Google reCAPTCHA widget. Once confirmed, the SMS code will be sent.
FlutterFire will manage the reCAPTCHA widget out of the box by default, however provides control over how it is displayed and configured if required.
To get started, call the
signInWithPhoneNumber method with the phone number.
Calling the method will first trigger the reCAPTCHA widget to display. The user must complete the
test before an SMS code is sent. Once complete, you can then sign the user in by providing the
SMS code to the
confirm method on the resolved
Like other sign-in flows, a successful sign-in will trigger any authentication state listeners you have subscribed throughout your application.
The reCAPTCHA widget is a fully managed flow which provides security to your web application.
The second argument of
signInWithPhoneNumber accepts an optional
RecaptchaVerifier instance which can be used
to manage the widget. By default, the widget will render as an invisible widget when the sign-in flow is triggered.
An "invisible" widget will appear as a full-page modal on-top of your application like demonstrated above.
It is however possible to display an inline widget which the user has to explicitly press to verify themselves.
To add an inline widget, specify a DOM element ID to the
container argument of the
The element must exist and be empty otherwise an error will be thrown.
container argument is provided, the widget will be rendered as "invisible".
You can optionally change the size and theme by customizing the
theme arguments as shown above.
It is also possible to listen to events, such as whether the reCAPTCHA has been completed by the user, whether the reCAPTCHA has expired or an error was thrown:
Firebase provides support for locally testing phone numbers:
- On the Firebase Console, select the "Phone" authentication provider and click on the "Phone numbers for testing" dropdown.
- Enter a new phone number (e.g.
+44 7444 555666) and a test code (e.g.
If providing a test phone number to either the
signInWithPhoneNumber methods, no SMS will actually be sent. You
can instead provide the test code directly to the
PhoneAuthProvider or with
signInWithPhoneNumbers confirmation result handler.