Telefonnummern im Web mit der WebOTP API bestätigen

Nutzern mit per SMS empfangenen OTPs helfen

Eiji Kitamura

Was ist die WebOTP API?

Heutzutage besitzen die meisten Menschen ein Mobilgerät und Entwickler verwenden meist Telefonnummern als Kennung für Nutzer ihrer Dienste.

Es gibt verschiedene Möglichkeiten, Telefonnummern zu bestätigen. Am häufigsten wird jedoch ein zufällig generiertes Einmalpasswort (OTP, das per SMS gesendet wird) gesendet. Durch das Zurücksenden dieses Codes an den Server des Entwicklers wird die Kontrolle über die Telefonnummer veranschaulicht.

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

  • Telefonnummer als Kennung für den Nutzer. Wenn sich Websites für einen neuen Dienst registrieren, fordern einige Websites eine Telefonnummer anstelle einer E-Mail-Adresse an 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 tätigt, kann er nach einem einmaligen Code per SMS fragen, um die Absicht der Person zu überprüfen.

Der aktuelle Prozess sorgt für Reibungspunkte für die Nutzenden. Ein OTP in einer SMS-Nachricht zu finden und es dann zu kopieren und in das Formular einzufügen ist umständlich. Dadurch sinken die Conversion-Raten bei kritischen Kaufprozessen. Viele der weltweit größten Entwicklerinnen und Entwickler weltweit wünschen sich dies für das Web. Android hat eine API, die genau dies 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. Auf diese Weise 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 auf einer Website bestätigen. Die Website sendet dem Nutzer eine SMS per SMS und er 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 im Video gezeigt. Bei Eingang der SMS wird am unteren Rand eine Ansicht angezeigt, in der der Nutzer aufgefordert wird, seine Telefonnummer zu bestätigen. Nachdem sie im unteren Fenster auf die Schaltfläche Bestätigen geklickt hat, 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. Sie werden nicht nach Ihrer Telefonnummer gefragt und es wird keine SMS an Ihr Gerät gesendet. Sie können aber eine SMS von einem anderen Gerät senden, indem Sie den in der Demo angezeigten Text kopieren. 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, der als SMS gesendet wurde.

Zuerst spreche ich mit dem <input>-Tag an.

<input>-Tag annotieren

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

Dadurch kann dem Nutzer in Safari 14 oder höher vorgeschlagen werden, das Feld <input> automatisch mit einem OTP auszufüllen, wenn er eine SMS in dem unter SMS-Nachricht formatieren beschriebenen Format erhält, 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, reicht es aus, den folgenden Code einfach 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 Funktionserkennung ist die gleiche wie für viele andere APIs. Wenn das Ereignis DOMContentLoaded überwacht wird, wird darauf gewartet, dass 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 eine neue otp-Option hinzu. Es hat nur ein Attribut: transport. dessen 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 Promise mit einem OTPCredential-Objekt aufgelöst.

Inhalt des abgerufenen OTPCredential-Objekts

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

Übergeben Sie dann den OTP-Wert an das Feld <input>. Durch das direkte Absenden des Formulars müssen Nutzer 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 so einfach aussehen, aber es gibt ein paar Dinge, die Sie vor der Verwendung wissen sollten. Die Nachricht muss gesendet werden, nachdem navigator.credentials.get() aufgerufen wurde, und auf dem Gerät empfangen, auf dem get() aufgerufen wurde. Außerdem muss die Nachricht die folgende Formatierung haben:

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

Beispiel:

Your OTP is: 123456.

@www.example.com #123456

Hier sind einige Beispiele für schlechte Werte:

Beispiel für falsch formatierten 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		 Ein einzelnes Leerzeichen wird zwischen @host und #code erwartet.
Your verification code is 123456

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

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

@https://example.com #123456		 URL-Schema kann nicht eingefügt 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 eingeschlossen werden.
Your verification code is 123456

@example .com #123456		 Die Domain enthält keine Leerzeichen.
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 auch einen Fork erstellen und eine Version erstellen: https://glitch.com/edit/#!/web-otp.

WebOTP über einen ursprungsübergreifenden iFrame verwenden

Die Eingabe eines SMS-OTP in einen ursprungsübergreifenden iFrame wird in der Regel zur Zahlungsbestätigung verwendet, insbesondere bei 3D Secure. Da die WebOTP API ein gemeinsames Format zur Unterstützung von ursprungsübergreifenden iFrames hat, stellt sie OTPs bereit, die an verschachtelte Ursprünge gebunden sind. Beispiel:

  • Ein Nutzer besucht die Website von shop.example, um mit einer Kreditkarte Schuhe zu kaufen.
  • Nach der Eingabe der Kreditkartennummer zeigt der integrierte Zahlungsanbieter 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, damit er seine Identität bestätigen kann.

Wenn Sie die WebOTP API in einem ursprungsübergreifenden iFrame verwenden möchten, sind zwei Schritte erforderlich:

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

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

Grenzquellen an die SMS-Textnachricht annotieren

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

Your verification code is 123456

@shop.example #123456 @bank.exmple

Berechtigungsrichtlinie konfigurieren

Um WebOTP in einem ursprungsübergreifenden iFrame zu verwenden, muss der Einbettunger ü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 für Computer.

Dazu muss sich der Nutzer sowohl in der Desktopversion von Chrome als auch in Android Chrome mit demselben Google-Konto anmelden.

Alle Entwickler müssen die WebOTP API auf ihrer Desktopwebsite implementieren, genau wie auf ihrer mobilen Website. 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 gibt es einige Einschränkungen:

  • Wenn die Telefonnummer des Absenders in der Kontaktliste des Empfängers enthalten ist, 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, Chrome stattdessen in Ihrem privaten Profil zu installieren und zu verwenden, d.h. in dem Profil, in dem Sie SMS empfangen.

Überprüfen Sie dieses 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 für SMS geeinigt und Apple kündigte eine Unterstützung durch Safari ab iOS 14 und macOS Big Sur an. Obwohl Safari die WebOTP JavaScript API nicht unterstützt, schlägt die Standardtastatur automatisch vor, das OTP einzugeben, wenn das input-Element mit autocomplete=["one-time-code"] versehen wird, wenn die SMS-Nachricht diesem Format entspricht.

Ist es sicher, eine SMS zur Authentifizierung zu verwenden?

Ein SMS-OTP ist zwar nützlich, um eine Telefonnummer beim ersten Angeben der Nummer zu verifizieren, aber für die erneute Authentifizierung muss die Bestätigung der Telefonnummer per SMS 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 in der Chrome-Implementierung melden?

Haben Sie einen Fehler bei der Implementierung in Chrome gefunden?

  • Melden Sie einen Fehler unter https://new.crbug.com. Geben Sie so viele Details wie möglich und eine einfache Anleitung zum Reproduzieren an. Setzen Sie Components (Komponenten) auf Blink>WebOTP.

Wie kann ich diese Funktion unterstützen?

Möchten Sie die WebOTP API verwenden? Ihre öffentliche Unterstützung hilft uns dabei, Funktionen zu priorisieren und anderen Browseranbietern zu zeigen, wie wichtig es ist, sie zu unterstützen. Sende einen Tweet mit dem Hashtag #WebOTP an @ChromiumDev und teile uns mit, wo und wie du es verwendest.

Ressourcen