Telefonauthentifizierung

Mit der Telefonauthentifizierung können sich Nutzer mit ihrem Smartphone als Authentifikator in Firebase anmelden. Der Nutzer erhält eine SMS mit einem eindeutigen Code an die angegebene Telefonnummer. Nachdem der Code autorisiert wurde, kann sich der Nutzer in Firebase anmelden.

Die Telefonnummern, die Endnutzer für die Authentifizierung angeben, werden von Google gesendet und gespeichert, um Spam und Missbrauch in den Google-Diensten zu verhindern, einschließlich, aber nicht beschränkt auf Firebase. Entwickler müssen sicherstellen, dass sie die entsprechende Endnutzereinwilligung haben, bevor sie den auf Telefonnummern basierenden Anmeldungsdienst von Firebase Authentication nutzen.authentication

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

Einrichtung

Bevor Sie mit der Telefonauthentifizierung beginnen, führen Sie die folgenden Schritte aus:

  1. Rufen Sie in der Firebase Console Security > Authentication auf.

  2. Aktivieren Sie auf dem Tab Anmeldemethode den Anmeldeanbieter Telefon.

  3. Richten Sie plattformspezifische Anforderungen ein:

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 zur Bestätigung 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.

Fordern Sie den Nutzer zuerst auf, seine Telefonnummer anzugeben. Rufen Sie dann 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 UI der Anwendung aktualisieren:

  1. verificationCompleted: Automatische Verarbeitung des SMS-Codes auf Android-Geräten.
  2. verificationFailed: Verarbeiten Sie Fehlerereignisse wie ungültige Telefonnummern oder das Überschreiten des SMS-Kontingents.
  3. codeSent: Verarbeiten Sie den Fall, dass ein Code von Firebase an das Gerät gesendet wurde, um Nutzer aufzufordern, den Code einzugeben.
  4. codeAutoRetrievalTimeout: Verarbeiten Sie ein Zeitlimit, wenn die automatische Verarbeitung des 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 an das Gerät gesendet wird, bestätigt Android den SMS-Code automatisch, ohne dass der Nutzer ihn manuell eingeben muss. Wenn dieses Ereignis eintritt, wird automatisch ein PhoneAuthCredential bereitgestellt, mit dem sich der Nutzer anmelden oder seine Telefonnummer 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 eine FirebaseAuthException an diesen Handler gesendet. In diesem Fall fordern Sie den Nutzer je nach Fehlercode auf, etwas zu tun.

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 einer 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.

Nach dem Auslösen ist es ein guter Zeitpunkt, die UI Ihrer Anwendung zu aktualisieren, um den Nutzer aufzufordern, den erwarteten SMS-Code einzugeben. Sobald der SMS-Code eingegeben wurde, können Sie die Bestätigungs-ID mit dem SMS-Code kombinieren, um ein neues 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-Nachricht, wenn kürzlich eine gesendet wurde. Sie können dieses Verhalten jedoch überschreiben, indem Sie die Methode verifyPhoneNumber mit dem Token zum erneuten Senden für das Argument forceResendingToken noch einmal aufrufen. Bei Erfolg wird die SMS-Nachricht 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 Zeitraums automatisch auflösen konnte. Nach Ablauf des Zeitraums versucht das Gerät nicht mehr, eingehende Nachrichten aufzulösen.

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 müssen Nutzer nachweisen, dass sie Menschen sind, indem sie ein Google reCAPTCHA Widget ausfüllen. Nach der Bestätigung wird der SMS-Code gesendet.

Das Firebase Authentication SDK für Flutter verwaltet das reCAPTCHA-Widget standardmäßig sofort, bietet aber bei Bedarf die Möglichkeit, die Anzeige und Konfiguration zu steuern. 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');

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

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

Wie bei anderen Anmeldeabläufen 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 Anmeldeablauf ausgelöst wird. Ein „unsichtbares“ Widget wird als modales Fenster im Vollbildmodus über Ihrer Anwendung angezeigt.

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

Wenn Sie ein Inline-Widget hinzufügen möchten, geben Sie eine DOM-Element-ID für das Argument container 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,
));

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

Außerdem können Sie auf Ereignisse wie den Abschluss von reCAPTCHA durch den Nutzer, den Ablauf von reCAPTCHA oder das Auftreten eines Fehlers warten:

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

Test

Firebase unterstützt 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 eine Testtelefonnummer für die Methoden verifyPhoneNumber oder signInWithPhoneNumber angeben, wird keine SMS gesendet. Stattdessen können Sie den Testcode direkt für PhoneAuthProvider oder mit dem Handler für das Bestätigungsergebnis von signInWithPhoneNumber angeben.