Se usó la API de Cloud Translation para traducir esta página.

Verifica números de teléfono en la Web con la API de WebOTP

Ayudar a los usuarios con OTP recibidos por SMS

Eiji Kitamura

Twitter GitHub Glitch Mastodon

¿Qué es la API de WebOTP?

En la actualidad, la mayoría de las personas en el mundo tienen dispositivos móviles, y los desarrolladores suelen usar números de teléfono como identificadores para los usuarios de sus servicios.

Hay varias formas de verificar números de teléfono, pero una contraseña de un solo uso (OTP) generada al azar que se envía por SMS es una de las más comunes. El envío de este código al servidor del desarrollador demuestra el control del número de teléfono.

Esta idea ya se implementa en muchas situaciones que se pueden lograr:

Número de teléfono como identificador del usuario. Cuando se registran en un servicio nuevo, algunos sitios web solicitan un número de teléfono en lugar de una dirección de correo electrónico y lo usan como identificador de cuenta.
Verificación en dos pasos. Cuando accedes, un sitio web solicita un código único que se envía por SMS, además de una contraseña o algún otro factor de conocimiento para mayor seguridad.
Confirmación del pago. Cuando un usuario realiza un pago, solicitar un código único que se envía por SMS puede ayudar a verificar la intención de la persona.

El proceso actual crea inconvenientes para los usuarios. Encontrar una OTP dentro de un mensaje SMS y, luego, copiarla y pegarla en el formulario es engorroso, ya que disminuye los porcentajes de conversiones en los recorridos críticos del usuario. Facilitamos que muchos de los desarrolladores mundiales más grandes nos hayan enviado una solicitud para la Web desde hace mucho tiempo. Android tiene una API que hace exactamente esto. iOS y Safari también lo hacen.

La API de WebOTP permite que tu app reciba mensajes con formato especial vinculados al dominio de tu app. De esta manera, puedes obtener de manera programática una OTP a partir de un mensaje SMS y verificar el número de teléfono del usuario con mayor facilidad.

Observa cómo funciona

Supongamos que un usuario desea verificar su número de teléfono con un sitio web. El sitio web envía un mensaje de texto al usuario por SMS y este ingresa la OTP del mensaje para verificar la propiedad del número de teléfono.

Con la API de WebOTP, estos pasos son tan sencillos como presionar un botón para el usuario, como se muestra en el video. Cuando llega el mensaje de texto, aparece una hoja inferior que le solicita al usuario que verifique su número de teléfono. Después de hacer clic en el botón Verificar de la hoja inferior, el navegador pega la OTP en el formulario y este se envía sin que el usuario tenga que presionar Continuar.

En la imagen de abajo, se muestra un diagrama de todo el proceso.

Prueba la demostración. No se te solicita tu número de teléfono ni se envía un SMS a tu dispositivo, pero puedes enviar uno desde otro dispositivo copiando el texto que aparece en la demostración. Esto funciona porque no importa quién es el remitente cuando usas la API de WebOTP.

Ve a https://web-otp.glitch.me en Chrome 84 o versiones posteriores en un dispositivo Android.
Envía el siguiente mensaje de texto SMS a tu teléfono desde el otro teléfono.

Your OTP is: 123456.

@web-otp.glitch.me #12345

¿Recibiste el SMS y viste el aviso para ingresar el código en el área de entrada? Así es como la API de WebOTP funciona para los usuarios.

El uso de la API de WebOTP consta de tres partes:

Una etiqueta <input> anotada correctamente
JavaScript en tu app web
Texto de mensaje con formato enviado por SMS.

Primero, abordaremos la etiqueta <input>.

Anota una etiqueta `<input>`

WebOTP funciona sin ninguna anotación HTML, pero para lograr la compatibilidad entre navegadores, te recomendamos que agregues autocomplete="one-time-code" a la etiqueta <input> en la que esperas que el usuario ingrese una OTP.

Esto permite que Safari 14 o versiones posteriores sugieran que el usuario complete el campo <input> con una OTP cuando reciba un SMS con el formato descrito en Cómo darle formato al mensaje SMS, aunque no sea compatible con WebOTP.

HTML

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

Usa la API de WebOTP

Como WebOTP es sencillo, basta con copiar y pegar el siguiente código. De todos modos, te explicaré lo que sucede.

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

Detección de atributos

La detección de funciones es la misma que para muchas otras APIs. Si escuchas el evento DOMContentLoaded, se esperará a que el árbol del DOM esté listo para la consulta.

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

Cómo procesar la OTP

La API de WebOTP en sí es bastante simple. Usa navigator.credentials.get() para obtener la OTP. WebOTP agrega una opción otp nueva a ese método. Solo tiene una propiedad: transport, cuyo valor debe ser un array con la string 'sms'.

JavaScript

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

Esto activa el flujo de permisos del navegador cuando llega un mensaje SMS. Si se otorga el permiso, la promesa que se muestra se resuelve con un objeto OTPCredential.

Contenido del objeto OTPCredential obtenido

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

A continuación, pasa el valor de OTP al campo <input>. Si envías el formulario directamente, se eliminará el paso que requiere que el usuario presione un botón.

JavaScript

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

Anulando el mensaje

En caso de que el usuario ingrese manualmente una OTP y envíe el formulario, puedes cancelar la llamada a get() mediante una instancia de AbortController en el objeto 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 => {
    …

Dar formato al mensaje SMS

La API en sí debe parecer bastante simple, pero hay algunos aspectos que debes conocer antes de usarla. El mensaje debe enviarse después de que se llame a navigator.credentials.get() y debe recibirse en el dispositivo en el que se llamó a get(). Por último, el mensaje debe cumplir con el siguiente formato:

El mensaje comienza con un texto legible (opcional) que contiene una cadena alfanumérica de entre cuatro y diez caracteres, y al menos un número deja la última línea de la URL y la OTP.
La parte del dominio de la URL del sitio web que invocó la API debe estar precedida por @.
La URL debe contener un signo numeral ("#") seguido de la OTP.

Por ejemplo:

Your OTP is: 123456.

@www.example.com #123456

Los siguientes son malos ejemplos:

Ejemplo de texto de SMS con errores de formato	Por qué no funcionará
`Here is your code for @example.com #123456`	Se espera que `@` sea el primer carácter de la última línea.
`Your code for @example.com is #123456`	Se espera que `@` sea el primer carácter de la última línea.
`Your verification code is 123456` `@example.com\t#123456`	Se espera un solo espacio entre `@host` y `#code`.
`Your verification code is 123456` `@example.com` `#123456`	Se espera un solo espacio entre `@host` y `#code`.
`Your verification code is 123456` `@ftp://example.com #123456`	No se puede incluir el esquema de URL.
`Your verification code is 123456` `@https://example.com #123456`	No se puede incluir el esquema de URL.
`Your verification code is 123456` `@example.com:8080 #123456`	No se puede incluir el puerto.
`Your verification code is 123456` `@example.com/foobar #123456`	No se puede incluir la ruta de acceso.
`Your verification code is 123456` `@example .com #123456`	No hay espacios en blanco en el dominio.
`Your verification code is 123456` `@domain-forbiden-chars-#%/:<>?@[] #123456`	No hay caracteres prohibidos en el dominio.
`@example.com #123456` `Mambo Jumbo`	Se espera que `@host` y `#code` sean la última línea.
`@example.com #123456` `App hash #oudf08lkjsdf834`	Se espera que `@host` y `#code` sean la última línea.
`Your verification code is 123456` `@example.com 123456`	Falta `#`.
`Your verification code is 123456` `example.com #123456`	Falta `@`.
`Hi mom, did you receive my last text`	Faltan `@` y `#`.

Demostraciones

Prueba varios mensajes con la demostración: https://web-otp.glitch.me.

También puedes bifurcarlo y crear tu versión: https://glitch.com/edit/#!/web-otp.

Cómo usar WebOTP desde un iframe de origen cruzado

Por lo general, para confirmar el pago se ingresa una OTP de SMS a un iframe de origen cruzado, en especial con 3D Secure. Con el formato común para admitir iframes de origen cruzado, la API de WebOTP entrega OTP vinculadas a orígenes anidados. Por ejemplo:

Un usuario visita shop.example para comprar un par de zapatos con una tarjeta de crédito.
Después de ingresar el número de la tarjeta de crédito, el proveedor de pagos integrado muestra un formulario de bank.example dentro de un iframe en el que se le solicita al usuario que verifique su número de teléfono para una confirmación rápida de la compra.
bank.example envía un SMS que contiene una OTP al usuario para que pueda ingresarlo y verificar su identidad.

Para usar la API de WebOTP desde un iframe de origen cruzado, debes hacer dos cosas:

Anota el origen del marco superior y el origen del iframe en el mensaje de texto SMS.
Configura la política de permisos para permitir que el iframe de origen cruzado reciba una OTP directamente del usuario.

API de WebOTP dentro de un iframe en acción

Puedes probar la demostración en https://web-otp-iframe-demo.stackblitz.io.

Anota los orígenes vinculados al mensaje de texto SMS

Cuando se llama a la API de WebOTP desde un iframe, el mensaje de texto SMS debe incluir el origen del marco superior precedido por @ seguido de la OTP precedida por # y el origen del iframe precedido por @ en la última línea.

Your verification code is 123456

@shop.example #123456 @bank.exmple

Configurar la política de permisos

Para usar WebOTP en un iframe de origen cruzado, el incorporador debe otorgar acceso a esta API a través de la política de permisos de otp-credentials para evitar comportamientos no deseados. En general, hay dos formas de lograr este objetivo:

a través del encabezado HTTP:

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

mediante el atributo allow de iframe:

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

Consulta más ejemplos sobre cómo especificar una política de permisos .

Nota: Por el momento, Chrome solo admite llamadas a la API de WebOTP desde iframes de origen cruzado que no tengan más de un origen único en su cadena principal. En los siguientes casos: <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> Se admite el uso de WebOTP en b.com, pero no en c.com. Ten en cuenta que la siguiente situación tampoco se admite debido a la falta de demanda y complejidades de UX. <ul> <li>a.com -> b.com -> a.com (llama a la API de WebOTP)</li> </ul>

Usa WebOTP en una computadora

En Chrome, WebOTP admite la detección de SMS recibidos en otros dispositivos para ayudar a los usuarios a completar la verificación del número de teléfono en computadoras de escritorio.

API de WebOTP en computadoras de escritorio.

Esta función requiere que el usuario acceda a la misma Cuenta de Google en la versión de Chrome para computadoras de escritorio y en Android.

Todo lo que los desarrolladores deben hacer es implementar la API de WebOTP en su sitio web para computadoras de escritorio, de la misma manera que en su sitio web móvil, pero no se requieren trucos especiales.

Obtén más información en Cómo verificar un número de teléfono en una computadora de escritorio con la API de WebOTP.

Preguntas frecuentes

El cuadro de diálogo no aparece aunque envío un mensaje con el formato correcto. ¿Cuál es el problema?

Ten en cuenta las siguientes advertencias cuando pruebes la API:

Si el número de teléfono del remitente se incluye en la lista de contactos del destinatario, no se activará la API debido al diseño de la API de consentimiento del usuario de SMS subyacente.
Si usas un perfil de trabajo en tu dispositivo Android y WebOTP no funciona, intenta instalar y usar Chrome en tu perfil personal (es decir, el mismo perfil en el que recibes los mensajes SMS).

Vuelve a consultar el formato para ver si el SMS tiene el formato correcto.

¿Esta API es compatible con distintos navegadores?

Chromium y WebKit acordaron el formato de los mensajes de texto SMS y Apple anunció la compatibilidad de Safari para este a partir de iOS 14 y macOS Big Sur. Si bien Safari no admite la API de WebOTP de JavaScript, cuando se anota el elemento input con autocomplete=["one-time-code"], el teclado predeterminado sugiere automáticamente que ingreses la OTP si el mensaje SMS cumple con el formato.

¿Es seguro usar SMS como método de autenticación?

Si bien la OTP por SMS es útil para verificar un número de teléfono cuando se proporciona por primera vez, la verificación del número de teléfono mediante SMS se debe usar con cuidado para la reautenticación, ya que los operadores pueden usurpar y reciclar los números de teléfono. WebOTP es un mecanismo de reautenticación y recuperación conveniente, pero los servicios deben combinarlo con factores adicionales, como un desafío de conocimiento, o usar la API de Web Authentication para una autenticación sólida.

¿Dónde puedo informar errores en la implementación de Chrome?

¿Encontraste un error en la implementación de Chrome?

Informa el error en https://new.crbug.com. Incluye todos los detalles que puedas, instrucciones simples para la reproducción y establece los Componentes en Blink>WebOTP.

¿Cómo te puedo ayudar con esta función?

¿Piensas usar la API de WebOTP? Tu apoyo público nos ayuda a priorizar funciones y les muestra a otros proveedores de navegadores lo importante que es admitirlas. Envía un tweet a @ChromiumDev con el hashtag #WebOTP y cuéntanos dónde y cómo lo estás usando.

Verifica números de teléfono en la Web con la API de WebOTP

¿Qué es la API de WebOTP?

Observa cómo funciona

Anota una etiqueta <input>

Usa la API de WebOTP

Detección de atributos

Cómo procesar la OTP

Anulando el mensaje

Dar formato al mensaje SMS

Demostraciones

Cómo usar WebOTP desde un iframe de origen cruzado

Anota los orígenes vinculados al mensaje de texto SMS

Configurar la política de permisos

Usa WebOTP en una computadora

Preguntas frecuentes

El cuadro de diálogo no aparece aunque envío un mensaje con el formato correcto. ¿Cuál es el problema?

¿Esta API es compatible con distintos navegadores?

¿Es seguro usar SMS como método de autenticación?

¿Dónde puedo informar errores en la implementación de Chrome?

¿Cómo te puedo ayudar con esta función?

Recursos

Anota una etiqueta `<input>`