Verifica i numeri di telefono sul web con l'API WebOTP

Aiutare gli utenti con le OTP ricevute tramite SMS

Eiji Kitamura

Che cos'è l'API WebOTP?

Oggigiorno, la maggior parte delle persone nel mondo possiede un dispositivo mobile e gli sviluppatori spesso utilizzano i numeri di telefono come identificatore per gli utenti dei loro servizi.

Esistono diversi modi per verificare i numeri di telefono, ma una password monouso (OTP) generata in modo casuale inviata tramite SMS è una delle più comuni. L'invio di questo codice al server dello sviluppatore dimostra il controllo del numero di telefono.

Questa idea è già implementata in molti scenari per ottenere:

  • Numero di telefono come identificatore dell'utente. Quando ti registri a un nuovo servizio, alcuni siti web chiedono un numero di telefono anziché un indirizzo email e lo utilizzano come identificatore dell'account.
  • Verifica in due passaggi. Al momento dell'accesso, un sito web richiede un codice una tantum inviato tramite SMS oltre a una password o un altro fattore di conoscenza per una maggiore sicurezza.
  • Conferma del pagamento. Quando un utente effettua un pagamento, chiedere un codice una tantum inviato tramite SMS può contribuire a verificare le intenzioni della persona.

L'attuale procedura crea attriti per gli utenti. Trovare un'OTP all'interno di un messaggio SMS, copiarla e incollarla nel modulo è complicato e riduce i tassi di conversione nei percorsi degli utenti critici. Simplificare questa operazione è stata una richiesta di lunga data per il web da parte di molti dei più grandi sviluppatori a livello mondiale. Android dispone di un'API che fa esattamente questo. Così come iOS e Safari.

L'API WebOTP consente alla tua app di ricevere messaggi con un formato speciale associati al dominio della tua app. In questo modo, puoi ottenere OTP in modo programmatico da un messaggio SMS e verificare più facilmente un numero di telefono per l'utente.

Guarda come funziona

Supponiamo che un utente voglia verificare il proprio numero di telefono con un sito web. Il sito web invia un messaggio all'utente tramite SMS e l'utente inserisce l'OTP contenuta nel messaggio per verificare la proprietà del numero di telefono.

Con l'API WebOTP, questi passaggi sono semplici come un tocco per l'utente, come dimostrato nel video. Quando arriva il messaggio, viene visualizzato un riquadro in basso che chiede all'utente di verificare il proprio numero di telefono. Dopo aver fatto clic sul pulsante Verifica nel foglio in basso, il browser incolla l'OTP nel modulo e il modulo viene inviato senza che l'utente debba premere Continua.

L'intera procedura è illustrata nel diagramma seguente.

Diagramma dell'API WebOTP

Prova la demo. Non ti chiede il tuo numero di telefono né invia un SMS al tuo dispositivo, ma puoi inviarne uno da un altro dispositivo copiando il testo visualizzato nella demo. Questo funziona perché non importa chi sia il mittente quando si utilizza l'API WebOTP.

  1. Vai alla pagina https://web-otp.glitch.me in Chrome 84 o versioni successive su un dispositivo Android.
  2. Invia al tuo smartphone il seguente messaggio SMS da un altro smartphone.
Your OTP is: 123456.

@web-otp.glitch.me #12345

Hai ricevuto l\'SMS e hai visualizzato la richiesta di inserimento del codice nell\'area di immissione? Questo è il funzionamento dell'API WebOTP per gli utenti.

L'utilizzo dell'API WebOTP è costituito da tre parti:

  • Un tag <input> annotato correttamente
  • JavaScript nella tua app web
  • Testo del messaggio formattato inviato tramite SMS.

Parleremo prima del tag <input>.

Annotare un tag <input>

WebOTP funziona senza alcuna annotazione HTML, ma per la compatibilità tra browser, ti consiglio vivamente di aggiungere autocomplete="one-time-code" al tag <input> in cui prevedi che l'utente inserisca un'OTP.

In questo modo, Safari 14 o versioni successive può suggerire all'utente di compilare automaticamente il campo <input> con una OTP quando riceve un SMS con il formato descritto in Formattare il messaggio SMS, anche se non supporta WebOTP.

HTML

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

Utilizzare l'API WebOTP

Poiché WebOTP è semplice, è sufficiente copiare e incollare il codice seguente. Ti spiegherò comunque cosa sta succedendo.

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

Rilevamento di funzionalità

Il rilevamento delle funzionalità è lo stesso di molte altre API. L'ascolto dell'eventoDOMContentLoaded attenderà che la struttura DOM sia pronta per la query.

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

Elabora l'OTP

L'API WebOTP stessa è abbastanza semplice. Utilizza navigator.credentials.get() per ottenere l'OTP. WebOTP aggiunge una nuova opzione otp a questo metodo. Ha solo una proprietà: transport, il cui valore deve essere un array con la stringa 'sms'.

JavaScript

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

Questo attiva il flusso di autorizzazione del browser quando arriva un messaggio SMS. Se l'autorizzazione viene concessa, la promessa restituita viene risolta con un oggetto OTPCredential.

Contenuti dell'oggetto OTPCredential ottenuto

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

Poi, passa il valore OTP al campo <input>. Se invii il modulo direttamente, viene eliminato il passaggio che richiede all'utente di toccare un pulsante.

JavaScript

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

Interrompere il messaggio

Se l'utente inserisce manualmente un'OTP e invia il modulo, puoi annullare la chiamataget() utilizzando un'istanza AbortController nell'oggetto 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 => {
    …

Formattare il messaggio SMS

L'API stessa dovrebbe sembrare abbastanza semplice, ma ci sono alcune cose che devi sapere prima di utilizzarla. Il messaggio deve essere inviato dopo la chiamata di navigator.credentials.get() e deve essere ricevuto sul dispositivo su cui è stata chiamata la funzione.get() Infine, il messaggio deve rispettare la seguente formattazione:

  • Il messaggio inizia con un testo (facoltativo) leggibile che contiene una stringa alfanumerica da quattro a dieci caratteri con almeno un numero, lasciando l'ultima riga per l'URL e l'OTP.
  • La parte di dominio dell'URL del sito web che ha richiamato l'API deve essere preceduta da @.
  • L'URL deve contenere il simbolo del cancelletto ("#") seguito dall'OTP.

Ad esempio:

Your OTP is: 123456.

@www.example.com #123456

Ecco alcuni esempi sbagliati:

Esempio di testo SMS con formato non corretto Perché non funziona
Here is your code for @example.com #123456 @ dovrebbe essere il primo carattere dell'ultima riga.
Your code for @example.com is #123456 @ dovrebbe essere il primo carattere dell'ultima riga.
Your verification code is 123456

@example.com\t#123456		 È previsto un singolo spazio tra @host e #code.
Your verification code is 123456

@example.com  #123456		 È previsto un singolo spazio tra @host e #code.
Your verification code is 123456

@ftp://example.com #123456		 Non è possibile includere lo schema dell'URL.
Your verification code is 123456

@https://example.com #123456		 Non è possibile includere lo schema dell'URL.
Your verification code is 123456

@example.com:8080 #123456		 La porta non può essere inclusa.
Your verification code is 123456

@example.com/foobar #123456		 Il percorso non può essere incluso.
Your verification code is 123456

@example .com #123456		 Nessuno spazio nel dominio.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 Nessun carattere vietato nel dominio.
@example.com #123456

Mambo Jumbo		 @host e #code dovrebbero essere l'ultima riga.
@example.com #123456

App hash #oudf08lkjsdf834		 @host e #code dovrebbero essere l'ultima riga.
Your verification code is 123456

@example.com 123456		 # mancante.
Your verification code is 123456

example.com #123456		 @ mancante.
Hi mom, did you receive my last text @ e # mancanti.

Demo

Prova vari messaggi con la demo: https://web-otp.glitch.me

Puoi anche creare un fork e creare la tua versione: https://glitch.com/edit/#!/web-otp.

Utilizzare WebOTP da un iframe cross-origin

L'inserimento di un'OTP via SMS in un iframe cross-origin viene in genere utilizzato per la conferma del pagamento, in particolare con 3D Secure. Avendo il formato comune per supportare gli iframe cross-origin, l'API WebOTP fornisce OTP legate a origini nidificate. Ad esempio:

  • Un utente visita il sito shop.example per acquistare un paio di scarpe con una carta di credito.
  • Dopo aver inserito il numero della carta di credito, il fornitore di servizi di pagamento integrato mostra un form di bank.example all'interno di un iframe che chiede all'utente di verificare il suo numero di telefono per il pagamento rapido.
  • bank.example invia all'utente un SMS contenente un'OTP che può inserire per verificare la propria identità.

Per utilizzare l'API WebOTP da un iframe cross-origin, devi fare due cose:

  • Aggiungi annotazioni sia all'origine del frame principale sia all'origine dell'iframe nel messaggio di testo SMS.
  • Configura il criterio di autorizzazione per consentire all'iframe cross-origin di ricevere l'OTP direttamente dall'utente.
API WebOTP in un iframe in azione.

Puoi provare la demo all'indirizzo https://web-otp-iframe-demo.stackblitz.io.

Aggiungi annotazioni alle origini vincolate al messaggio SMS

Quando l'API WebOTP viene chiamata da un iframe, il messaggio SMS deve includere l'origine del frame principale preceduta da @, seguita dall'OTP preceduta da # e l'origine dell'iframe preceduta da @ nell'ultima riga.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Configura il criterio relativo alle autorizzazioni

Per utilizzare WebOTP in un iframe cross-origin, l'utente che esegue l'embed deve concedere l'accesso a questa API tramite le norme relative alle autorizzazioni otp-credentials per evitare comportamenti indesiderati. In generale, esistono due modi per raggiungere questo obiettivo:

tramite intestazione HTTP:

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

tramite l'attributo iframe allow:

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

Consulta altri esempi su come specificare un criterio di autorizzazione .

Utilizzare WebOTP su computer

In Chrome, WebOTP supporta l'ascolto degli SMS ricevuti su altri dispositivi per aiutare gli utenti a completare la verifica del numero di telefono su computer.

API WebOTP su computer.

Questa funzionalità richiede che l'utente acceda allo stesso Account Google sia su Chrome per computer sia su Chrome per Android.

Gli sviluppatori devono semplicemente implementare l'API WebOTP sul proprio sito web desktop, come fanno sul sito web mobile, senza dover seguire procedure particolari.

Scopri di più su come verificare un numero di telefono su computer utilizzando l'API WebOTP.

Domande frequenti

La finestra di dialogo non viene visualizzata anche se invio un messaggio formattato correttamente. Che sta succedendo?

Esistono alcune avvertenze da tenere presente durante il test dell'API:

  • Se il numero di telefono del mittente è incluso nell'elenco contatti del destinatario, questa API non verrà attivata a causa del design dell'API SMS User Consent sottostante.
  • Se utilizzi un profilo di lavoro sul tuo dispositivo Android e WebOTP non funziona, prova a installare e utilizzare Chrome sul tuo profilo personale (ovvero lo stesso profilo in cui ricevi i messaggi SMS).

Torna al formato per verificare se l'SMS è formattato correttamente.

Questa API è compatibile tra browser diversi?

Chromium e WebKit hanno concordato sul formato dei messaggi SMS e Apple ha annunciato il supporto di Safari a partire da iOS 14 e macOS Big Sur. Anche se Safari non supporta l'API JavaScript WebOTP, se annoti l'elemento input con autocomplete=["one-time-code"], la tastiera predefinita suggerisce automaticamente di inserire l'OTP se il messaggio SMS è conforme al formato.

È sicuro utilizzare l'SMS come metodo di autenticazione?

Sebbene l'OTP via SMS sia utile per verificare un numero di telefono quando viene fornito per la prima volta, la verifica del numero di telefono tramite SMS deve essere utilizzata con cautela per la nuova autenticazione, poiché i numeri di telefono possono essere compromessi e riutilizzati dagli operatori. WebOTP è un pratico meccanismo di autenticazione e recupero, ma i servizi devono combinarlo con fattori aggiuntivi, come un test di conoscenza, o utilizzare l'API Web Authentication per l'autenticazione avanzata.

Dove posso segnalare i bug nell'implementazione di Chrome?

Hai trovato un bug nell'implementazione di Chrome?

  • Segnala un bug all'indirizzo crbug.com. Includi il maggior numero possibile di dettagli, istruzioni semplici per la riproduzione e imposta Componenti su Blink>WebOTP.

Come posso contribuire a migliorare questa funzionalità?

Intendi utilizzare l'API WebOTP? Il tuo supporto pubblico ci aiuta a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto sia fondamentale supportarle. Invia un tweet all'account @ChromiumDev utilizzando l'hashtag #WebOTP e facci sapere dove e come lo stai utilizzando.

Risorse