Telefonnummern im Web mit der WebOTP API bestätigen

Nutzern mit per SMS erhaltenen OTPs helfen

Eiji Kitamura

Was ist die WebOTP API?

Heutzutage haben die meisten Menschen auf der Welt ein Mobilgerät und Entwickler verwenden häufig Telefonnummern als Kennung für Nutzer ihrer Dienste.

Es gibt verschiedene Möglichkeiten, Telefonnummern zu bestätigen. Eine der gängigsten ist ein per SMS gesendetes, zufällig generiertes Einmalpasswort (OTP). Wenn dieser Code an den Server des Entwicklers zurückgesendet wird, wird die Kontrolle über die Telefonnummer nachgewiesen.

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 wird auf einigen Websites eine Telefonnummer anstelle einer E-Mail-Adresse abgefragt und als Konto-ID verwendet.
  • 2-Faktor-Authentifizierung Bei der Anmeldung auf einer Website wird zusätzlich zu einem Passwort oder einem anderen Wissensfaktor zur zusätzlichen Sicherheit ein einmaliger Code per SMS angefordert.
  • Zahlungsbestätigung Wenn ein Nutzer eine Zahlung ausführt, kann die Aufforderung zur Eingabe eines einmaligen Codes, der per SMS gesendet wird, dazu beitragen, die Absicht der Person zu bestätigen.

Der aktuelle Prozess ist für Nutzer kompliziert. Es ist mühsam, einen OTP in einer SMS-Nachricht zu finden, ihn zu kopieren und in das Formular einzufügen. Das senkt die Conversion-Raten in wichtigen Kaufprozessen. Viele der größten Entwickler weltweit haben schon lange eine Vereinfachung für das Web gefordert. Android bietet eine API, die genau das tut. Das gilt auch für iOS und Safari.

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

Beispiele ansehen

Angenommen, ein Nutzer möchte seine Telefonnummer auf einer Website bestätigen. Die Website sendet dem Nutzer eine SMS und der Nutzer gibt das OTP aus der Nachricht ein, um den Inhaber 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. Wenn die SMS eingeht, wird ein Unterblatt eingeblendet, in dem der Nutzer aufgefordert wird, seine Telefonnummer zu bestätigen. Nachdem der Nutzer auf dem unteren Blatt auf die Schaltfläche Bestätigen geklickt hat, fügt der Browser das OTP in das Formular ein und das Formular wird gesendet, ohne dass der Nutzer auf Weiter klicken muss.

Der gesamte Prozess ist im Bild unten dargestellt.

Diagramm der WebOTP API

Probieren Sie die Demo selbst aus. Es wird nicht nach Ihrer Telefonnummer gefragt und es wird auch keine SMS an Ihr Gerät gesendet. Sie können aber eine SMS von einem anderen Gerät aus senden, indem Sie den in der Demo angezeigten Text kopieren. Das funktioniert, weil 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 Ihrem Smartphone von einem anderen Smartphone aus die folgende SMS.
Your OTP is: 123456.

@web-otp.glitch.me #12345

Haben Sie die SMS erhalten und die Aufforderung gesehen, den Code in das Eingabefeld einzugeben? So funktioniert die WebOTP API für Nutzer.

Die Verwendung der WebOTP API besteht aus drei Teilen:

  • Ein korrekt kommentiertes <input>-Tag
  • JavaScript in Ihrer Webanwendung
  • Formatierter Text einer Nachricht, die per SMS gesendet wurde.

Ich erkläre zuerst das <input>-Tag.

<input>-Tag mit Anmerkungen versehen

WebOTP funktioniert ohne HTML-Anmerkung. Für die plattformübergreifende Kompatibilität empfehlen wir jedoch dringend, dem <input>-Tag, in dem der Nutzer ein OTP eingeben soll, autocomplete="one-time-code" hinzuzufügen.

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

HTML

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

WebOTP API verwenden

Da WebOTP einfach ist, genügt es, den folgenden Code zu kopieren und einzufügen. 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 Funktionsweise der Feature-Erkennung entspricht der vieler anderer APIs. Wenn Sie auf das Ereignis DOMContentLoaded warten, wird gewartet, bis der DOM-Baum für die Abfrage bereit ist.

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 recht einfach. Verwenden Sie navigator.credentials.get(), um das OTP abzurufen. WebOTP fügt dieser Methode eine neue otp-Option hinzu. Sie hat nur eine Property: transport. Der Wert muss ein Array mit dem String 'sms' sein.

JavaScript

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

Dadurch wird der Berechtigungsablauf des Browsers ausgelöst, wenn eine SMS eingeht. Wenn die Berechtigung gewährt wird, wird das zurückgegebene Versprechen 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 das Formular direkt gesendet wird, entfällt der Schritt, bei dem der Nutzer auf eine Schaltfläche tippen muss.

JavaScript

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

Nachricht abbrechen

Wenn der Nutzer ein OTP manuell eingibt und das Formular einreicht, kannst du 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 einige Dinge, die Sie vor der Verwendung wissen sollten. Die Nachricht muss nach dem Aufruf von navigator.credentials.get() gesendet und auf dem Gerät empfangen werden, auf dem get() aufgerufen wurde. Außerdem muss die Nachricht folgende Formatierung haben:

  • Die Nachricht beginnt mit einem (optionalen) visuell lesbaren Text, der einen alphanumerischen String mit vier bis zehn Zeichen mit mindestens einer Zahl enthält. Die letzte Zeile ist für die URL und das OTP reserviert.
  • Vor dem Domainteil der URL der Website, auf der die API aufgerufen wurde, muss @ stehen.
  • Die URL muss ein Rautezeichen („#“) gefolgt vom OTP enthalten.

Beispiel:

Your OTP is: 123456.

@www.example.com #123456

Hier sind einige schlechte Beispiele:

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

@example.com\t#123456		 Zwischen @host und #code ist ein einzelner Leerraum erforderlich.
Your verification code is 123456

@example.com  #123456		 Zwischen @host und #code ist ein einzelner Leerraum erforderlich.
Your verification code is 123456

@ftp://example.com #123456		 Das URL-Schema darf nicht enthalten sein.
Your verification code is 123456

@https://example.com #123456		 Das URL-Schema darf nicht enthalten sein.
Your verification code is 123456

@example.com:8080 #123456		 Der Anschluss darf nicht enthalten sein.
Your verification code is 123456

@example.com/foobar #123456		 Der Pfad darf nicht enthalten sein.
Your verification code is 123456

@example .com #123456		 Die Domain darf keine Leerzeichen enthalten.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 Die Domain darf keine unzulässigen Zeichen enthalten.
@example.com #123456

Mambo Jumbo		 @host und #code sollten die letzte Zeile sein.
@example.com #123456

App hash #oudf08lkjsdf834		 @host und #code sollten 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

Mit der Demo verschiedene Nachrichten testen: https://web-otp.glitch.me

Sie können es auch forkieren und Ihre eigene Version erstellen: https://glitch.com/edit/#!/web-otp.

WebOTP über einen ursprungsübergreifenden iFrame verwenden

Die Eingabe eines SMS-OTP in einen iframe mit unterschiedlichen Ursprüngen wird in der Regel für die Zahlungsbestätigung verwendet, insbesondere bei 3D Secure. Da die WebOTP API das gängige Format zur Unterstützung von iframes mit unterschiedlichen Ursprüngen verwendet, werden OTPs an verschachtelte Ursprünge gebunden. Beispiel:

  • Ein Nutzer besucht shop.example, um ein Paar Schuhe mit einer Kreditkarte zu kaufen.
  • Nach der Eingabe der Kreditkartennummer zeigt der integrierte Zahlungsanbieter in einem Iframe ein Formular von bank.example an, in dem der Nutzer aufgefordert wird, seine Telefonnummer für den schnellen Bezahlvorgang zu bestätigen.
  • bank.example sendet dem Nutzer eine SMS mit einem OTP, das er zur Bestätigung seiner Identität eingeben kann.

Wenn Sie die WebOTP API in einem iframe mit unterschiedlichen Ursprüngen verwenden möchten, müssen Sie zwei Dinge tun:

  • Fügen Sie in der SMS-Textnachricht sowohl den Ursprung des Top-Frames als auch den des iFrames hinzu.
  • Konfigurieren Sie die Berechtigungsrichtlinie so, dass der iframe mit unterschiedlichen Ursprüngen OTP direkt vom Nutzer empfangen kann.
Ein WebOTP API-iFrame in Aktion.

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

gebundene Ursprünge in der SMS-Textnachricht annotieren

Wenn die WebOTP API innerhalb eines Iframes aufgerufen wird, muss die SMS-Textnachricht den Ursprung des Top-Frames mit vorangestellter @, gefolgt vom OTP mit vorangestellter # und dem Ursprung des Iframes mit vorangestellter @ in der letzten Zeile enthalten.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Berechtigungsrichtlinie konfigurieren

Wenn WebOTP in einem iframe mit unterschiedlichen Ursprüngen verwendet werden soll, muss der Einbettungscode-Anbieter über die Berechtigungsrichtlinie für otp-Anmeldedaten 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 das iframe-Attribut allow:

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

Weitere Beispiele für die Angabe einer Berechtigungsrichtlinie

WebOTP auf dem Computer verwenden

In Chrome unterstützt WebOTP das Abhören von SMS, die auf anderen Geräten empfangen werden, um Nutzern die Bestätigung der Telefonnummer auf dem Computer zu erleichtern.

WebOTP API auf dem Computer.

Für diese Funktion muss sich der Nutzer sowohl in Chrome für Computer als auch in Chrome für Android mit demselben Google-Konto anmelden.

Entwickler müssen die WebOTP API auf ihrer Desktop-Website genauso implementieren wie auf ihrer mobilen Website. Es sind keine speziellen Tricks erforderlich.

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

FAQ

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

Beim Testen der API gibt es einige Einschränkungen:

  • Wenn die Telefonnummer des Absenders in der Kontaktliste des Empfängers enthalten ist, wird diese API aufgrund der Funktionsweise der zugrunde liegenden SMS User Consent API nicht ausgelöst.
  • Wenn Sie ein Arbeitsprofil auf Ihrem Android-Gerät verwenden und der Web-OTP nicht funktioniert, installieren und verwenden Sie Chrome stattdessen in Ihrem privaten Profil, also in dem Profil, in dem Sie SMS-Nachrichten erhalten.

Sehen Sie sich das Format noch einmal an, um zu prüfen, ob Ihre SMS richtig formatiert ist.

Ist diese API mit verschiedenen Browsern kompatibel?

Chromium und WebKit haben sich auf ein SMS-Format geeinigt und Apple hat angekündigt, dass Safari ab iOS 14 und macOS Big Sur diese Funktion unterstützt. Auch wenn Safari die WebOTP JavaScript API nicht unterstützt, wird durch das Anhängen von autocomplete=["one-time-code"] an das input-Element automatisch die Eingabe des OTPs über die Standardtastatur vorgeschlagen, wenn die SMS dem Format entspricht.

Ist es sicher, SMS zur Authentifizierung zu verwenden?

SMS-OTPs sind zwar nützlich, um eine Telefonnummer zu bestätigen, wenn sie zum ersten Mal angegeben wird, die Bestätigung per SMS muss bei der erneuten Authentifizierung jedoch mit Bedacht 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 kombinieren, z. B. mit einer Wissensfrage, oder die Web Authentication API für eine starke Authentifizierung verwenden.

Wo kann ich Fehler in der Chrome-Implementierung melden?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden?

  • Melden Sie den Fehler unter crbug.com. Geben Sie dabei so viele Details wie möglich an, fügen Sie eine einfache Anleitung zum Nachstellen des Fehlers hinzu und setzen Sie Components auf Blink>WebOTP.

Wie kann ich diese Funktion verbessern?

Beabsichtigen Sie, die WebOTP API zu verwenden? Ihre öffentliche Unterstützung hilft uns, Funktionen zu priorisieren, 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 ihn verwenden.

Ressourcen