Discoverable credentials deep dive

Eiji Kitamura

Maud Nalpas

While FIDO credentials such as passkeys aim to replace passwords, most of them can also free the user from typing in a username. This enables users to authenticate by selecting an account from a list of passkeys they have for the current website.

Earlier versions of security keys were designed as 2-step authentication methods, and required the IDs of potential credentials, thus requiring entry of a username. Credentials that a security key can find without knowing their IDs are called discoverable credentials. Most FIDO credentials created today are discoverable credentials; particularly passkeys stored in a password manager or on a modern security key.

To ensure your credentials are created as passkeys (discoverable credentials), specify residentKey and requireResidentKey when the credential is created.

Relying parties (RPs) can use discoverable credentials by omitting allowCredentials during passkey authentication. In these cases, the browser or system show the user a list of available passkeys, identified by the user.name property set at creation time. If the user selects one, the user.id value will be included in the resulting signature. The server can then use that or the returned credential ID to look up the account instead of a typed username.

Account selector UIs, like the ones discussed earlier, never show non-discoverable credentials.

requireResidentKey and residentKey

To create a passkey, specify authenticatorSelection.residentKey and authenticatorSelection.requireResidentKey on navigator.credentials.create() with the values indicated as follows.

async function register () {
  // ...

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

  const credential =