Telefonnummern im Web mit der WebOTP API bestätigen

Nutzern mit per SMS empfangenen OTPs helfen

Eiji Kitamura
Eiji Kitamura

Was ist die WebOTP API?

Heutzutage haben die meisten Menschen weltweit ein Mobilgerät und Entwickler verwenden für gewöhnlich Telefonnummern als Kennung für die Nutzer ihrer Dienste.

Es gibt verschiedene Möglichkeiten, Telefonnummern zu bestätigen. Am häufigsten wird jedoch ein zufällig generiertes einmaliges Passwort (OTP) per SMS gesendet. Durch das Zurücksenden dieses Codes an den Server des Entwicklers demonstrieren Sie, dass Sie über die Telefonnummer gesteuert werden können.

Diese Idee wird bereits in vielen Szenarien eingesetzt, um Folgendes zu erreichen:

  • Telefonnummer als Kennung für den Nutzer. Bei der Registrierung für einen neuen Dienst fragen manche Websites nach einer Telefonnummer statt einer E-Mail-Adresse und verwenden diese als Kontokennung.
  • Bestätigung in zwei Schritten: Bei der Anmeldung fragt eine Website nach einem einmaligen Code, der zusätzlich zu einem Passwort oder einem anderen Wissensfaktor per SMS gesendet wird, um die Sicherheit zu erhöhen.
  • Zahlungsbestätigung: Wenn ein Nutzer eine Zahlung vornimmt, kann die Frage nach einem einmaligen Code, der per SMS gesendet wird, dabei helfen, die Absicht der Person zu überprüfen.

Der aktuelle Prozess sorgt für Reibungspunkte für die Nutzenden. Ein OTP in einer SMS zu finden, es dann kopieren und in das Formular einfügen, ist umständlich, wodurch die Conversion-Raten bei kritischen Kaufprozessen sinken. Viele der weltweit größten Entwicklerinnen und Entwickler weltweit wünschen sich diese Möglichkeit für das Web. Android hat eine API, die genau das tut. Dasselbe gilt für iOS und Safari.

Mit der WebOTP API kann Ihre Anwendung speziell formatierte Nachrichten empfangen, die an die Domain Ihrer Anwendung gebunden sind. So können Sie programmatisch ein OTP aus einer SMS abrufen und eine Telefonnummer für den Nutzer einfacher bestätigen.

Beispiele ansehen

Angenommen, ein Nutzer möchte seine Telefonnummer über eine Website bestätigen. Die Website sendet eine SMS an den Nutzer und der Nutzer gibt das OTP aus der Nachricht ein, um die Inhaberschaft der Telefonnummer zu bestätigen.

Mit der WebOTP API sind diese Schritte für den Nutzer so einfach wie ein Tippen, wie im Video gezeigt. Nach Eingang der SMS wird am unteren Rand ein Fenster geöffnet, in dem der Nutzer aufgefordert wird, seine Telefonnummer zu bestätigen. Nachdem Sie im unteren Tabellenblatt auf die Schaltfläche Bestätigen geklickt haben, fügt der Browser das OTP in das Formular ein. Das Formular wird gesendet, ohne dass der Nutzer auf Weiter klicken muss.

Der gesamte Prozess ist in der nachfolgenden Abbildung schematisch dargestellt.

WebOTP API-Diagramm

Probieren Sie die Demo selbst aus. Du wirst nicht nach deiner Telefonnummer gefragt oder es wird eine SMS an dein Gerät gesendet. Du kannst aber eine von einem anderen Gerät senden, indem du den in der Demo angezeigten Text kopierst. Dies funktioniert, da es bei der Verwendung der WebOTP API keine Rolle spielt, wer der Absender ist.

  1. Rufen Sie in Chrome 84 oder höher auf einem Android-Gerät https://web-otp.glitch.me auf.
  2. Senden Sie die folgende SMS von einem anderen Telefon an Ihr Telefon.
Your OTP is: 123456.

@web-otp.glitch.me #12345

Haben Sie die SMS erhalten und werden Sie aufgefordert, den Code im Eingabebereich einzugeben? So funktioniert die WebOTP API für Nutzer.

Die Verwendung der WebOTP API besteht aus drei Teilen:

  • Ein korrekt annotiertes <input>-Tag
  • JavaScript in Ihrer Webanwendung
  • Formatierter Nachrichtentext per SMS

Ich werde zuerst auf das <input>-Tag eingehen.

<input>-Tag annotieren

WebOTP selbst funktioniert ohne HTML-Annotationen. Aus Gründen der Kompatibilität mit anderen Browsern empfehlen wir jedoch, autocomplete="one-time-code" dort in das <input>-Tag einzufügen, wo der Nutzer voraussichtlich ein OTP eingibt.

Dadurch kann Safari 14 oder höher dem Nutzer vorschlagen, das Feld <input> automatisch mit einem OTP auszufüllen, wenn er eine SMS in dem unter SMS-Nachricht formatieren beschriebenen Format erhält, obwohl WebOTP nicht unterstützt wird.

HTML

<form>
  <input autocomplete="one-time-code" required/>
  <input type="submit">
</form>

WebOTP API verwenden

Da WebOTP einfach ist, reicht das Kopieren und Einfügen des folgenden Codes aus. Ich erkläre Ihnen trotzdem, was passiert.

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

Funktionserkennung

Die Funktionserkennung ist die gleiche wie bei vielen anderen APIs. Mit dem Warten auf das DOMContentLoaded-Ereignis wird gewartet, bis der DOM-Baum abfragen kann.

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    …
    const form = input.closest('form');
    …
  });
}

OTP verarbeiten

Die WebOTP API selbst ist einfach genug. Verwenden Sie navigator.credentials.get(), um das OTP abzurufen. WebOTP fügt dieser Methode die neue otp-Option hinzu. Es hat nur ein Attribut: transport, dessen Wert ein Array mit dem String 'sms' sein muss.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
    …

Dadurch wird der Berechtigungsablauf des Browsers ausgelöst, wenn eine SMS eingeht. Wenn die Berechtigung erteilt wird, wird das zurückgegebene Promise mit einem OTPCredential-Objekt aufgelöst.

Inhalt des abgerufenen OTPCredential-Objekts

{
  code: "123456" // Obtained OTP
  type: "otp"  // `type` is always "otp"
}

Übergeben Sie als Nächstes den OTP-Wert an das Feld <input>. Wenn der Nutzer das Formular direkt absendet, muss er nicht mehr auf eine Schaltfläche tippen.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.error(err);
    });
    …

Nachricht abbrechen

Falls der Nutzer manuell ein OTP eingibt und das Formular sendet, können Sie den get()-Aufruf mit einer AbortController-Instanz im options-Objekt abbrechen.

JavaScript

    …
    const ac = new AbortController();
    …
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    …
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
    …

SMS-Nachricht formatieren

Die API selbst sollte einfach genug aussehen, aber es gibt ein paar Dinge, die Sie wissen sollten, bevor Sie sie verwenden. Die Nachricht muss nach dem Aufruf von navigator.credentials.get() gesendet und auf dem Gerät empfangen werden, auf dem get() aufgerufen wurde. Schließlich muss die Nachricht folgende Formatierungen einhalten:

  • Die Nachricht beginnt mit einem (optionalen) lesbaren Text, der einen alphanumerischen String aus vier bis zehn Zeichen enthält, wobei die letzte Zeile für die URL und das OTP mindestens eine Zahl hinterlässt.
  • Dem Domainteil der URL der Website, auf der die API aufgerufen wurde, muss @ vorangestellt sein.
  • Die URL muss ein Rautezeichen („#“) enthalten, gefolgt vom OTP.

Beispiel:

Your OTP is: 123456.

@www.example.com #123456

Hier einige Beispiele für schlechte Werte:

Beispiel für fehlerhaften SMS-Text Warum das nicht funktioniert
Here is your code for @example.com #123456 @ muss das erste Zeichen der letzten Zeile sein.
Your code for @example.com is #123456 @ muss das erste Zeichen der letzten Zeile sein.
Your verification code is 123456

@example.com\t#123456
Zwischen @host und #code wird ein einzelnes Leerzeichen erwartet.
Your verification code is 123456

@example.com  #123456
Zwischen @host und #code wird ein einzelnes Leerzeichen erwartet.
Your verification code is 123456

@ftp://example.com #123456
URL-Schema kann nicht eingeschlossen werden.
Your verification code is 123456

@https://example.com #123456
URL-Schema kann nicht eingeschlossen werden.
Your verification code is 123456

@example.com:8080 #123456
Port kann nicht angegeben werden.
Your verification code is 123456

@example.com/foobar #123456
Pfad kann nicht angegeben werden.
Your verification code is 123456

@example .com #123456
Keine Leerzeichen in der Domain.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456
Keine unzulässigen Zeichen in der Domain.
@example.com #123456

Mambo Jumbo
@host und #code müssen die letzte Zeile sein.
@example.com #123456

App hash #oudf08lkjsdf834
@host und #code müssen die letzte Zeile sein.
Your verification code is 123456

@example.com 123456
#“ fehlt.
Your verification code is 123456

example.com #123456
@“ fehlt.
Hi mom, did you receive my last text @ und # fehlen.

Demos

Probieren Sie verschiedene Nachrichten mit der Demo aus: https://web-otp.glitch.me

Sie können den Fork auch verzweigen und Ihre Version erstellen: https://glitch.com/edit/#!/web-otp.

WebOTP aus einem ursprungsübergreifenden iFrame verwenden

Die Eingabe eines SMS-OTP in einen ursprungsübergreifenden iFrame wird normalerweise zur Zahlungsbestätigung verwendet, insbesondere bei 3D Secure. Dank des gemeinsamen Formats zur Unterstützung ursprungsübergreifender iFrames stellt die WebOTP API OTPs bereit, die an verschachtelte Ursprünge gebunden sind. Beispiel:

  • Ein Nutzer besucht shop.example, um mit einer Kreditkarte ein Paar Schuhe zu kaufen.
  • Nach der Eingabe der Kreditkartennummer zeigt der integrierte Zahlungsdienstleister ein Formular von bank.example in einem iFrame an, in dem der Nutzer aufgefordert wird, seine Telefonnummer zu bestätigen, um schnell bezahlen zu können.
  • bank.example sendet eine SMS mit einem OTP an den Nutzer, das er zur Identitätsbestätigung eingeben kann.

Wenn Sie die WebOTP API innerhalb eines ursprungsübergreifenden iFrames verwenden möchten, müssen Sie zwei Schritte ausführen:

  • Annotieren Sie in der SMS-Textnachricht sowohl den Ursprung des oberen Frames als auch den iFrame-Ursprung.
  • Konfigurieren Sie die Berechtigungsrichtlinie so, dass der ursprungsübergreifende iFrame OTP vom Nutzer direkt empfangen kann.
WebOTP API in einem iFrame in Aktion.

Sie können die Demo unter https://web-otp-iframe-demo.stackblitz.io ausprobieren.

Ursprungsorte der SMS-Textnachricht annotieren

Wenn die WebOTP API aus einem iFrame aufgerufen wird, muss die SMS den Ursprung des oberen Frames mit vorangestelltem @, das OTP mit vorangestelltem # und den Ursprung des iFrames mit vorangestelltem @ in der letzten Zeile enthalten.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Berechtigungsrichtlinie konfigurieren

Wenn Sie WebOTP in einem ursprungsübergreifenden iFrame verwenden möchten, muss der Einbettungsanbieter über die Berechtigungsrichtlinie „otp-credentials“ Zugriff auf diese API gewähren, um unbeabsichtigtes Verhalten zu vermeiden. Im Allgemeinen gibt es zwei Möglichkeiten, dieses Ziel zu erreichen:

über HTTP-Header:

Permissions-Policy: otp-credentials=(self "https://bank.example")

über iFrame allow-Attribut:

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

Weitere Beispiele zum Angeben einer Berechtigungsrichtlinie

WebOTP auf dem Computer verwenden

In Chrome unterstützt WebOTP das Abhören von SMS, die auf anderen Geräten empfangen wurden, um Nutzer bei der Bestätigung ihrer Telefonnummer auf dem Computer zu unterstützen.

WebOTP API auf dem Computer.

Für diese Funktion muss sich der Nutzer sowohl in der Desktopversion von Chrome als auch in Android in Chrome im selben Google-Konto anmelden.

Alle Entwickler müssen die WebOTP API auf ihrer Desktopwebsite wie auf ihrer mobilen Website implementieren. Es sind jedoch keine besonderen Tricks erforderlich.

Weitere Informationen finden Sie unter Telefonnummer auf dem Computer mit der WebOTP API bestätigen.

Häufig gestellte Fragen

Das Dialogfeld wird nicht angezeigt, obwohl ich eine korrekt formatierte Nachricht sende. Woran liegt das?

Beim Testen der API sind einige Einschränkungen zu beachten:

  • Wenn die Telefonnummer des Absenders in der Kontaktliste des Empfängers steht, wird diese API aufgrund des Designs der zugrunde liegenden SMS User Consent API nicht ausgelöst.
  • Wenn Sie ein Arbeitsprofil auf Ihrem Android-Gerät verwenden und WebOTP nicht funktioniert, versuchen Sie stattdessen, Chrome in Ihrem privaten Profil zu installieren und zu verwenden, d.h. in dem Profil, über das Sie SMS-Nachrichten empfangen.

Überprüfen Sie das Format, um festzustellen, ob Ihre SMS richtig formatiert ist.

Ist diese API mit verschiedenen Browsern kompatibel?

Chromium und WebKit haben sich auf das SMS-Format geeinigt und Apple hat angekündigt, dass Safari es ab iOS 14 und macOS Big Sur unterstützt. Obwohl Safari die WebOTP JavaScript API nicht unterstützt, schlägt die Standardtastatur beim Annotieren des input-Elements mit autocomplete=["one-time-code"] automatisch vor, das OTP einzugeben, wenn die SMS dem Format entspricht.

Ist es sicher, sich per SMS zu authentifizieren?

Das SMS-OTP ist zwar nützlich, um eine Telefonnummer zu bestätigen, wenn die Nummer zum ersten Mal angegeben wird. Die Bestätigung der Telefonnummer per SMS muss jedoch für die erneute Authentifizierung vorsichtig verwendet werden, da Telefonnummern von Mobilfunkanbietern gehackt und wiederverwendet werden können. WebOTP ist ein praktischer Mechanismus zur erneuten Authentifizierung und Wiederherstellung. Dienste sollten ihn jedoch mit zusätzlichen Faktoren wie einer Wissensabfrage kombinieren oder die Web Authentication API für eine starke Authentifizierung verwenden.

Wo kann ich Fehler bei der Chrome-Implementierung melden?

Haben Sie bei der Implementierung von Chrome einen Fehler gefunden?

  • Melden Sie den Fehler unter https://new.crbug.com. Geben Sie so viele Details wie möglich, eine einfache Anleitung zum Reproduzieren an und setzen Sie die Komponenten auf Blink>WebOTP.

Wie kann ich diese Funktion unterstützen?

Möchten Sie die WebOTP API verwenden? Ihre öffentliche Unterstützung hilft uns bei der Priorisierung von Funktionen und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen. Senden Sie einen Tweet an @ChromiumDev mit dem Hashtag #WebOTP und teilen Sie uns mit, wo und wie Sie es verwenden.

Ressourcen