Weryfikowanie numerów telefonów w internecie za pomocą interfejsu WebOTP API

Pomoc dla użytkowników w przypadku kodów jednorazowych otrzymanych SMS-em

Eiji Kitamura

Czym jest interfejs WebOTP API?

Obecnie większość ludzi na świecie ma urządzenie mobilne, a deweloperzy często używają numerów telefonów jako identyfikatorów użytkowników swoich usług.

Istnieją różne sposoby weryfikacji numerów telefonów, ale jednym z najczęstszych jest losowo generowane hasło jednorazowe (OTP) wysyłane SMS-em. Wysłanie tego kodu z powrotem na serwer dewelopera potwierdza kontrolę nad numerem telefonu.

Ta koncepcja jest już stosowana w wielu scenariuszach w celu:

  • Numer telefonu jako identyfikator użytkownika. Podczas rejestracji w nowej usłudze niektóre witryny proszą o podanie numeru telefonu zamiast adresu e-mail i używają go jako identyfikatora konta.
  • Weryfikacja dwuetapowa. Podczas logowania się na stronie internetowej oprócz hasła lub innego czynnika wiedzy możesz zostać poproszony(-a) o podanie jednorazowego kodu wysłanego SMS-em.
  • Potwierdzenie płatności. Gdy użytkownik dokonuje płatności, poproszenie o wysłanie jednorazowego kodu SMS-em może pomóc w weryfikacji jego zamiaru.

Obecny proces powoduje problemy dla użytkowników. Wyszukiwanie kodu OTP w SMS-ie, a następnie kopiowanie i wklejanie go w formularzu jest uciążliwe i obniża współczynniki konwersji w kluczowych procesach użytkownika. Wielu dużych programistów na całym świecie od dawna prosi o zwiększenie limitu. Android ma interfejs API, który służy właśnie do tego celu. Dotyczy to również iOS i Safari.

Interfejs WebOTP API umożliwia aplikacji odbieranie wiadomości w specjalnym formacie powiązanym z domeną aplikacji. Dzięki temu możesz programowo pobierać hasła jednorazowe z wiadomości SMS i łatwiej weryfikować numer telefonu użytkownika.

Zobacz, jak to działa

Załóżmy, że użytkownik chce zweryfikować swój numer telefonu w witrynie. Witryna wysyła SMS-a do użytkownika, a ten podaje w SMS-ie hasło jednorazowe, aby potwierdzić, że jest właścicielem numeru telefonu.

Dzięki interfejsowi WebOTP użytkownik może wykonać te czynności jednym kliknięciem, jak pokazano w filmie. Gdy wiadomość tekstowa dotrze do użytkownika, na dole ekranu pojawi się panel z prośbą o weryfikację numeru telefonu. Po kliknięciu przycisku Sprawdź na dolnym arkuszu przeglądarka wklei kod OTP do formularza, który zostanie przesłany bez konieczności klikania przycisku Dalej.

Cały proces jest przedstawiony na diagramie na obrazie poniżej.

Schemat interfejsu WebOTP API

Wypróbuj wersję demonstracyjną. Nie prosi o podanie numeru telefonu ani nie wysyła SMS-a na urządzenie, ale możesz wysłać SMS-a z innego urządzenia, kopiując tekst wyświetlany w demo. To działa, ponieważ podczas korzystania z interfejsu WebOTP nie ma znaczenia, kto jest nadawcą.

  1. Otwórz stronę https://web-otp.glitch.me w Chrome 84 lub nowszej wersji na urządzeniu z Androidem.
  2. Wyślij na swój telefon SMS-a z innego telefonu.
Your OTP is: 123456.

@web-otp.glitch.me #12345

Czy otrzymałeś SMS-a i czy w obszarze wprowadzania danych pojawił się komunikat z prośbą o wpisanie kodu? Właśnie tak działa interfejs WebOTP API dla użytkowników.

Korzystanie z interfejsu WebOTP API składa się z 3 części:

  • Prawidłowo oznaczony tag <input>
  • JavaScript w aplikacji internetowej
  • Sformatowany tekst wiadomości wysłanej SMS-em.

Najpierw omówię tag <input>.

Dodawanie adnotacji do tagu <input>

WebOTP działa bez adnotacji HTML, ale ze względu na zgodność z wieloma przeglądarkami zdecydowanie zalecamy dodanie autocomplete="one-time-code" do tagu <input>, w którym użytkownik ma wpisać kod OTP.

Dzięki temu Safari w wersji 14 lub nowszej może sugerować użytkownikowi autouzupełnianie pola <input> za pomocą kodu OTP, gdy otrzyma SMS-a w formacie opisanym w sekcji Formatowanie wiadomości SMS, mimo że nie obsługuje ona WebOTP.

w kodzie HTML,

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

Korzystanie z interfejsu WebOTP API

WebOTP jest prosty, więc wystarczy skopiować i wklejć podany poniżej kod. Przeprowadzę Cię przez cały proces.

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);
    });
  });
}

Wykrywanie cech

Wykrywanie funkcji działa tak samo jak w przypadku wielu innych interfejsów API. Nasłuchywanie zdarzenia DOMContentLoaded będzie oczekiwać, aż drzewo DOM będzie gotowe do wysłania zapytania.

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');
    …
  });
}

Przetwarzanie hasła jednorazowego

Interfejs WebOTP API jest dość prosty. Aby uzyskać hasło jednorazowe, użyj adresu navigator.credentials.get(). WebOTP dodaje do tej metody nową opcję otp. Ma tylko jedną właściwość: transport, której wartość musi być tablicą zawierającą ciąg znaków 'sms'.

JavaScript

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

Gdy otrzymasz SMS-a, przeglądarka uruchomi proces uzyskiwania uprawnień. Jeśli pozwolenie zostanie udzielone, zwrócona obietnica zostanie rozwiązana z obiektem OTPCredential.

Treść uzyskanego obiektu OTPCredential

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

Następnie przekaż wartość OTP do pola <input>. Przesłanie formularza bezpośrednio wyeliminuje konieczność kliknięcia przez użytkownika przycisku.

JavaScript

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

Przerwanie wiadomości

Jeśli użytkownik ręcznie wpisze kod OTP i prześle formularz, możesz anulować wywołanie get(), używając instancji AbortController w obiekcie options.

JavaScript 

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

Formatowanie wiadomości SMS

Interfejs API powinien być dość prosty, ale przed jego użyciem musisz wiedzieć kilka rzeczy. Wiadomość musi zostać wysłana po wywołaniu funkcji navigator.credentials.get() i otrzymana na urządzeniu, na którym wywołano funkcję get(). Oprócz tego wiadomość musi być sformatowana w ten sposób:

  • Wiadomość zaczyna się (opcjonalnie) tekstem zrozumiałym dla człowieka, który zawiera ciąg znaków alfanumerycznych o długości od 4 do 10 znaków, z co najmniej 1 liczbą, pozostawiając ostatnie miejsce na adres URL i kod OTP.
  • Część domeny adresu URL witryny, która wywołała interfejs API, musi być poprzedzona symbolem @.
  • Adres URL musi zawierać podwójny krzyżyk („#”) i kod OTP.

Na przykład:

Your OTP is: 123456.

@www.example.com #123456

Oto złe przykłady:

Przykład źle sformatowanego SMS-a Dlaczego to nie zadziała
Here is your code for @example.com #123456 Wartość @ powinna być pierwszym znakiem ostatniego wiersza.
Your code for @example.com is #123456 Wartość @ powinna być pierwszym znakiem ostatniego wiersza.
Your verification code is 123456

@example.com\t#123456		 Między @host a #code powinna być pojedyncza spacja.
Your verification code is 123456

@example.com  #123456		 Między @host a #code powinna być pojedyncza spacja.
Your verification code is 123456

@ftp://example.com #123456		 Nie można uwzględnić schematu adresu URL.
Your verification code is 123456

@https://example.com #123456		 Nie można uwzględnić schematu adresu URL.
Your verification code is 123456

@example.com:8080 #123456		 Port nie może być uwzględniony.
Your verification code is 123456

@example.com/foobar #123456		 Ścieżka nie może być uwzględniona.
Your verification code is 123456

@example .com #123456		 Brak spacji w domenie.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 Brak zakazanych znaków w domenie.
@example.com #123456

Mambo Jumbo		 Wartości @host i #code powinny znajdować się w ostatnim wierszu.
@example.com #123456

App hash #oudf08lkjsdf834		 Wartości @host i #code powinny znajdować się w ostatnim wierszu.
Your verification code is 123456

@example.com 123456		 Brakuje atrybutu #.
Your verification code is 123456

example.com #123456		 Brakuje atrybutu @.
Hi mom, did you receive my last text Brak wartości @ i #.

Prezentacje

Wypróbuj różne wiadomości w wersji demonstracyjnej: https://web-otp.glitch.me

Możesz też utworzyć własną wersję: https://glitch.com/edit/#!/web-otp.

Używanie WebOTP z elementu iframe z innej domeny

Wprowadzanie kodu OTP SMS do elementu iframe w wielu domenach jest zwykle używane do potwierdzenia płatności, zwłaszcza w przypadku 3D Secure. Dzięki wspólnemu formatowi do obsługi iframe z innych źródeł interfejs WebOTP dostarcza kody OTP powiązane z zagnieżdżonymi źródłami. Przykład:

  • Użytkownik odwiedza stronę shop.example, aby kupić buty za pomocą karty kredytowej.
  • Po wpisaniu numeru karty kredytowej zintegrowany dostawca płatności wyświetla w ramce iframe formularz z bank.example, w którym prosi użytkownika o potwierdzenie numeru telefonu, aby umożliwić szybkie dokonanie płatności.
  • bank.example wysyła SMS-a z hasłem jednorazowym, aby użytkownik mógł go wpisać i potwierdzić swoją tożsamość.

Aby używać interfejsu WebOTP API z poziomu elementu iframe w innej domenie, musisz wykonać 2 czynności:

  • W tekście SMS-a dodaj adnotacje do obu źródeł: górnego elementu ramki i iframe.
  • Skonfiguruj zasady dotyczące uprawnień, aby umożliwić elementowi iframe w innej domenie odbieranie kodu OTP bezpośrednio od użytkownika.
WebOTP API w ramce iframe w działaniu

Wersję demonstracyjną możesz wypróbować na stronie https://web-otp-iframe-demo.stackblitz.io.

Dołączanie adnotacji do powiązanych usług do SMS-a

Gdy interfejs WebOTP API jest wywoływany z poziomu elementu iframe, wiadomość SMS musi zawierać:@, po którym następuje #, a na ostatnim wierszu @.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Konfigurowanie zasad dotyczących uprawnień

Aby używać WebOTP w elementach iframe z innych domen, osoba umieszczająca je na stronie musi przyznać dostęp do tego interfejsu API za pomocą zasad dotyczących uprawnień dotyczących danych logowania do usługi OTP, aby uniknąć niezamierzonego działania. Ogólnie istnieją 2 sposoby osiągnięcia tego celu:

za pomocą nagłówka HTTP:

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

za pomocą atrybutu iframe allow:

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

Zobacz więcej przykładów określania zasad dotyczących uprawnień .

Korzystanie z WebOTP na komputerze

W Chrome WebOTP obsługuje odsłuchiwanie SMS-ów odebranych na innych urządzeniach, aby ułatwić użytkownikom weryfikację numeru telefonu na komputerze.

WebOTP API na komputerze.

Ta funkcja wymaga zalogowania się na to samo konto Google w Chrome na komputerze i w Chrome na Androida.

Deweloperzy muszą tylko zaimplementować interfejs WebOTP API w swojej witrynie na komputery, tak samo jak w witrynie mobilnej, ale bez stosowania specjalnych sztuczek.

Więcej informacji znajdziesz w artykule Weryfikacja numeru telefonu na komputerze za pomocą interfejsu WebOTP API.

Najczęstsze pytania

Okno nie pojawia się, mimo że wysyłam prawidłowo sformatowaną wiadomość. Co jest nie tak?

Podczas testowania interfejsu API należy wziąć pod uwagę kilka kwestii:

  • Jeśli numer telefonu nadawcy znajduje się na liście kontaktów odbiorcy, interfejs API nie zostanie uruchomiony z powodu konstrukcji podstawowego interfejsu SMS API dotyczącego zgody użytkownika.
  • Jeśli na urządzeniu z Androidem używasz profilu służbowego, a WebOTP nie działa, zainstaluj Chrome na profilu osobistym (czyli na tym samym profilu, na którym otrzymujesz SMS-y).

Sprawdź format, aby zobaczyć, czy SMS jest prawidłowo sformatowany.

Czy ten interfejs API jest zgodny z różnymi przeglądarkami?

Chromium i WebKit uzgodniły format wiadomości tekstowych SMS, a firma Apple ogłosiła, że Safari będzie go obsługiwać od iOS 14 i macOS Big Sur. Mimo że Safari nie obsługuje interfejsu WebOTP JavaScript API, jeśli element input zostanie opatrzony adnotacją autocomplete=["one-time-code"], domyślna klawiatura automatycznie zaproponuje wpisanie kodu OTP, jeśli wiadomość SMS jest zgodna z formatem.

Czy korzystanie z SMS-ów do uwierzytelniania jest bezpieczne?

SMS-y z hasłem jednorazowym są przydatne do weryfikacji numeru telefonu przy pierwszym podawaniu numeru, ale w przypadku ponownej autoryzacji należy zachować ostrożność, ponieważ numery telefonów mogą być przechwytywane i wykorzystywane przez operatorów. WebOTP to wygodny mechanizm ponownego uwierzytelniania i odzyskiwania, ale usługi powinny go łączyć z dodatkowymi czynnikami, takimi jak test wiedzy, lub używać interfejsu Web Authentication API do uwierzytelniania silnego.

Gdzie zgłaszać błędy w implementacji Chrome?

Czy znalazłeś/znalazłaś błąd w implementacji Chrome?

  • Zgłoś błąd na stronie crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtworzenia błędu i ustaw wartość Components na Blink>WebOTP.

Jak mogę pomóc w rozwoju tej funkcji?

Zamierzasz używać interfejsu WebOTP API? Twoje publiczne wsparcie pomaga nam ustalać priorytety w przypadku funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie. Wyślij tweeta do @ChromiumDev, używając hashtaga #WebOTP, i podaj, gdzie i jak go używasz.

Zasoby