Implement Phone Number Authentication with Firebase Auth in Flutter

📅

loading..🐩🐩🐩🐩

Before We Begin 🔗

This guide uses firebase_auth ^5.5.0.

It assumes you've created a project in the Firebase console↗ and registered your app. If you haven't registered it yet, follow the app registration guide.

Several services support phone verification, including Naver Cloud Console, Kakao AlimTalk, and NICE. This guide shows how to implement it in Flutter with

Firebase Auth

1. Configure Firebase Auth 🔗

In the Firebase console, go to Build > Authentication and click Get started.

Getting started with Authentication

Enable Phone in the sign-in method settings. If you use an emulator, add a fictional test phone number and verification code. I added +1 1234567812 and 123654.

Enabling phone authentication

Phone authentication enabled

2. Add SHA Certificate Fingerprints for Android 🔗

2.1. Get the Fingerprints 🔗

To use Firebase Auth in the Android app, add its signing certificate fingerprints. Run the relevant command below to find them. If prompted for the default password, enter android.

MAC/Linux

keytool -list -v \
-alias androiddebugkey -keystore ~/.android/debug.keystore

Windows

keytool -list -v \
-alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore

Successful output looks like this.

Finding the SHA certificate fingerprints

2.2. Register the Fingerprints 🔗

Open the settings for your registered Android app in the Firebase console.

Android app settings

Under Your apps on the General tab, click Add fingerprint.

Adding a fingerprint

Add the SHA-1 and SHA-256 fingerprints separately.

3. Write the Flutter Code 🔗

My directory structure looks like this. main.dart opens page_onboarding.dart.

📦lib
┣ 📜main.dart
┣ 📜page_onboarding.dart

3.1. Add the Firebase Auth Plugin 🔗

Run this command from the project root to add the plugin.

flutter pub add firebase_auth

3.2. Write page_onboarding.dart 🔗

Add the following code to page_onboarding.dart, using the test phone number you added in section 1.

/lib/page_onboarding.dart

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';
 
class PageOnboarding extends StatelessWidget {
  const PageOnboarding({super.key});
 
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextButton(
                onPressed: () async {
                  await FirebaseAuth.instance.verifyPhoneNumber(
                    phoneNumber: '+1 1234567812', // 테스트 번호
                    verificationCompleted: (PhoneAuthCredential credential) {
                      print("credential: $credential");
                    },
                    verificationFailed: (FirebaseAuthException e) {
                      print("verificationFailed: $e");
                    },
                    codeSent: (String verificationId, int? resendToken) {
                      print("codeSent: $verificationId");
                      print("codeSent: $resendToken");
                    },
                    codeAutoRetrievalTimeout: (String verificationId) {
                      print("codeAutoRetrievalTimeout: $verificationId");
                    },
                  );
                },
                child: const Text("Phone Number Verification"))
          ],
        ),
      ),
    );
  }
}

Tap the text, complete the CAPTCHA, and check for the verification success message in the logs. If you see the error below, see Error When Requesting Verification.

Fatal error: Please register custom URL scheme app-1-****** in the app's Info.plist file.

4. Understand the verifyPhoneNumber Callbacks 🔗

4.1. verificationCompleted 🔗

This callback handles automatic SMS code verification on Android devices.

verificationCompleted: (PhoneAuthCredential credential) {
  print("credential: $credential");
	await auth.signInWithCredential(credential); // 자동 인증 과정 진행
},

4.2. verificationFailed 🔗

This callback handles failures such as an invalid phone number or an exceeded SMS quota.

verificationFailed: (FirebaseAuthException e) {
	if (e.code == 'invalid-phone-number') {
		print('The provided phone number is not valid.');
	} else {
		print("verificationFailed: $e");
	}
},

4.3. codeSent 🔗

This runs when Firebase sends the code to the device. Use it to prompt the user to enter the code.

codeSent: (String verificationId, int? resendToken) {
  print("codeSent: $verificationId");
  print("codeSent: $resendToken");
},

4.4. codeAutoRetrievalTimeout 🔗

This runs if automatic SMS code retrieval times out.

codeAutoRetrievalTimeout: (String verificationId) {
  print("codeAutoRetrievalTimeout: $verificationId");
},

5. Finish Verification 🔗

After the user enters the SMS code, use the following code to complete verification. Use the verificationId received from 4.3. codeSent. See the complete example below.

/lib/page_onboarding.dart

TextButton(
	onPressed: () async {
		PhoneAuthCredential credential =
				PhoneAuthProvider.credential(
						verificationId: verificationId,
						smsCode: "123654",
						);
		await FirebaseAuth.instance
				.signInWithCredential(credential)
				.then((value) {
				print("signInWithCredential: $value");
		}).catchError((error) {
			print("signInWithCredential: $error");
		});
	},
	child: const Text("Sign In"),
),

Troubleshooting 🔗

Build Error: CocoaPods Version Conflict 🔗

Firebase/CoreOnly (= 11.8.0)
2
 
    You have either:
     * out-of-date source repos which you can update with pod repo update or with pod install --repo-update.
     * changed the constraints of dependency Firebase/CoreOnly inside your development pod firebase_core.
       You should run pod update Firebase/CoreOnly to apply changes you've made.
 
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:317:in raise_error_unless_state'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:299:in block in unwind_for_conflict'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:297:in tap'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:297:in unwind_for_conflict'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:257:in process_topmost_state'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolution.rb:182:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/molinillo-0.8.0/lib/molinillo/resolver.rb:43:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/resolver.rb:94:in resolve'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:1082:in block in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/user_interface.rb:64:in section'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:1080:in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer/analyzer.rb:125:in analyze'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:422:in analyze'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:244:in block in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/user_interface.rb:64:in section'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:243:in resolve_dependencies'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/installer.rb:162:in install!'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/command/install.rb:52:in run'
    /Library/Ruby/Gems/2.6.0/gems/claide-1.1.0/lib/claide/command.rb:334:in run'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/lib/cocoapods/command.rb:52:in run'
    /Library/Ruby/Gems/2.6.0/gems/cocoapods-1.16.2/bin/pod:55:in <top (required)>'
    /usr/local/bin/pod:23:in load'
    /usr/local/bin/pod:23:in `<main>'
 
Error output from CocoaPods:
↳
 
    [!] Automatically assigning platform iOS with version 13.0 on target Runner because no platform was specified. Please specify a platform for this target in your Podfile. See https://guides.cocoapods.org/syntax/podfile.html#platform.
 
Error: CocoaPods's specs repository is too out-of-date to satisfy dependencies.
To update the CocoaPods specs, run:
  pod repo update
 
Error running pod install
Error launching application on iPhone 16 Pro Max.

Fix 🔗

The CocoaPods repository may be out of date. Update it and reinstall the dependencies.

pod repo update
pod install --repo-update

Build Error: Firebase Version Conflict 🔗

Podfile.lock pins Firebase/CoreOnly to 11.6.0, while the firebase_core plugin requires 11.8.0.

!] CocoaPods could not find compatible versions for pod "Firebase/CoreOnly":
  In snapshot (Podfile.lock):
    Firebase/CoreOnly (= 11.6.0)
 
  In Podfile:
    firebase_core (from .symlinks/plugins/firebase_core/ios) was resolved to 3.12.0, which depends on
      Firebase/CoreOnly (= 11.8.0)
 
You have either:
 * changed the constraints of dependency Firebase/CoreOnly inside your development pod firebase_core.
   You should run pod update Firebase/CoreOnly to apply changes you've made.

Fix 🔗

Delete Podfile.lock and reinstall the pods.

rm ios/Podfile.lock
pod install --repo-update

Error When Requesting Verification 🔗

On iOS, you may see this error when the app opens a browser for reCAPTCHA and the return URL scheme hasn't been registered.

Fatal error: Please register custom URL scheme app-1-****** in the app's Info.plist file.

Fix 🔗

Add the URL scheme to Info.plist as shown below.

/ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>app-1-******</string>
        </array>
    </dict>
</array>

Conclusion 🔗

Complete Code 🔗

Show the complete code

/lib/page_onboarding.dart

import 'package:firebase_auth/firebase_auth.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
 
class PageOnboarding extends StatefulWidget {
  const PageOnboarding({super.key});
 
  @override
  State<PageOnboarding> createState() => _PageOnboardingState();
}
 
class _PageOnboardingState extends State<PageOnboarding> {
  String verificationId = '';
 
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            TextButton(
              onPressed: () async {
                await FirebaseAuth.instance.verifyPhoneNumber(
                  phoneNumber: '+1 1234567812', // 테스트 번호
                  timeout: const Duration(seconds: 60),
                  verificationCompleted: (PhoneAuthCredential credential) {
										print("verificationCompleted: $credential");
                  },
                  verificationFailed: (FirebaseAuthException e) {
										print("verificationFailed: $e");
                  },
                  codeSent: (String verificationId, int? resendToken) {
                    this.verificationId = verificationId;
										print("codeSent: $verificationId");
										print("codeSent: $resendToken");
                  },
                  codeAutoRetrievalTimeout: (String verificationId) {
										print("codeAutoRetrievalTimeout: $verificationId");
                  },
                );
              },
              child: const Text("Phone Number Verification"),
            ),
            const SizedBox(height: 20),
            SizedBox(
              width: 200,
              child: TextField( 	// 인증 코드 입력 (123654)
                onChanged: (value) {
                  setState(() {
                    smsCode = value;
                  });
                },
              ),
            ),
            TextButton(
              onPressed: () async {
                PhoneAuthCredential credential = PhoneAuthProvider.credential(
                    verificationId: verificationId, smsCode: smsCode);
                await FirebaseAuth.instance
                    .signInWithCredential(credential)
											.then((value) {
										print("signInWithCredential: $value");
                }).catchError((error) {
										print("signInWithCredential: $error");
                });
              },
              child: const Text("Sign In"),
            ),
          ],
        ),
      ),
    );
  }
}

Further Considerations 🔗

Build a separate screen for entering the SMS verification code.
Show users whether the code was sent and how much time they have left.
Under what conditions can Firebase verify the request without a reCAPTCHA challenge?

References 🔗

Implement Phone Number Authentication with Firebase Auth in Flutter | PromleeBlog