Telefonauthentifizierung

Mit der Telefonauthentifizierung können sich Nutzer mit ihrem Smartphone als Authenticator in Firebase anmelden. An den Nutzer wird eine SMS mit einem eindeutigen Code gesendet. 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 allen Google-Diensten zu verhindern, einschließlich Firebase. Entwickler müssen die Einwilligung der Endnutzer einholen, bevor sie den Anmeldedienst per Telefonnummer von Firebase Authentication verwenden.

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

Einrichtung

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

  1. Aktivieren Sie in der Firebase Console „Smartphone“ als Anmeldemethode.
  2. Android: Wenn Sie den SHA-1-Hash Ihrer App noch nicht in der Firebase Console festgelegt haben, tun Sie dies jetzt. Informationen zum Abrufen des SHA-1-Hashes Ihrer App finden Sie unter Client authentifizieren.
  3. iOS: Aktivieren Sie in Xcode die Push-Benachrichtigungen für Ihr Projekt und achten Sie darauf, 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 Erklärung zu diesem Schritt findest du in der Firebase iOS Phone Auth-Dokumentation.
  4. Web: Achten Sie darauf, dass Sie die Domain Ihrer Anwendung in der Firebase Console unter OAuth-Weiterleitungsdomains hinzugefügt haben.

Hinweis: Die Anmeldung per 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, Nutzer mit ihrer 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 Methoden:

  • Native Plattform: verifyPhoneNumber.
  • Webplattform: signInWithPhoneNumber.

Natives Format: verifyPhoneNumber

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

Sie müssen den Nutzer zuerst nach seiner Telefonnummer fragen. Rufe 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 Benutzeroberfläche der Anwendung aktualisieren:

  1. verificationCompleted: Automatische Verarbeitung des SMS-Codes auf Android-Geräten.
  2. verificationFailed: Hiermit werden Fehlerereignisse wie ungültige Telefonnummern oder das Überschreiten des SMS-Kontingents verarbeitet.
  3. codeSent: Wird ausgelöst, wenn ein Code von Firebase an das Gerät gesendet wurde, um Nutzer zum Eingeben des Codes aufzufordern.
  4. codeAutoRetrievalTimeout: Damit wird ein Zeitlimit festgelegt, das auftritt, 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, wird er von Android automatisch bestätigt, ohne dass der Nutzer den Code manuell eingeben muss. Wenn dieses Ereignis eintritt, wird automatisch eine PhoneAuthCredential bereitgestellt, mit der sich der Nutzer mit seiner Telefonnummer anmelden oder sie 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. aufgrund einer falschen Telefonnummer oder wenn das SMS-Kontingent für das Projekt überschritten wurde, wird an diesen Handler eine FirebaseAuthException gesendet. In diesem Fall informieren Sie den Nutzer je nach Fehlercode darüber, dass ein Fehler aufgetreten 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 verificationId und resendToken ausgelöst. resendToken wird nur auf Android-Geräten unterstützt. Auf iOS-Geräten wird immer der Wert null zurückgegeben.

Nach dem Auslösen ist es an der Zeit, die Benutzeroberfläche Ihrer Anwendung so zu aktualisieren, dass der Nutzer aufgefordert wird, den erwarteten SMS-Code einzugeben. Nachdem Sie den SMS-Code eingegeben haben, 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, die vor Kurzem gesendet wurde. Sie können dieses Verhalten jedoch überschreiben, indem Sie die verifyPhoneNumber-Methode noch einmal mit dem Token zum erneuten Senden an das forceResendingToken-Argument aufrufen. Ist der Vorgang erfolgreich, 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 Zeitraums 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. Diese Zeit kann 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 Smartphone haben, indem sie den SMS-Code eingeben, der an die angegebene Telefonnummer gesendet wurde. Für zusätzliche Sicherheit und Spamprävention müssen Nutzer ihr Google reCAPTCHA-Widget ausfüllen, um zu bestätigen, dass sie Menschen sind. Nach der Bestätigung wird der SMS-Code gesendet.

Das Firebase Authentication SDK für Flutter verwaltet das reCAPTCHA-Widget standardmäßig. Sie können jedoch festlegen, wie es angezeigt und konfiguriert wird. Rufen Sie zuerst 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');

Wenn Sie die Methode aufrufen, wird zuerst das reCAPTCHA-Widget angezeigt. Der Nutzer muss den Test bestehen, bevor ein SMS-Code gesendet wird. Anschließend kannst du den Nutzer anmelden, indem du den SMS-Code in der confirm-Methode der ConfirmationResult-Antwort angibst:

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 für die Sicherheit Ihrer Webanwendung sorgt.

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 modaler Dialog auf voller Seite über Ihrer Anwendung angezeigt.

Es ist jedoch möglich, ein Inline-Widget anzuzeigen, das der Nutzer explizit drücken muss, um sich zu authentifizieren.

Wenn du ein Inline-Widget hinzufügen möchtest, gib dem container-Argument der RecaptchaVerifier-Instanz eine DOM-Element-ID 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.

Es ist auch möglich, Ereignisse zu überwachen, z. B. ob das reCAPTCHA vom Nutzer abgeschlossen wurde, ob das reCAPTCHA abgelaufen ist oder ein Fehler aufgetreten ist:

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 für die Methoden verifyPhoneNumber oder signInWithPhoneNumber eine Testtelefonnummer angeben, wird keine SMS gesendet. Sie können den Testcode stattdessen direkt an PhoneAuthProvider oder an den Bestätigungsergebnis-Handler von signInWithPhoneNumber senden.