Firebase Authentication Skill

This skill defines how to correctly use Firebase Authentication in Flutter applications.

When to Use

Use this skill when:

Setting up Firebase Authentication in a Flutter project.
Listening to authentication state changes.
Implementing email/password or social sign-in.
Managing user profiles, account linking, or MFA.
Handling authentication errors.
Applying security best practices for auth flows.

1. Setup and Configuration

flutter pub add firebase_auth

import 'package:firebase_auth/firebase_auth.dart';

Enable desired authentication providers in the Firebase console before using them.
Initialize Firebase before using any Firebase Authentication features.

Local emulator for testing:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  await FirebaseAuth.instance.useAuthEmulator('localhost', 9099);
  // ...
}

2. Authentication State Management

Use the appropriate stream based on what you need to observe:

Stream	Fires when
`authStateChanges()`	User signs in or out
`idTokenChanges()`	ID token changes (including custom claims)
`userChanges()`	User data changes (e.g., profile updates)

FirebaseAuth.instance
  .authStateChanges()
  .listen((User? user) {
    if (user == null) {
      print('User is currently signed out!');
    } else {
      print('User is signed in!');
    }
  });

Listen to these streams immediately when the app starts to handle the initial auth state.
Custom claims are only available after sign-in, re-authentication, token expiration, or manual token refresh.

3. Email and Password Authentication

Create a new account:

try {
  final credential = await FirebaseAuth.instance.createUserWithEmailAndPassword(
    email: emailAddress,
    password: password,
  );
} on FirebaseAuthException catch (e) {
  if (e.code == 'weak-password') {
    print('The password provided is too weak.');
  } else if (e.code == 'email-already-in-use') {
    print('The account already exists for that email.');
  }
} catch (e) {
  print(e);
}

Sign in:

try {
  final credential = await FirebaseAuth.instance.signInWithEmailAndPassword(
    email: emailAddress,
    password: password,
  );
} on FirebaseAuthException catch (e) {
  if (e.code == 'user-not-found') {
    print('No user found for that email.');
  } else if (e.code == 'wrong-password') {
    print('Wrong password provided for that user.');
  }
}

Verify the user's email address after account creation.
Firebase rate-limits new email/password sign-ups from the same IP to protect against abuse.
On iOS/macOS, authentication state persists between app re-installs via the system keychain.

4. Social Authentication

Google Sign-In (native platforms):

Future<UserCredential> signInWithGoogle() async {
  final GoogleSignInAccount? googleUser = await GoogleSignIn.instance.authenticate();
  final GoogleSignInAuthentication googleAuth = googleUser.authentication;
  final credential = GoogleAuthProvider.credential(idToken: googleAuth.idToken);
  return await FirebaseAuth.instance.signInWithCredential(credential);
}

Google Sign-In (web):

Future<UserCredential> signInWithGoogle() async {
  GoogleAuthProvider googleProvider = GoogleAuthProvider();
  googleProvider.addScope('https://www.googleapis.com/auth/contacts.readonly');
  googleProvider.setCustomParameters({'login_hint': 'user@example.com'});
  return await FirebaseAuth.instance.signInWithPopup(googleProvider);
}

Configure platform-specific settings for each provider (e.g., SHA1 key for Google Sign-In on Android).
If a user signs in with a social provider after registering with the same email manually, Firebase's trusted provider concept will automatically change their authentication provider.

5. Error Handling

Always use try-catch with FirebaseAuthException.
Check e.code to identify specific error types.
Handle account-exists-with-different-credential by fetching sign-in methods for the email and guiding users through the correct flow.
Handle too-many-requests with retry logic or user feedback.
Handle operation-not-allowed by ensuring the provider is enabled in the Firebase console.

6. User Management

// Update profile
await FirebaseAuth.instance.currentUser?.updateProfile(
  displayName: "Jane Q. User",
  photoURL: "https://example.com/jane-q-user/profile.jpg",
);

// Update email (sends verification to new address first)
await user?.verifyBeforeUpdateEmail("newemail@example.com");

Use verifyBeforeUpdateEmail() — not updateEmail() — to change a user's email. The email only updates after the user verifies it.
Store only essential info in the auth profile; use a database for additional user data.
Use linkWithCredential() to connect multiple auth providers to a single account.
Verify the user's identity before linking new credentials.
Use fetchSignInMethodsForEmail() when handling account linking.

7. Security Best Practices

Never store sensitive authentication credentials in client-side code.
Monitor auth state changes for proper session management.
Validate user input before submitting authentication requests to prevent injection attacks.
Call FirebaseAuth.instance.signOut() when users exit the app.
For sensitive operations, re-authenticate users with reauthenticateWithCredential().
Enforce strong password policies for email/password auth.
In Realtime Database and Cloud Storage Security Rules, use the auth variable to get the signed-in user's UID for access control.
Use multi-factor authentication for sensitive applications.

8. Multi-Factor Authentication

Security warning: Avoid SMS-based MFA. SMS is insecure and easy to compromise or spoof.

Platform limitation: Windows does not support MFA. MFA with multiple tenants is not supported on Flutter.

Enable at least one MFA-compatible provider before implementing MFA.

9. Email Link Authentication

Important: Firebase Dynamic Links is deprecated for email link authentication. Firebase Hosting is now used to send sign-in links.

Set handleCodeInApp: true in ActionCodeSettings — sign-in must always be completed in the app.
Store the user's email locally (e.g., SharedPreferences) when sending the sign-in link.
Never pass the user's email in redirect URL parameters — this enables session injection attacks.
Use HTTPS URLs in production to prevent link interception.
Configure the app to detect incoming links and parse the underlying deep link for sign-in completion.

firebase-auth