Ta strona została przetłumaczona przez Cloud Translation API.

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

Pomoc dla użytkowników korzystających z haseł jednorazowych otrzymywanych SMS-em

Eiji Kitamura

Twitter GitHub Glitch Mastodon

Czym jest interfejs WebOTP API?

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

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

Ten pomysł został już wdrożony w wielu scenariuszach, aby:

Numer telefonu jako identyfikator użytkownika. Podczas rejestracji w nowej usłudze niektóre witryny wymagają podania numeru telefonu zamiast adresu e-mail i używają go jako identyfikatora konta.
Weryfikacja dwuetapowa. Podczas logowania strona internetowa prosi o podanie jednorazowego kodu wysłanego SMS-em w postaci hasła lub innego zabezpieczenia.
Potwierdzenie płatności. Gdy użytkownik dokonuje płatności, prośba o jednorazowy kod wysłany w SMS-ie może pomóc w zweryfikowaniu zamiaru tej osoby.

Obecny proces utrudnia użytkownikom. Znalezienie hasła jednorazowego w SMS-ie, a potem skopiowanie go i wklejenie do formularza jest niewygodne i zmniejsza współczynniki konwersji na najważniejszych etapach ścieżki użytkownika. Rozwiązanie tego problemu od dawna otrzymało od wielu największych deweloperów z całego świata. Android ma interfejs API, który dokładnie tak działa. To samo dotyczy iOS i Safari.

Interfejs WebOTP API umożliwia aplikacji odbieranie specjalnie sformatowanych wiadomości powiązanych z domeną Twojej aplikacji. W ten sposób możesz automatycznie otrzymywać hasło jednorazowe z SMS-a i łatwiej zweryfikować numer telefonu użytkownika.

Zobacz, jak to działa

Załóżmy, że użytkownik chce potwierdzić swój numer telefonu w witrynie. Witryna wysyła do użytkownika SMS-a, w którym wpisuje hasło jednorazowe, aby potwierdzić własność numeru telefonu.

Dzięki interfejsowi WebOTP API możesz wykonać te czynności jednym kliknięciem, co widać na filmie. Po otrzymaniu SMS-a wyświetla się plansza dolna z prośbą o potwierdzenie numeru telefonu. Po kliknięciu przycisku Zweryfikuj w dolnej części arkusza przeglądarka wkleja hasło jednorazowe do formularza, a formularz jest przesyłany bez konieczności klikania przycisku Dalej.

Cały proces przedstawiono na ilustracji poniżej.

Zobacz prezentację. Nie wymaga on podania numeru telefonu ani wysyłania SMS-ów na urządzenie, ale można wysłać go z innego urządzenia, kopiując tekst wyświetlany w wersji demonstracyjnej. Dzięki temu nie ma znaczenia, kto jest nadawcą w przypadku używania interfejsu WebOTP API.

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

Your OTP is: 123456.

@web-otp.glitch.me #12345

Czy dotarł do Ciebie SMS i widzisz prośbę o wpisanie kodu w obszarze wprowadzania? Tak działa interfejs WebOTP API dla użytkowników.

Na korzystanie z interfejsu WebOTP API składają się 3 części:

Tag <input> z odpowiednimi adnotacjami
JavaScript w aplikacji internetowej
Sformatowany tekst wiadomości wysłany przez SMS.

Najpierw omówię tag <input>.

Dodaj adnotację do tagu `<input>`

WebOTP działa bez adnotacji HTML, ale aby zapewnić zgodność z różnymi przeglądarkami, zdecydowanie zalecamy dodanie autocomplete="one-time-code" do tagu <input> w miejscu, w którym użytkownik powinien wpisać hasło jednorazowe.

Dzięki temu Safari w wersji 14 lub nowszej może zasugerować użytkownikowi autouzupełnianie pola <input> hasłem jednorazowym po otrzymaniu SMS-a w formacie opisanym w artykule Formatowanie wiadomości SMS, mimo że ta funkcja nie obsługuje WebOTP.

w kodzie HTML,

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

Używanie interfejsu WebOTP API

WebOTP jest prosty, więc wystarczy skopiować i wkleić poniższy kod. Tak czy inaczej, wyjaśnię Ci, co się dzieje.

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 funkcji

Wykrywanie funkcji jest takie samo jak w przypadku wielu innych interfejsów API. Detektor zdarzenia DOMContentLoaded będzie czekać, aż drzewo DOM będzie gotowe do wykonania 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

Sam interfejs WebOTP API jest wystarczająco 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ą z ciągiem znaków 'sms'.

JavaScript

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

Spowoduje to aktywowanie procedury uprawnień przeglądarki, gdy nadejdzie wiadomość SMS. Jeśli użytkownik otrzyma uprawnienia, zwrócona obietnica znika z obiektem OTPCredential.

Zawartość uzyskanego obiektu OTPCredential

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

Następnie przekaż wartość hasła jednorazowego do pola <input>. Bezpośrednie przesłanie formularza eliminuje konieczność kliknięcia 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 hasło jednorazowe i prześle formularz, możesz anulować wywołanie get(), używając wystąpienia 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 => {
    …

Sformatuj SMS-a

Sam interfejs API powinien wyglądać na dość prosty, ale jest kilka rzeczy, które musisz wiedzieć, zanim z niego skorzystasz. Wiadomość musi zostać wysłana po wywołaniu funkcji navigator.credentials.get() i musi zostać odebrana na urządzeniu, na którym została wywołana usługa get(). Wiadomość musi też być zgodna z następującym formatem:

Wiadomość zaczyna się (opcjonalnym) zrozumiałym dla człowieka tekstem, który zawiera od 4 do 10 znaków alfanumerycznych. Co najmniej 1 cyfrę pozostawia w ostatnim wierszu adresu URL i hasła jednorazowego.
Część domeny adresu URL witryny, która wywołała interfejs API, musi być poprzedzona ciągiem @.
Adres URL musi zawierać podwójny krzyżyk („#”), po którym następuje hasło jednorazowe.

Na przykład:

Your OTP is: 123456.

@www.example.com #123456

Oto złe przykłady:

Przykładowy nieprawidłowy tekst SMS-a	Dlaczego to nie działa
`Here is your code for @example.com #123456`	`@` będzie prawdopodobnie pierwszym znakiem ostatniego wiersza.
`Your code for @example.com is #123456`	`@` będzie prawdopodobnie pierwszym znakiem ostatniego wiersza.
`Your verification code is 123456` `@example.com\t#123456`	Pojedyncza spacja jest spodziewana między `@host` a `#code`.
`Your verification code is 123456` `@example.com` `#123456`	Pojedyncza spacja jest spodziewana między `@host` a `#code`.
`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`	Nie można uwzględnić portu.
`Your verification code is 123456` `@example.com/foobar #123456`	Nie można uwzględnić ścieżki.
`Your verification code is 123456` `@example .com #123456`	Brak odstępów w domenie.
`Your verification code is 123456` `@domain-forbiden-chars-#%/:<>?@[] #123456`	Brak zabronionych znaków w domenie.
`@example.com #123456` `Mambo Jumbo`	Wiersze `@host` i `#code` będą prawdopodobnie ostatnim wierszem.
`@example.com #123456` `App hash #oudf08lkjsdf834`	Wiersze `@host` i `#code` będą prawdopodobnie ostatnim wierszem.
`Your verification code is 123456` `@example.com 123456`	Brak pola `#`.
`Your verification code is 123456` `example.com #123456`	Brak pola `@`.
`Hi mom, did you receive my last text`	Brak atrybutów `@` i `#`.

Przykłady

W wersji demonstracyjnej wypróbuj różne komunikaty: https://web-otp.glitch.me

Możesz też utworzyć rozwidlenie i utworzyć swoją wersję: https://glitch.com/edit/#!/web-otp.

Używanie WebOTP z międzyźródłowego elementu iframe

Wpisanie hasła jednorazowego z SMS-a do międzyźródłowego elementu iframe jest zwykle używane do potwierdzenia płatności, zwłaszcza w przypadku 3D Secure. Interfejs WebOTP API ma wspólny format do obsługi elementów iframe z innych domen, dzięki czemu interfejs WebOTP API dostarcza hasła jednorazowe powiązane z zagnieżdżonymi źródłami. Przykład:

Użytkownik odwiedza sklep shop.example, aby kupić parę butów za pomocą karty kredytowej.
Po wpisaniu numeru karty kredytowej zintegrowany dostawca usług płatniczych wyświetla w elemencie iframe formularz z witryny bank.example, z prośbą o potwierdzenie numeru telefonu użytkownika w celu szybkiej płatności.
bank.example wysyła do użytkownika SMS-a z hasłem jednorazowym, aby mógł on wpisać go, aby potwierdzić swoją tożsamość.

Aby używać interfejsu WebOTP API z elementu iframe z innych domen, musisz zrobić 2 rzeczy:

W SMS-ie dodaj adnotacje ze źródłem górnej ramki i pierwotnym elementem iframe.
Skonfiguruj zasady uprawnień tak, aby międzyźródłowy element iframe bezpośrednio odbierał hasło jednorazowe od użytkownika.

Interfejs WebOTP API w elemencie iframe w działaniu.

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

Dodaj adnotacje dotyczące źródeł powiązanych z SMS-em

Gdy interfejs WebOTP API jest wywoływany z elementu iframe, wiadomość tekstowa SMS musi zawierać źródło ramki najwyższego poziomu poprzedzone znakiem @, po którym następuje hasło jednorazowe poprzedzone znakiem #, a źródło elementu iframe poprzedzone znakiem @ w ostatnim wierszu.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Skonfiguruj zasadę uprawnień

Aby używać WebOTP w międzyźródłowym elemencie iframe, komponent do umieszczania na stronie musi przyznać dostęp do tego interfejsu API za pomocą zasady uprawnień otp-credential. W ten sposób unikniesz niezamierzonego zachowania. Ogólnie można osiągnąć ten cel na 2 sposoby:

przez nagłówek 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ń .

Uwaga: obecnie Chrome obsługuje tylko wywołania interfejsu WebOTP API z innych domen iframe, które mają nie więcej niż 1 unikalne źródło w łańcuchu elementów nadrzędnych. W tych scenariuszach: <ul> <li>a.com -> b.com</li> <li>a.com -> b.com -> b.com</li> <li>a.com -> a.com -> b.com</li> <li>a.com -> b.com -> c.com</li> </ul> W b.com można używać WebOTP, ale nie można go używać w c.com. Ten scenariusz nie jest też obsługiwany ze względu na brak popytu i złożoności UX. <ul> <li>a.com -> b.com -> a.com (wywołania WebOTP API)</li> </ul>

Używaj 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.

Interfejs WebOTP API na komputerze.

Ta funkcja wymaga od użytkownika zalogowania się na to samo konto Google w Chrome na komputery i w Chrome na Androida.

Wystarczy, że deweloperzy zaimplementują interfejs WebOTP API w swojej witrynie na komputery w taki sam sposób jak w witrynie mobilnej. Nie są jednak wymagane żadne specjalne sztuczki.

Więcej informacji znajdziesz w artykule o potwierdzaniu numeru telefonu na komputerze przy użyciu interfejsu WebOTP API.

Najczęstsze pytania

Okno nie pojawia się, mimo że wysyłam prawidłowo sformatowaną wiadomość. Na czym polega problem?

Testowanie interfejsu API wiąże się z kilkoma zastrzeżeniami:

Jeśli numer telefonu nadawcy znajduje się na liście kontaktów odbiorcy, ten interfejs API nie zostanie aktywowany ze względu na konstrukcję podstawowego interfejsu API do uzyskiwania zgody użytkownika przez SMS.
Jeśli używasz profilu służbowego na urządzeniu z Androidem, a WebOTP nie działa, spróbuj zainstalować Chrome i używać go na profilu osobistym (tzn. z tego samego profilu, na którym otrzymujesz SMS-y).

Sprawdź format, aby zobaczyć, czy SMS jest poprawnie sformatowany.

Czy ten interfejs API jest zgodny w różnych przeglądarkach?

Przeglądarka Chromium i WebKit uzgodniły format SMS-ów, a Apple ogłosił wprowadzenie obsługi tej przeglądarki Safari na urządzeniach z iOS 14 i macOS Big Sur. Chociaż Safari nie obsługuje interfejsu WebOTP JavaScript API, przez dodanie adnotacji input do elementu autocomplete=["one-time-code"] domyślna klawiatura automatycznie sugeruje wprowadzenie hasła jednorazowego, jeśli SMS jest zgodny z formatem.

Czy korzystanie z SMS-ów jako metody uwierzytelniania jest bezpieczne?

Hasło jednorazowe z SMS-a przydaje się do weryfikacji numeru telefonu przy pierwszym podaniu numeru, jednak do ponownego uwierzytelnienia należy ostrożnie używać weryfikacji za pomocą SMS-a, ponieważ operatorzy mogą zhakować i ponownie wykorzystać numery telefonów. WebOTP to wygodny mechanizm ponownego uwierzytelniania i przywracania danych, ale usługi powinny połączyć go z dodatkowymi czynnikami, takimi jak test wiedzy, lub korzystać z interfejsu Web Uwierzytelnianie API w celu silnego uwierzytelniania.

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

Czy wystąpił błąd w implementacji Chrome?

Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtwarzania i ustaw Komponenty na Blink>WebOTP.

Jak mogę pomóc w tej funkcji?

Czy zamierzasz używać interfejsu WebOTP API? Twoja publiczna pomoc pomoże nam nadać priorytet funkcjom, a inni dostawcy przeglądarek pokażą, jak ważne jest ich wsparcie. Wyślij tweeta na adres @ChromiumDev, używając hashtagu #WebOTP i daj nam znać, gdzie i jak go używasz.

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

Czym jest interfejs WebOTP API?

Zobacz, jak to działa

Dodaj adnotację do tagu <input>

Używanie interfejsu WebOTP API

Wykrywanie funkcji

Przetwarzanie hasła jednorazowego

Przerwanie wiadomości

Sformatuj SMS-a

Przykłady

Używanie WebOTP z międzyźródłowego elementu iframe

Dodaj adnotacje dotyczące źródeł powiązanych z SMS-em

Skonfiguruj zasadę uprawnień

Używaj WebOTP na komputerze

Najczęstsze pytania

Okno nie pojawia się, mimo że wysyłam prawidłowo sformatowaną wiadomość. Na czym polega problem?

Czy ten interfejs API jest zgodny w różnych przeglądarkach?

Czy korzystanie z SMS-ów jako metody uwierzytelniania jest bezpieczne?

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

Jak mogę pomóc w tej funkcji?

Zasoby

Dodaj adnotację do tagu `<input>`