Credentials
What is a credential?
In general, FIDO2 works by using public/private key pairs that are generated by a FIDO2 authenticator. The private key is protected by the authenticator, and the public key is stored server-side by the Relying Party (RP). The authenticator uses the private key to sign challenges from a RP, and the RP uses the public key to verify the signature.
According to the WebAuthn specification, a credential is data one entity presents to another in order to authenticate the former to the latter. What the term "credential" refers to is generally determined by context, and can be one of the following:
- A public key credential source
- The data structure that is protected by the authenticator, including the private key, and any metadata that is associated with it. For more information see Public Key Credential Source.
- The attested credential public key (corresponding to a public key credential source)
- The public key that is stored server-side by the RP.
- An authentication assertion
- The data structure that contains a cryptographic signature.
In this documentation, the term "credential" refers to the public key credential source i.e. the private key plus metadata.
Data structure
Required fields
Credentials are relatively simple data structures and only require the following fields:
credentialId- Binary data sequence that uniquely identifies the credential. It is either a random value, or an encrypted version of the credential (see Storage Modes).rpId- The identifier of the RP for which the credential was created. By default assigned the effective domain of the application's origin (ex: bitwarden.com).privateKey- Private key material, created when generating the public/private key pair.
Notable optional fields
userHandle- Binary data sequence that uniquely identifies the user account. This data is opaque for anyone other than the RP. It is used to associate a credential with a specific user account.userName- A human-readable name for the user account. This can be used to display the user account in the authenticator's user interface (if supported).
Storage modality
Client-side credentials
The credential is stored in persistent storage embedded in the authenticator, client, or client device. This is rapidly becoming a common storage mode, as it is the only way to support synced credentials across multiple devices. Client-side storage is required.
Hardware security keys also support this storage mode, but they often have a limited capacity (e.g. the YubiKey 5 can hold up to 25 client-side credentials).
Server-side credentials
The credential is encrypted by the authenticator and stored in a database managed by the RP. This is the traditional storage mode and is often used in 2FA flows.
This enables the authenticator to have unlimited storage capacity for credentials, since the data is stored by the RP instead of by the authenticator. However, this means that a credential stored in this way must be retrieved from the RP before the authenticator can use it.
Discoverability
Non-discoverable credentials
This is a credential whose credentialId must be provided in allowCredentials when calling
navigator.credentials.get because it is not client-side discoverable. This is always the case when
the credential is stored server-side, because the RP must first identify the user in order to
discover the credentialId to supply in the navigator.credentials.get call.
Client-side discoverable credentials
These credentials have been previously known as resident credentials or resident keys. Due to the
phrases ResidentKey and residentKey being widely used in both the WebAuthn API and also in the
Authenticator Model (e.g. in dictionary member names, algorithm variable names, and operation
parameters) the usage of resident within their names has not been changed for backwards
compatibility purposes.
This credential is usable in authentication operations where the RP does not provide any
credentialId, meaning that the RP does not need to identify the user first.
As a result, an authenticator that can handle discoverable credentials can create assertion
signatures using just an rpId. This enables single-click authentication flows where the returned
assertion data contains everything the RP needs to identify and authenticate the user.
This implies that the source of the credential must be stored either in the authenticator or the client platform (see Client Side Credentials).
Storage vs discoverability matrix
As described above, there is a relationship between storage modality and discoverability. This can be condensed into the matrix below, which shows the supported combinations of the two.
| Non-Discoverable | Discoverable | |
|---|---|---|
| Client-Side | Supported | Supported |
| Server-Side | Supported | - |