Telefonauthentifizierung

Bei der Telefonauthentifizierung können sich Nutzer mit ihrem Telefon als Authentifikator bei Firebase anmelden. Eine SMS mit einem eindeutigen Code wird an den Nutzer gesendet (an die angegebene Telefonnummer). Sobald der Code autorisiert wurde, kann sich der Nutzer in Firebase anmelden.

Telefonnummern, die Endnutzer zur Authentifizierung angeben, werden von Google gesendet und gespeichert, um Spam und Missbrauch in Google-Diensten zu verhindern, einschließlich, aber nicht beschränkt auf Firebase. Entwickler sollten sich die entsprechende Endnutzereinwilligung einholen, bevor sie den auf Telefonnummern basierenden Anmeldungsdienst von Firebase Authentication nutzen.

Die Firebase-Telefonauthentifizierung wird nicht in allen Ländern unterstützt. Weitere Informationen finden Sie in den FAQs des jeweiligen Anbieters.

Einrichtung

Bevor Sie mit der Telefonauthentifizierung beginnen, müssen Sie die folgenden Schritte ausführen:

  1. Aktivieren Sie „Telefon“ als Anmeldemethode in der Firebase Console.
  2. Android: Wenn Sie den SHA-1-Hash Ihrer App noch nicht in der Firebase Console festgelegt haben, holen Sie das nach. Informationen zum Ermitteln des SHA-1-Hashs Ihrer App finden Sie unter Client authentifizieren.
  3. iOS: Aktivieren Sie Push-Benachrichtigungen für Ihr Projekt in Xcode und sorgen Sie dafür, dass Ihr APNs-Authentifizierungsschlüssel mit Firebase Cloud Messaging (FCM) konfiguriert ist. Außerdem müssen Sie Hintergrundmodi für Remote-Benachrichtigungen aktivieren. Eine ausführliche Beschreibung dieses Schritts finden Sie in der Dokumentation zur Firebase-Telefonauthentifizierung für iOS.
  4. Web: Achten Sie darauf, dass Sie die Domain Ihrer Anwendung in der Firebase Console unter OAuth-Weiterleitungsdomains hinzugefügt haben.

Hinweis: Die Anmeldung mit der Telefonnummer ist nur auf echten Geräten und im Web verfügbar. Informationen zum Testen des Authentifizierungsablaufs auf Geräteemulatoren finden Sie unter Testen.

Nutzung

Das Firebase Authentication SDK für Flutter bietet zwei Möglichkeiten, einen Nutzer mit seiner Telefonnummer anzumelden. Native Plattformen (z. B. Android und iOS) bieten andere Funktionen zum Validieren einer Telefonnummer als das Web. Daher gibt es für jede Plattform zwei exklusive Methoden:

  • Native Plattform: verifyPhoneNumber.
  • Webplattform: signInWithPhoneNumber.

Nativ: verifyPhoneNumber

Auf nativen Plattformen muss die Telefonnummer des Nutzers zuerst bestätigt werden. Anschließend kann sich der Nutzer entweder anmelden oder sein Konto mit einem PhoneAuthCredential verknüpfen.

Zuerst müssen Sie den Nutzer nach seiner Telefonnummer fragen. Rufen Sie nach der Bereitstellung die Methode verifyPhoneNumber() auf:

await FirebaseAuth.instance.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationCompleted: (PhoneAuthCredential credential) {},
  verificationFailed: (FirebaseAuthException e) {},
  codeSent: (String verificationId, int? resendToken) {},
  codeAutoRetrievalTimeout: (String verificationId) {},
);

Es gibt vier separate Callbacks, die Sie verarbeiten müssen. Jeder bestimmt, wie Sie die Anwendungs-UI aktualisieren:

  1. verificationCompleted: Automatische Verarbeitung des SMS-Codes auf Android-Geräten.
  2. verificationFailed: Behandeln Sie Fehlerereignisse wie ungültige Telefonnummern oder das Überschreiten des SMS-Kontingents.
  3. codeSent: Wird ausgelöst, wenn ein Code von Firebase an das Gerät gesendet wurde. Nutzer werden aufgefordert, den Code einzugeben.
  4. codeAutoRetrievalTimeout: Behandeln Sie ein Zeitlimit, wenn die automatische Verarbeitung von SMS-Codes fehlschlägt.

verificationCompleted

Dieser Handler wird nur auf Android-Geräten aufgerufen, die die automatische Auflösung von SMS-Codes unterstützen.

Wenn der SMS-Code auf dem Gerät eingeht, wird er von Android automatisch bestätigt, ohne dass der Nutzer ihn manuell eingeben muss. Wenn dieses Ereignis eintritt, wird automatisch ein PhoneAuthCredential bereitgestellt, mit dem sich der Nutzer anmelden oder die Telefonnummer des Nutzers verknüpfen kann.

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationCompleted: (PhoneAuthCredential credential) async {
    // ANDROID ONLY!

    // Sign the user in (or link) with the auto-generated credential
    await auth.signInWithCredential(credential);
  },
);

verificationFailed

Wenn Firebase einen Fehler zurückgibt, z. B. bei einer falschen Telefonnummer oder wenn das SMS-Kontingent für das Projekt überschritten wurde, wird ein FirebaseAuthException an diesen Handler gesendet. In diesem Fall würden Sie den Nutzer je nach Fehlercode darüber informieren, dass etwas schiefgelaufen ist.

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  verificationFailed: (FirebaseAuthException e) {
    if (e.code == 'invalid-phone-number') {
      print('The provided phone number is not valid.');
    }

    // Handle other errors
  },
);

codeSent

Wenn Firebase einen SMS-Code an das Gerät sendet, wird dieser Handler mit einem verificationId und einem resendToken ausgelöst. Ein resendToken wird nur auf Android-Geräten unterstützt. Auf iOS-Geräten wird immer ein null-Wert zurückgegeben.

Nachdem der Vorgang ausgelöst wurde, sollten Sie die Benutzeroberfläche Ihrer Anwendung aktualisieren, um den Nutzer aufzufordern, den erwarteten SMS-Code einzugeben. Nachdem der SMS-Code eingegeben wurde, können Sie die Bestätigungs-ID mit dem SMS-Code kombinieren, um eine neue PhoneAuthCredential zu erstellen:

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  codeSent: (String verificationId, int? resendToken) async {
    // Update the UI - wait for the user to enter the SMS code
    String smsCode = 'xxxx';

    // Create a PhoneAuthCredential with the code
    PhoneAuthCredential credential = PhoneAuthProvider.credential(verificationId: verificationId, smsCode: smsCode);

    // Sign the user in (or link) with the credential
    await auth.signInWithCredential(credential);
  },
);

Standardmäßig sendet Firebase keine neue SMS, wenn vor Kurzem eine SMS gesendet wurde. Sie können dieses Verhalten jedoch überschreiben, indem Sie die verifyPhoneNumber-Methode mit dem Resend-Token für das forceResendingToken-Argument noch einmal aufrufen. Bei Erfolg wird die SMS noch einmal gesendet.

codeAutoRetrievalTimeout

Auf Android-Geräten, die die automatische Auflösung von SMS-Codes unterstützen, wird dieser Handler aufgerufen, wenn das Gerät eine SMS-Nachricht nicht innerhalb eines bestimmten Zeitrahmens automatisch aufgelöst hat. Nach Ablauf des Zeitraums versucht das Gerät nicht mehr, eingehende Nachrichten zu verarbeiten.

Standardmäßig wartet das Gerät 30 Sekunden. Dies kann jedoch mit dem Argument timeout angepasst werden:

FirebaseAuth auth = FirebaseAuth.instance;

await auth.verifyPhoneNumber(
  phoneNumber: '+44 7123 123 456',
  timeout: const Duration(seconds: 60),
  codeAutoRetrievalTimeout: (String verificationId) {
    // Auto-resolution timed out...
  },
);

Web: signInWithPhoneNumber

Auf Webplattformen können sich Nutzer anmelden, indem sie bestätigen, dass sie Zugriff auf ein Telefon haben. Dazu geben sie den SMS-Code ein, der an die angegebene Telefonnummer gesendet wurde. Zur Erhöhung der Sicherheit und zur Vermeidung von Spam werden Nutzer aufgefordert, über ein Google reCAPTCHA-Widget nachzuweisen, dass sie Menschen sind. Nach der Bestätigung wird der SMS-Code gesendet.

Das Firebase Authentication SDK for Flutter verwaltet das reCAPTCHA-Widget standardmäßig. Bei Bedarf können Sie jedoch festlegen, wie es angezeigt und konfiguriert wird. Rufen Sie dazu die Methode signInWithPhoneNumber mit der Telefonnummer auf.

FirebaseAuth auth = FirebaseAuth.instance;

// Wait for the user to complete the reCAPTCHA & for an SMS code to be sent.
ConfirmationResult confirmationResult = await auth.signInWithPhoneNumber('+44 7123 123 456');

Beim Aufrufen der Methode wird zuerst das reCAPTCHA-Widget angezeigt. Der Nutzer muss den Test abschließen, bevor ein SMS-Code gesendet wird. Anschließend können Sie den Nutzer anmelden, indem Sie den SMS-Code für die confirm-Methode in der aufgelösten ConfirmationResult-Antwort angeben:

UserCredential userCredential = await confirmationResult.confirm('123456');

Wie bei anderen Anmeldevorgängen werden bei einer erfolgreichen Anmeldung alle Listener für den Authentifizierungsstatus ausgelöst, die Sie in Ihrer Anwendung abonniert haben.

reCAPTCHA-Konfiguration

Das reCAPTCHA-Widget ist ein vollständig verwalteter Ablauf, der die Sicherheit Ihrer Webanwendung erhöht.

Das zweite Argument von signInWithPhoneNumber akzeptiert eine optionale RecaptchaVerifier-Instanz, mit der das Widget verwaltet werden kann. Standardmäßig wird das Widget als unsichtbares Widget gerendert, wenn der Anmeldevorgang ausgelöst wird. Ein „unsichtbares“ Widget wird als ganzseitiges Modal über Ihrer Anwendung angezeigt.

Es ist jedoch möglich, ein Inline-Widget einzublenden, auf das der Nutzer explizit tippen muss, um sich zu bestätigen.

Wenn Sie ein Inline-Widget hinzufügen möchten, geben Sie eine DOM-Element-ID für das container-Argument der RecaptchaVerifier-Instanz an. Das Element muss vorhanden und leer sein. Andernfalls wird ein Fehler ausgegeben. Wenn kein container-Argument angegeben wird, wird das Widget als „unsichtbar“ gerendert.

ConfirmationResult confirmationResult = await auth.signInWithPhoneNumber('+44 7123 123 456', RecaptchaVerifier(
  container: 'recaptcha',
  size: RecaptchaVerifierSize.compact,
  theme: RecaptchaVerifierTheme.dark,
));

Optional können Sie die Größe und das Design ändern, indem Sie die Argumente size und theme wie oben gezeigt anpassen.

Sie können auch auf Ereignisse warten, z. B. ob das reCAPTCHA vom Nutzer abgeschlossen wurde, ob das reCAPTCHA abgelaufen ist oder ob ein Fehler aufgetreten ist:

RecaptchaVerifier(
  onSuccess: () => print('reCAPTCHA Completed!'),
  onError: (FirebaseAuthException error) => print(error),
  onExpired: () => print('reCAPTCHA Expired!'),
);

Test

Firebase bietet Unterstützung für das lokale Testen von Telefonnummern:

  1. Wählen Sie in der Firebase Console den Authentifizierungsanbieter „Telefon“ aus und klicken Sie auf das Drop-down-Menü „Telefonnummern für Tests“.
  2. Geben Sie eine neue Telefonnummer (z.B. +44 7444 555666) und einen Testcode (z.B. 123456) ein.

Wenn Sie für die Methoden verifyPhoneNumber oder signInWithPhoneNumber eine Test-Telefonnummer angeben, werden keine SMS gesendet. Stattdessen können Sie den Testcode direkt an PhoneAuthProvider oder mit dem Bestätigungsergebnishandler von signInWithPhoneNumber senden.