Análisis detallado de las credenciales detectables

Eiji Kitamura
Maud Nalpas

Si bien las credenciales de FIDO, como las llaves de acceso, tienen como objetivo reemplazar las contraseñas, la mayoría de ellas también pueden evitar que el usuario tenga que escribir un nombre de usuario. Esto permite que los usuarios se autentiquen seleccionando una cuenta de una lista de llaves de acceso que tienen para el sitio web actual.

Las versiones anteriores de las llaves de seguridad se diseñaron como métodos de autenticación en 2 pasos y requerían los IDs de las credenciales potenciales, por lo que se debía ingresar un nombre de usuario. Las credenciales que una llave de seguridad puede encontrar sin conocer sus IDs se denominan credenciales detectables. La mayoría de las credenciales de FIDO que se crean hoy en día son credenciales detectables, en particular, las llaves de acceso almacenadas en un administrador de contraseñas o en una llave de seguridad moderna.

Para asegurarte de que tus credenciales se creen como llaves de acceso (credenciales detectables), especifica residentKey y requireResidentKey cuando se cree la credencial.

Las partes de confianza (RP) pueden usar credenciales detectables omitiendo allowCredentials durante la autenticación con llave de acceso. En estos casos, el navegador o el sistema muestran al usuario una lista de llaves de acceso disponibles, identificadas por la propiedad user.name establecida en el momento de la creación. Si el usuario selecciona uno, el valor user.id se incluirá en la firma resultante. Luego, el servidor puede usar ese ID o el ID de credencial devuelto para buscar la cuenta en lugar de un nombre de usuario escrito.

Las IU del selector de cuentas, como las que se mencionaron antes, nunca muestran credenciales no detectables.

requireResidentKey y residentKey

Para crear una llave de acceso, especifica authenticatorSelection.residentKey y authenticatorSelection.requireResidentKey en navigator.credentials.create() con los valores que se indican a continuación.

async function register () {
  // ...

  const publicKeyCredentialCreationOptions = {
    // ...
    authenticatorSelection: {
      authenticatorAttachment: 'platform',
      residentKey: 'required',
      requireResidentKey: true,
    }
  };

  const credential = await navigator.credentials.create({
    publicKey: publicKeyCredentialCreationOptions
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;

  // ...
}

residentKey:

  • 'required': Se debe crear una credencial detectable. Si no se puede crear, se devuelve NotSupportedError.
  • 'preferred': La RP prefiere crear una credencial detectable, pero acepta una no detectable.
  • 'discouraged': La RP prefiere crear una credencial no detectable, pero acepta una credencial detectable.

requireResidentKey:

  • Esta propiedad se conserva para la retrocompatibilidad con WebAuthn nivel 1, una versión anterior de la especificación. Establece este valor en true si residentKey es 'required'; de lo contrario, establécelo en false.

allowCredentials

Las RP pueden usar allowCredentials en navigator.credentials.get() para controlar la experiencia de autenticación con llaves de acceso. Por lo general, existen tres tipos de experiencias de autenticación con llaves de acceso:

Con las credenciales detectables, las RP pueden mostrar un selector de cuentas modal para que el usuario seleccione una cuenta con la que acceder, seguido de la verificación del usuario. Esto es adecuado para el flujo de autenticación con llave de acceso que se inicia presionando un botón dedicado a la autenticación con llave de acceso.

Para lograr esta experiencia del usuario, omite o pasa un array vacío al parámetro allowCredentials en navigator.credentials.get().

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

Muestra un autocompletado de formulario de llave de acceso

El selector de cuentas modal descrito anteriormente funciona bien si la mayoría de los usuarios usan llaves de acceso y las tienen disponibles en el dispositivo local. En el caso de un usuario que no tiene llaves de acceso locales, el diálogo modal seguirá apareciendo y le ofrecerá presentar una llave de acceso de otro dispositivo. Mientras realizas la transición de tus usuarios a las llaves de acceso, es posible que quieras evitar esa IU para los usuarios que no hayan configurado una.

En su lugar, la selección de una llave de acceso se puede incorporar en las indicaciones de autocompletado para los campos de un formulario de acceso tradicional, junto con los nombres de usuario y las contraseñas guardados. De esta manera, un usuario con llaves de acceso puede "completar" el formulario de acceso seleccionando su llave de acceso, los usuarios con pares de nombre de usuario y contraseña guardados pueden seleccionarlos, y los usuarios que no tengan ninguno de los dos pueden escribir su nombre de usuario y contraseña.

Esta experiencia del usuario es ideal cuando la RP se encuentra en una migración con un uso mixto de contraseñas y llaves de acceso.

Para lograr esta experiencia del usuario, además de pasar un array vacío a la propiedad allowCredentials o de omitir el parámetro, especifica mediation: 'conditional' en navigator.credentials.get() y anota un campo de entrada username de HTML con autocomplete="username webauthn" o un campo de entrada password con autocomplete="password webauthn".

La llamada a navigator.credentials.get() no hará que se muestre ninguna IU, pero si el usuario se enfoca en el campo de entrada anotado, las llaves de acceso disponibles se incluirán en las opciones de autocompletado. Si el usuario selecciona una, pasará por la verificación habitual de desbloqueo del dispositivo y, solo entonces, la promesa que devuelve .get() se resolverá con un resultado. Si el usuario no selecciona una llave de acceso, la promesa nunca se resuelve.

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const cred = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal,
    // Specify 'conditional' to activate conditional UI
    mediation: 'conditional'
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

<input type="text" name="username" autocomplete=&qu>ot;username webauthn" ...

Puedes aprender a compilar esta experiencia del usuario en Accede con una llave de acceso a través del autocompletado de formularios, así como en el codelab Implementa llaves de acceso con el autocompletado de formularios en una app web.

Reautenticación

En algunos casos, como cuando se usan llaves de acceso para volver a autenticar, ya se conoce el identificador del usuario. En este caso, nos gustaría usar una llave de acceso sin que el navegador o el SO muestren ningún tipo de selector de cuentas. Para ello, pasa una lista de IDs de credenciales en el parámetro allowCredentials.

En ese caso, si alguna de las credenciales con nombre está disponible de forma local, se le solicitará al usuario que desbloquee el dispositivo de inmediato. De lo contrario, se le solicitará al usuario que presente otro dispositivo (un teléfono o una llave de seguridad) que contenga una credencial válida.

Para lograr esta experiencia del usuario, proporciona una lista de IDs de credenciales para el usuario que accede. La RP debería poder consultarlas porque el usuario ya es conocido. Proporciona los IDs de credenciales como objetos PublicKeyCredentialDescriptor en la propiedad allowCredentials de navigator.credentials.get().

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // Provide a list of PublicKeyCredentialDescriptors:
    allowCredentials: [{
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, {
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, ...]
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

Un objeto PublicKeyCredentialDescriptor consta de lo siguiente:

  • id: Es un ID de la credencial de clave pública que la RP obtuvo en el registro de la llave de acceso.
  • type: Por lo general, este campo es 'public-key'.
  • transports: Es una sugerencia de los transportes que admite el dispositivo que contiene esta credencial, que usan los navegadores para optimizar la IU que le solicita al usuario que presente un dispositivo externo. Si se proporciona, esta lista debe contener el resultado de la llamada a getTransports() durante el registro de cada credencial.

Resumen

Las credenciales detectables hacen que la experiencia de acceso con llave de acceso sea mucho más fácil de usar, ya que permiten que los usuarios omitan el ingreso de un nombre de usuario. Con la combinación de residentKey, requireResidentKey y allowCredentials, las RP pueden lograr experiencias de acceso que:

  • Muestra un selector de cuentas modal.
  • Muestra un autocompletado de formulario de llave de acceso.
  • Reautenticación.

Usa las credenciales detectables con prudencia. De esta manera, puedes diseñar experiencias de acceso con llaves de acceso sofisticadas que los usuarios encontrarán fluidas y con las que tendrán más probabilidades de interactuar.