Web Authentication:
An API for accessing Public Key Credentials
Level 3

1. Introduction

This section is not normative.

This specification defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users. A public key credential is created and stored by a WebAuthn Authenticator at the behest of a WebAuthn Relying Party, subject to user consent. Subsequently, the public key credential can only be accessed by origins belonging to that Relying Party. This scoping is enforced jointly by conforming User Agents and authenticators. Additionally, privacy across Relying Parties is maintained; Relying Parties are not able to detect any properties, or even the existence, of credentials scoped to other Relying Parties.

Relying Parties employ the Web Authentication API during two distinct, but related, ceremonies involving a user. The first is Registration, where a public key credential is created on an authenticator, and scoped to a Relying Party with the present user’s account (the account might already exist or might be created at this time). The second is Authentication, where the Relying Party is presented with an Authentication Assertion proving the presence and consent of the user who registered the public key credential. Functionally, the Web Authentication API comprises a PublicKeyCredential which extends the Credential Management API [CREDENTIAL-MANAGEMENT-1], and infrastructure which allows those credentials to be used with navigator.credentials.create() and navigator.credentials.get(). The former is used during Registration, and the latter during Authentication.

Broadly, compliant authenticators protect public key credentials, and interact with user agents to implement the Web Authentication API. Implementing compliant authenticators is possible in software executing (a) on a general-purpose computing device, (b) on an on-device Secure Execution Environment, Trusted Platform Module (TPM), or a Secure Element (SE), or (c) off device. Authenticators being implemented on device are called platform authenticators. Authenticators being implemented off device (roaming authenticators) can be accessed over a transport such as Universal Serial Bus (USB), Bluetooth Low Energy (BLE), or Near Field Communications (NFC).

1.1. Specification Roadmap

While many W3C specifications are directed primarily to user agent developers and also to web application developers (i.e., "Web authors"), the nature of Web Authentication requires that this specification be correctly used by multiple audiences, as described below.

All audiences ought to begin with § 1.2 Use Cases, § 1.3 Sample API Usage Scenarios, and § 4 Terminology, and should also refer to [WebAuthnAPIGuide] for an overall tutorial. Beyond that, the intended audiences for this document are the following main groups:

• Relying Party web application developers, especially those responsible for Relying Party web application login flows, account recovery flows, user account database content, etc.

• Web framework developers

  • The above two audiences should in particular refer to § 7 WebAuthn Relying Party Operations. The introduction to § 5 Web Authentication API may be helpful, though readers should realize that the § 5 Web Authentication API section is targeted specifically at user agent developers, not web application developers. Additionally, if they intend to verify authenticator attestations, then § 6.5 Attestation and § 8 Defined Attestation Statement Formats will also be relevant. § 9 WebAuthn Extensions, and § 10 Defined Extensions will be of interest if they wish to make use of extensions. Finally, they should read § 13.5 Security considerations for Relying Parties and § 14.6 Privacy considerations for Relying Parties and consider which challenges apply to their application and users.

• User agent developers

• OS platform developers, responsible for OS platform API design and implementation in regards to platform-specific authenticator APIs, platform WebAuthn Client instantiation, etc.

  • The above two audiences should read § 5 Web Authentication API very carefully, along with § 9 WebAuthn Extensions if they intend to support extensions. They should also carefully read § 14.5 Privacy considerations for clients.

• Authenticator developers. These readers will want to pay particular attention to § 6 WebAuthn Authenticator Model, § 8 Defined Attestation Statement Formats, § 9 WebAuthn Extensions, and § 10 Defined Extensions. They should also carefully read § 13.3 Security considerations for authenticators and § 14.4 Privacy considerations for authenticators.

1.2. Use Cases

The below use case scenarios illustrate use of two very different types of authenticators and credentials across two common deployment types, as well as outline further scenarios. Additional scenarios, including sample code, are given later in § 1.3 Sample API Usage Scenarios. These examples are for illustrative purposes only, and feature availability may differ between client and authenticator implementations.

1.2.1. Consumer with Multi-Device Credentials

This use case illustrates how a consumer-centric Relying Party can leverage the authenticator built-in to a user’s devices to provide phishing-resistant sign in using multi-device credentials (commonly referred to as synced passkeys).

1.2.1.1. Registration

• On a phone:

  • User navigates to example.com in a browser and signs in to an existing account using whatever method they have been using (possibly a legacy method such as a password), or creates a new account.

  • The phone prompts, "Do you want to create a passkey for example.com?"

  • User agrees.

  • The phone prompts the user for a previously configured authorization gesture (PIN, biometric, etc.); the user provides this.

  • Website shows message, "Registration complete."

1.2.1.2. Authentication

• On a laptop or desktop:

  • User navigates to example.com in a browser and initiates signing in.

  • If the multi-device credential (commonly referred to as a synced passkey) is available on the device:

    • The browser or operating system prompts the user for a previously configured authorization gesture (PIN, biometric, etc.); the user provides this.

    • Web page shows that the selected user is signed in, and navigates to the signed-in page.

  • If the synced passkey is not available on the device:

    • The browser or operating system prompts the user for an external authenticator, such as a phone or security key.

    • The user selects a previously linked phone.

• Next, on their phone:

  • User sees a discrete prompt or notification, "Sign in to example.com."

  • User selects this prompt / notification.

  • User is shown a list of their example.com identities, e.g., "Sign in as Mohamed / Sign in as 张三".

  • User picks an identity, is prompted for an authorization gesture (PIN, biometric, etc.) and provides this.

• Now, back on the laptop:

  • Web page shows that the selected user is signed in, and navigates to the signed-in page.

1.2.2. Workforce with Single-Device Credentials

This use case illustrates how a workforce-centric Relying Party can leverage a combination of a roaming authenticator (e.g., a USB security key) and a platform authenticator (e.g., a built-in fingerprint sensor) such that the user has:

• a "primary" roaming authenticator that they use to authenticate on new-to-them client devices (e.g., laptops, desktops) or on such client devices that lack a platform authenticator, and

• a low-friction means to strongly re-authenticate on client devices having platform authenticators, or

• a means to strongly re-authenticate on client devices having passkey platform authenticators which do not support single-device credentials (commonly referred to as device-bound passkeys).

1.2.2.1. Registration

In this example, the user’s employer mails a security key which is preconfigured with a device-bound passkey.

A temporary PIN was sent to the user out of band (e.g., via an RCS message).

1.2.2.2. Authentication

• On a laptop or desktop:

  • User navigates to corp.example.com in a browser and initiates signing in.

  • The browser or operating system prompts the user for their security key.

  • The user connects their USB security key.

  • The USB security key blinks to indicate the user should press the button on it; the user does.

  • The browser or operating system asks the user to enter their PIN.

  • The user enters the temporary PIN they were provided and continues.

  • The browser or operating system informs the user that they must change their PIN and prompts for a new one.

  • The user enters their new PIN and continues.

  • The browser or operating system restarts the authentication flow and asks the user to enter their PIN.

  • The user enters their new PIN and taps the security key.

  • Web page shows that the selected user is signed in, and navigates to the signed-in page.

1.2.3. Other Use Cases and Configurations

A variety of additional use cases and configurations are also possible, including (but not limited to):

• A user navigates to example.com on their laptop, is guided through a flow to create and register a credential on their phone.

• A user obtains a discrete, roaming authenticator, such as a security key with USB and/or NFC connectivity options, loads example.com in their browser on a laptop or phone, and is guided through a flow to create and register a credential on the security key.

• A Relying Party prompts the user for their authorization gesture in order to authorize a single transaction, such as a payment or other financial transaction.

1.3. Sample API Usage Scenarios

This section is not normative.

In this section, we walk through some events in the lifecycle of a public key credential, along with the corresponding sample code for using this API. Note that this is an example flow and does not limit the scope of how the API can be used.

As was the case in earlier sections, this flow focuses on a use case involving a passkey roaming authenticator with its own display. One example of such an authenticator would be a smart phone. Other authenticator types are also supported by this API, subject to implementation by the client platform. For instance, this flow also works without modification for the case of an authenticator that is embedded in the client device. The flow also works for the case of an authenticator without its own display (similar to a smart card) subject to specific implementation considerations. Specifically, the client platform needs to display any prompts that would otherwise be shown by the authenticator, and the authenticator needs to allow the client platform to enumerate all the authenticator’s credentials so that the client can have information to show appropriate prompts.

1.3.1. Registration

This is the first-time flow, in which a new credential is created and registered with the server. In this flow, the WebAuthn Relying Party does not have a preference for platform authenticator or roaming authenticators.

1. The user visits example.com, which serves up a script. At this point, the user may already be logged in using a legacy username and password, or additional authenticator, or other means acceptable to the Relying Party. Or the user may be in the process of creating a new account.

2. The Relying Party script runs the code snippet below.

3. The client platform searches for and locates the authenticator.

4. The client connects to the authenticator, performing any pairing actions if necessary.

5. The authenticator shows appropriate UI for the user to provide a biometric or other authorization gesture.

6. The authenticator returns a response to the client, which in turn returns a response to the Relying Party script. If the user declined to select an authenticator or provide authorization, an appropriate error is returned.

7. If a new credential was created,

   • The Relying Party script sends the newly generated credential public key to the server, along with additional information such as attestation regarding the provenance and characteristics of the authenticator.

   • The server stores the credential public key in its database and associates it with the user as well as with the characteristics of authentication indicated by attestation, also storing a friendly name for later use.

   • The script may store data such as the credential ID in local storage, to improve future UX by narrowing the choice of credential for the user.

The sample code for generating and registering a new key follows:

 windowPublicKeyCredential   

 publicKey  
 
 challenge  Uint8Array 

 
 rp 
 name 
 

 
 user 
 id Uint8Arraywindowatob cccharCodeAt
 name 
 displayName 
 

 
 
 pubKeyCredParams 
 
 type 
 alg  
 
 
 type 
 alg  
 
 
 type 
 alg  
 
 

 authenticatorSelection 
 
 userVerification 
 

 timeout  
 excludeCredentials 
 
  Uint8Arraywindowatob cccharCodeAt  
  Uint8Arraywindowatob cccharCodeAt  
 

 
 extensions  



navigatorcredentialscreate publicKey 
 then newCredentialInfo 
 
  err 
 
 

1.3.2. Registration Specifically with User-Verifying Platform Authenticator

This is an example flow for when the WebAuthn Relying Party is specifically interested in creating a public key credential with a user-verifying platform authenticator.

1. The user visits example.com and clicks on the login button, which redirects the user to login.example.com.

2. The user enters a username and password to log in. After successful login, the user is redirected back to example.com.

3. The Relying Party script runs the code snippet below.

   1. The user agent checks if a user-verifying platform authenticator is available. If not, terminate this flow.

   2. The Relying Party asks the user if they want to create a credential with it. If not, terminate this flow.

   3. The user agent and/or operating system shows appropriate UI and guides the user in creating a credential using one of the available platform authenticators.

   4. Upon successful credential creation, the Relying Party script conveys the new credential to the server.

 windowPublicKeyCredential   

PublicKeyCredentialisUserVerifyingPlatformAuthenticatorAvailable
 then uvpaAvailable 
 
  uvpaAvailable 
 
  askIfUserWantsToCreateCredential
 
 then userSaidYes 
 
 
  userSaidYes 
  publicKeyOptions   
  navigatorcredentialscreate  publicKeyOptions 
 
 then newCredentialInfo 
  newCredentialInfo 
 
 
  err 
 
 

1.3.3. Authentication

This is the flow when a user with an already registered credential visits a website and wants to authenticate using the credential.

1. The user visits example.com, which serves up a script.

2. The script asks the client for an Authentication Assertion, providing as much information as possible to narrow the choice of acceptable credentials for the user. This can be obtained from the data that was stored locally after registration, or by other means such as prompting the user for a username.

3. The Relying Party script runs one of the code snippets below.

4. The client platform searches for and locates the authenticator.

5. The client connects to the authenticator, performing any pairing actions if necessary.

6. The authenticator presents the user with a notification that their attention is needed. On opening the notification, the user is shown a friendly selection menu of acceptable credentials using the account information provided when creating the credentials, along with some information on the origin that is requesting these keys.

7. The authenticator obtains a biometric or other authorization gesture from the user.

8. The authenticator returns a response to the client, which in turn returns a response to the Relying Party script. If the user declined to select a credential or provide an authorization, an appropriate error is returned.

9. If an assertion was successfully generated and returned,

   • The script sends the assertion to the server.

   • The server examines the assertion, extracts the credential ID, looks up the registered credential public key in its database, and verifies the assertion signature. If valid, it looks up the identity associated with the assertion’s credential ID; that identity is now authenticated. If the credential ID is not recognized by the server (e.g., it has been deregistered due to inactivity) then the authentication has failed; each Relying Party will handle this in its own way.

   • The server now does whatever it would otherwise do upon successful authentication -- return a success page, set authentication cookies, etc.

If the Relying Party script does not have any hints available (e.g., from locally stored data) to help it narrow the list of credentials, then the sample code for performing such an authentication might look like this:

 windowPublicKeyCredential   


 credentialId   Uint8Array   
 options  
 
 challenge  Uint8Array 
 timeout  
 allowCredentials  type  id credentialId 


navigatorcredentialsget  options 
 then assertion 
 
 err 
 

On the other hand, if the Relying Party script has some hints to help it narrow the list of credentials, then the sample code for performing such an authentication might look like the following. Note that this sample also demonstrates how to use the Credential Properties Extension.

 windowPublicKeyCredential   

 encoder   TextEncoder
 acceptableCredential1  
 type 
 id encoderencode

 acceptableCredential2  
 type 
 id encoderencode


 options  
 
 challenge  Uint8Array 
 timeout  
 allowCredentials acceptableCredential1 acceptableCredential2
 extensions    


navigatorcredentialsget  options 
 then assertion 
 
 err 
 

1.3.4. Aborting Authentication Operations

The below example shows how a developer may use the AbortSignal parameter to abort a credential registration operation. A similar procedure applies to an authentication operation.

 authAbortController   AbortController
 authAbortSignal  authAbortControllersignal

authAbortSignalonabort    
 


 options  
 


navigatorcredentialscreate
 publicKey options
 signal authAbortSignal
 then attestation 
 
  error 
  errorname   
 
 
 
 


 widget   
 authAbortControllerabort

1.3.5. Decommissioning

The following are possible situations in which decommissioning a credential might be desired. Note that all of these are handled on the server side and do not need support from the API specified here.

• Possibility #1 -- user reports the credential as lost.

  • User goes to server.example.net, authenticates and follows a link to report a lost/stolen authenticator.

  • Server returns a page showing the list of registered credentials with friendly names as configured during registration.

  • User selects a credential and the server deletes it from its database.

  • In the future, the Relying Party script does not specify this credential in any list of acceptable credentials, and assertions signed by this credential are rejected.

• Possibility #2 -- server deregisters the credential due to inactivity.

  • Server deletes credential from its database during maintenance activity.

  • In the future, the Relying Party script does not specify this credential in any list of acceptable credentials, and assertions signed by this credential are rejected.

• Possibility #3 -- user deletes the credential from the authenticator.

  • User employs a authenticator-specific method (e.g., device settings UI) to delete a credential from their authenticator.

  • From this point on, this credential will not appear in any selection prompts, and no assertions can be generated with it.

  • Sometime later, the server deregisters this credential due to inactivity.

1.4. Platform-Specific Implementation Guidance

This specification defines how to use Web Authentication in the general case. When using Web Authentication in connection with specific platform support (e.g. apps), it is recommended to see platform-specific documentation and guides for additional guidance and limitations.

2. Conformance

This specification defines three conformance classes. Each of these classes is specified so that conforming members of the class are secure against non-conforming or hostile members of the other classes.

2.1. User Agents

A User Agent MUST behave as described by § 5 Web Authentication API in order to be considered conformant. Conforming User Agents MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification’s algorithms.

A conforming User Agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [WebIDL]

2.1.1. Enumerations as DOMString types

Enumeration types are not referenced by other parts of the Web IDL because that would preclude other values from being used without updating this specification and its implementations. It is important for backwards compatibility that client platforms and Relying Parties handle unknown values. Enumerations for this specification exist here for documentation and as a registry. Where the enumerations are represented elsewhere, they are typed as DOMStrings, for example in transports.

2.2. Authenticators

A WebAuthn Authenticator MUST provide the operations defined by § 6 WebAuthn Authenticator Model, and those operations MUST behave as described there. This is a set of functional and security requirements for an authenticator to be usable by a Conforming User Agent.

As described in § 1.2 Use Cases, an authenticator may be implemented in the operating system underlying the User Agent, or in external hardware, or a combination of both.

2.2.1. Backwards Compatibility with FIDO U2F

Authenticators that only support the § 8.6 FIDO U2F Attestation Statement Format have no mechanism to store a user handle, so the returned userHandle will always be null.

2.3. WebAuthn Relying Parties

A WebAuthn Relying Party MUST behave as described in § 7 WebAuthn Relying Party Operations to obtain all the security benefits offered by this specification. See § 13.5.1 Security Benefits for WebAuthn Relying Parties for further discussion of this.

2.4. All Conformance Classes

All CBOR encoding performed by the members of the above conformance classes MUST be done using the CTAP2 canonical CBOR encoding form. All decoders of the above conformance classes SHOULD reject CBOR that is not validly encoded in the CTAP2 canonical CBOR encoding form and SHOULD reject messages with duplicate map keys.

3. Dependencies

This specification relies on several other underlying specifications, listed below and in Terms defined by reference.

Base64url encoding

The term Base64url Encoding refers to the base64 encoding using the URL- and filename-safe character set defined in Section 5 of [RFC4648], with all trailing '=' characters omitted (as permitted by Section 3.2) and without the inclusion of any line breaks, whitespace, or other additional characters.

CBOR

A number of structures in this specification, including attestation statements and extensions, are encoded using the CTAP2 canonical CBOR encoding form of the Compact Binary Object Representation (CBOR) [RFC8949], as defined in [FIDO-CTAP].

CDDL

This specification describes the syntax of all CBOR-encoded data using the CBOR Data Definition Language (CDDL) [RFC8610].

COSE

CBOR Object Signing and Encryption (COSE) [RFC9052] [RFC9053]. The IANA COSE Algorithms registry [IANA-COSE-ALGS-REG] originally established by [RFC8152] and updated by these specifications is also used.

Credential Management

The API described in this document is an extension of the Credential concept defined in [CREDENTIAL-MANAGEMENT-1].

DOM

DOMException and the DOMException values used in this specification are defined in [DOM4].

ECMAScript

%ArrayBuffer% is defined in [ECMAScript].

URL

The concepts of domain, host, port, scheme, valid domain and valid domain string are defined in [URL].

Web IDL

Many of the interface definitions and all of the IDL in this specification depend on [WebIDL]. This updated version of the Web IDL standard adds support for Promises, which are now the preferred mechanism for asynchronous interaction in all new web APIs.

FIDO AppID

The algorithms for determining the FacetID of a calling application and determining if a caller’s FacetID is authorized for an AppID (used only in the AppID extension) are defined by [FIDO-APPID].

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

4. Terminology

Attestation

Generally, attestation is a statement that serves to bear witness, confirm, or authenticate. In the WebAuthn context, attestation is employed to provide verifiable evidence as to the origin of an authenticator and the data it emits. This includes such things as credential IDs, credential key pairs, signature counters, etc.

An attestation statement is provided within an attestation object during a registration ceremony. See also § 6.5 Attestation and Figure 6. Whether or how the client conveys the attestation statement and aaguid portions of the attestation object to the Relying Party is described by attestation conveyance.

Attestation Certificate

An X.509 Certificate for the attestation key pair used by an authenticator to attest to its manufacture and capabilities. At registration time, the authenticator uses the attestation private key to sign the Relying Party-specific credential public key (and additional data) that it generates and returns via the authenticatorMakeCredential operation. Relying Parties use the attestation public key conveyed in the attestation certificate to verify the attestation signature. Note that in the case of self attestation, the authenticator has no distinct attestation key pair nor attestation certificate, see self attestation for details.

Authentication

Authentication Ceremony

The ceremony where a user, and the user’s client platform (containing or connected to at least one authenticator) work in concert to cryptographically prove to a Relying Party that the user controls the credential private key of a previously-registered public key credential (see Registration). Note that this includes a test of user presence or user verification.

The WebAuthn authentication ceremony is defined in § 7.2 Verifying an Authentication Assertion, and is initiated by the Relying Party invoking a navigator.credentials.get() operation with a publicKey argument. See § 5 Web Authentication API for an introductory overview and § 1.3.3 Authentication for implementation examples.

Authentication Assertion

Assertion

The cryptographically signed AuthenticatorAssertionResponse object returned by an authenticator as the result of an authenticatorGetAssertion operation.

This corresponds to the [CREDENTIAL-MANAGEMENT-1] specification’s single-use credentials.

Authenticator

WebAuthn Authenticator

A cryptographic entity, existing in hardware or software, that can register a user with a given Relying Party and later assert possession of the registered public key credential, and optionally verify the user to the Relying Party. Authenticators can report information regarding their type and security characteristics via attestation during registration and assertion.

A WebAuthn Authenticator could be a roaming authenticator, a dedicated hardware subsystem integrated into the client device, or a software component of the client or client device. A WebAuthn Authenticator is not necessarily confined to operating in a local context, and can generate or store a credential key pair in a server outside of client-side hardware.

In general, an authenticator is assumed to have only one user. If multiple natural persons share access to an authenticator, they are considered to represent the same user in the context of that authenticator. If an authenticator implementation supports multiple users in separated compartments, then each compartment is considered a separate authenticator with a single user with no access to other users' credentials.

Authorization Gesture

An authorization gesture is a physical interaction performed by a user with an authenticator as part of a ceremony, such as registration or authentication. By making such an authorization gesture, a user provides consent for (i.e., authorizes) a ceremony to proceed. This MAY involve user verification if the employed authenticator is capable, or it MAY involve a simple test of user presence.

Backed Up

Public Key Credential Sources may be backed up in some fashion such that they may become present on an authenticator other than their generating authenticator. Backup can occur via mechanisms including but not limited to peer-to-peer sync, cloud sync, local network sync, and manual import/export. See also § 6.1.3 Credential Backup State.

Backup Eligibility

Backup Eligible

A Public Key Credential Source’s generating authenticator determines at creation time whether the public key credential source is allowed to be backed up. Backup eligibility is signaled in authenticator data’s flags along with the current backup state. Backup eligibility is a credential property and is permanent for a given public key credential source. A backup eligible public key credential source is referred to as a multi-device credential whereas one that is not backup eligible is referred to as a single-device credential. See also § 6.1.3 Credential Backup State.

Backup State

The current backup state of a multi-device credential as determined by the current managing authenticator. Backup state is signaled in authenticator data’s flags and can change over time. See also backup eligibility and § 6.1.3 Credential Backup State.

Biometric Authenticator

Any authenticator that implements biometric recognition.

Biometric Recognition

The automated recognition of individuals based on their biological and behavioral characteristics [ISOBiometricVocabulary].

Bound credential

"Authenticator contains a credential"

"Credential created on an authenticator"

A public key credential source or public key credential is said to be bound to its managing authenticator. This means that only the managing authenticator can generate assertions for the public key credential sources bound to it.

This may also be expressed as "the managing authenticator contains the bound credential", or "the bound credential was created on its managing authenticator". Note, however, that a server-side credential might not be physically stored in persistent memory inside the authenticator, hence "bound to" is the primary term. See § 6.2.2 Credential Storage Modality.

Ceremony

The concept of a ceremony [Ceremony] is an extension of the concept of a network protocol, with human nodes alongside computer nodes and with communication links that include user interface(s), human-to-human communication, and transfers of physical objects that carry data. What is out-of-band to a protocol is in-band to a ceremony. In this specification, Registration and Authentication are ceremonies, and an authorization gesture is often a component of those ceremonies.

Client

WebAuthn Client

Also referred to herein as simply a client. See also Conforming User Agent. A WebAuthn Client is an intermediary entity typically implemented in the user agent (in whole, or in part). Conceptually, it underlies the Web Authentication API and embodies the implementation of the [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal methods. It is responsible for both marshalling the inputs for the underlying authenticator operations, and for returning the results of the latter operations to the Web Authentication API’s callers.

The WebAuthn Client runs on, and is distinct from, a WebAuthn Client Device.

Client Device

WebAuthn Client Device

The hardware device on which the WebAuthn Client runs, for example a smartphone, a laptop computer or a desktop computer, and the operating system running on that hardware.

The distinctions between a WebAuthn Client device and a client are:

• a single client device MAY support running multiple clients, i.e., browser implementations, which all have access to the same authenticators available on that client device, and

• platform authenticators are bound to a client device rather than a WebAuthn Client.

A client device and a client together constitute a client platform.

Client Platform

A client device and a client together make up a client platform. A single hardware device MAY be part of multiple distinct client platforms at different times by running different operating systems and/or clients.

Client-Side

This refers in general to the combination of the user’s client platform, authenticators, and everything gluing it all together.

Client-side discoverable Public Key Credential Source

Client-side discoverable Credential

Discoverable Credential

Passkey

[DEPRECATED] Resident Credential

[DEPRECATED] Resident Key

Note: Historically, client-side discoverable credentials have been 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. Also, the term resident key is defined here as equivalent to a client-side discoverable credential.

A Client-side discoverable Public Key Credential Source, or Discoverable Credential for short, is a public key credential source that is discoverable and usable in authentication ceremonies where the Relying Party does not provide any credential IDs, i.e., the Relying Party invokes navigator.credentials.get() with an empty allowCredentials argument. This means that the Relying Party does not necessarily need to first identify the user.

As a consequence, a discoverable credential capable authenticator can generate an assertion signature for a discoverable credential given only an RP ID, which in turn necessitates that the public key credential source is stored in the authenticator or client platform. This is in contrast to a Server-side Public Key Credential Source, which requires that the authenticator is given both the RP ID and the credential ID but does not require client-side storage of the public key credential source.

See also: client-side credential storage modality and non-discoverable credential.

Note: Client-side discoverable credentials are also usable in authentication ceremonies where credential IDs are given, i.e., when calling navigator.credentials.get() with a non-empty allowCredentials argument.

Conforming User Agent

A user agent implementing, in cooperation with the underlying client device, the Web Authentication API and algorithms given in this specification, and handling communication between authenticators and Relying Parties.

Credential ID

A probabilistically-unique byte sequence identifying a public key credential source and its authentication assertions. At most 1023 bytes long.

Credential IDs are generated by authenticators in two forms:

1. At least 16 bytes that include at least 100 bits of entropy, or

2. The public key credential source, without its Credential ID or mutable items, encrypted so only its managing authenticator can decrypt it. This form allows the authenticator to be nearly stateless, by having the Relying Party store any necessary state.

   Note: [FIDO-UAF-AUTHNR-CMDS] includes guidance on encryption techniques under "Security Guidelines".

Relying Parties do not need to distinguish these two Credential ID forms.

Credential Key Pair

Credential Private Key

Credential Public Key

User Public Key

A credential key pair is a pair of asymmetric cryptographic keys generated by an authenticator and scoped to a specific WebAuthn Relying Party. It is the central part of a public key credential.

A credential public key is the public key portion of a credential key pair. The credential public key is returned to the Relying Party during a registration ceremony.

A credential private key is the private key portion of a credential key pair. The credential private key is bound to a particular authenticator - its managing authenticator - and is expected to never be exposed to any other party, not even to the owner of the authenticator.

Note that in the case of self attestation, the credential key pair is also used as the attestation key pair, see self attestation for details.

Note: The credential public key is referred to as the user public key in FIDO UAF [UAFProtocol], and in FIDO U2F [FIDO-U2F-Message-Formats] and some parts of this specification that relate to it.

Credential Properties

A credential property is some characteristic property of a public key credential source, such as whether it is a client-side discoverable credential or a server-side credential.

Credential Record

In order to implement the algorithms defined in § 7 WebAuthn Relying Party Operations, the Relying Party MUST store some properties of registered public key credential sources. The credential record struct is an abstraction of these properties stored in a user account. A credential record is created during a registration ceremony and used in subsequent authentication ceremonies. Relying Parties MAY delete credential records as necessary or when requested by users.

The following items are RECOMMENDED in order to implement all steps of § 7.1 Registering a New Credential and § 7.2 Verifying an Authentication Assertion as defined:

type

The type of the public key credential source.

id

The Credential ID of the public key credential source.

publicKey

The credential public key of the public key credential source.

signCount

The latest value of the signature counter in the authenticator data from any ceremony using the public key credential source.

transports

The value returned from getTransports() when the public key credential source was registered.

Note: Modifying or removing items from the value returned from getTransports() could negatively impact user experience, or even prevent use of the corresponding credential.

uvInitialized

A Boolean value indicating whether any credential from this public key credential source has had the UV flag set.

When this is true, the Relying Party MAY consider the UV flag as an authentication factor in authentication ceremonies. For example, a Relying Party might skip a password prompt if uvInitialized is true and the UV flag is set, even when user verification was not required.

When this is false, including an authentication ceremony where it would be updated to true, the UV flag MUST NOT be relied upon as an authentication factor. This is because the first time a public key credential source sets the UV flag to 1, there is not yet any trust relationship established between the Relying Party and the authenticator’s user verification. Therefore, updating uvInitialized from false to true SHOULD require authorization by an additional authentication factor equivalent to WebAuthn user verification.

backupEligible

The value of the BE flag when the public key credential source was created.

backupState

The latest value of the BS flag in the authenticator data from any ceremony using the public key credential source.

The following items are OPTIONAL:

attestationObject

The value of the attestationObject attribute when the public key credential source was registered. Storing this enables the Relying Party to reference the credential’s attestation statement at a later time.

attestationClientDataJSON

The value of the clientDataJSON attribute when the public key credential source was registered. Storing this in combination with the above attestationObject item enables the Relying Party to re-verify the attestation signature at a later time.

rpId

The value of the rp.id parameter specified in the create() operation during credential registration. This value is a core property of the credential that determines where it can be used. Storing this value at registration time can help in the future, such as to audit its use, troubleshoot issues authenticating with it, or to use it across different domains later via Related Origins.

WebAuthn extensions MAY define additional items needed to process the extension. Relying Parties MAY also include any additional items as needed, and MAY omit any items not needed for their implementation.

The credential descriptor for a credential record is a PublicKeyCredentialDescriptor value with the contents:

type

The type of the credential record.

id

The id of the credential record.

transports

The transports of the credential record.

Generating Authenticator

The Generating Authenticator is the authenticator involved in the authenticatorMakeCredential operation resulting in the creation of a given public key credential source. The generating authenticator is the same as the managing authenticator for single-device credentials. For multi-device credentials, the generating authenticator may or may not be the same as the current managing authenticator participating in a given authentication operation.

Human Palatability

An identifier that is human-palatable is intended to be rememberable and reproducible by typical human users, in contrast to identifiers that are, for example, randomly generated sequences of bits [EduPersonObjectClassSpec].

Non-Discoverable Credential

This is a credential whose credential ID must be provided in allowCredentials when calling navigator.credentials.get() because it is not client-side discoverable. See also server-side credentials.

Registrable Origin Label

The first domain label of the registrable domain of a domain, or null if the registrable domain is null. For example, the registrable origin label of both example.co.uk and www.example.de is example if both co.uk and de are public suffixes.

Public Key Credential

Generically, a credential is data one entity presents to another in order to authenticate the former to the latter [RFC4949]. The term public key credential refers to one of: a public key credential source, the possibly-attested credential public key corresponding to a public key credential source, or an authentication assertion. Which one is generally determined by context.

Note: This is a willful violation of [RFC4949]. In English, a "credential" is both a) the thing presented to prove a statement and b) intended to be used multiple times. It’s impossible to achieve both criteria securely with a single piece of data in a public key system. [RFC4949] chooses to define a credential as the thing that can be used multiple times (the public key), while this specification gives "credential" the English term’s flexibility. This specification uses more specific terms to identify the data related to an [RFC4949] credential:

"Authentication information" (possibly including a private key)

Public key credential source

"Signed value"

Authentication assertion

[RFC4949] "credential"

Credential public key or attestation object

At registration time, the authenticator creates an asymmetric key pair, and stores its private key portion and information from the Relying Party into a public key credential source. The public key portion is returned to the Relying Party, which then stores it in the active user account. Subsequently, only that Relying Party, as identified by its RP ID, is able to employ the public key credential in authentication ceremonies, via the get() method. The Relying Party uses its stored copy of the credential public key to verify the resultant authentication assertion.

Public Key Credential Source

A credential source ([CREDENTIAL-MANAGEMENT-1]) used by an authenticator to generate authentication assertions. A public key credential source consists of a struct with the following items:

type

whose value is of PublicKeyCredentialType, defaulting to public-key.

id

A Credential ID.

privateKey

The credential private key.

rpId

The Relying Party Identifier, for the Relying Party this public key credential source is scoped to. This is determined by the rp.id parameter of the create() operation.

userHandle

The user handle associated when this public key credential source was created. This item is nullable, however user handle MUST always be populated for discoverable credentials.

otherUI

OPTIONAL other information used by the authenticator to inform its UI. For example, this might include the user’s displayName. otherUI is a mutable item and SHOULD NOT be bound to the public key credential source in a way that prevents otherUI from being updated.

The authenticatorMakeCredential operation creates a public key credential source bound to a managing authenticator and returns the credential public key associated with its credential private key. The Relying Party can use this credential public key to verify the authentication assertions created by this public key credential source.

Rate Limiting

The process (also known as throttling) by which an authenticator implements controls against brute force attacks by limiting the number of consecutive failed authentication attempts within a given period of time. If the limit is reached, the authenticator should impose a delay that increases exponentially with each successive attempt, or disable the current authentication modality and offer a different authentication factor if available. Rate limiting is often implemented as an aspect of user verification.

Registration

Registration Ceremony

The ceremony where a user, a Relying Party, and the user’s client platform (containing or connected to at least one authenticator) work in concert to create a public key credential and associate it with a user account. Note that this includes employing a test of user presence or user verification. After a successful registration ceremony, the user can be authenticated by an authentication ceremony.

The WebAuthn registration ceremony is defined in § 7.1 Registering a New Credential, and is initiated by the Relying Party invoking a navigator.credentials.create() operation with a publicKey argument. See § 5 Web Authentication API for an introductory overview and § 1.3.1 Registration for implementation examples.

Relying Party

WebAuthn Relying Party

The entity whose web application utilizes the Web Authentication API to register and authenticate users.

A Relying Party implementation typically consists of both some client-side script that invokes the Web Authentication API in the client, and a server-side component that executes the Relying Party operations and other application logic. Communication between the two components MUST use HTTPS or equivalent transport security, but is otherwise beyond the scope of this specification.

Note: While the term Relying Party is also often used in other contexts (e.g., X.509 and OAuth), an entity acting as a Relying Party in one context is not necessarily a Relying Party in other contexts. In this specification, the term WebAuthn Relying Party is often shortened to be just Relying Party, and explicitly refers to a Relying Party in the WebAuthn context. Note that in any concrete instantiation a WebAuthn context may be embedded in a broader overall context, e.g., one based on OAuth.

Relying Party Identifier

RP ID

In the context of the WebAuthn API, a relying party identifier is a valid domain string identifying the WebAuthn Relying Party on whose behalf a given registration or authentication ceremony is being performed. A public key credential can only be used for authentication with the same entity (as identified by RP ID) it was registered with.

By default, the RP ID for a WebAuthn operation is set to the caller’s origin’s effective domain. This default MAY be overridden by the caller, as long as the caller-specified RP ID value is a registrable domain suffix of or is equal to the caller’s origin’s effective domain. See also § 5.1.3 Create a New Credential - PublicKeyCredential’s [[Create]](origin, options, sameOriginWithAncestors) Internal Method and § 5.1.4 Use an Existing Credential to Make an Assertion.

An RP ID is based on a host’s domain name. It does not itself include a scheme or port, as an origin does. The RP ID of a public key credential determines its scope. I.e., it determines the set of origins on which the public key credential may be exercised, as follows:

• The RP ID must be equal to the origin’s effective domain, or a registrable domain suffix of the origin’s effective domain.

• One of the following must be true:

  • The origin’s scheme is https.

  • The origin’s host is localhost and its scheme is http.

• The origin’s port is unrestricted.

For example, given a Relying Party whose origin is https://login.example.com:1337, then the following RP IDs are valid: login.example.com (default) and example.com, but not m.login.example.com and not com. Another example of a valid origin is http://localhost:8000, due to the origin being localhost.

This is done in order to match the behavior of pervasively deployed ambient credentials (e.g., cookies, [RFC6265]). Please note that this is a greater relaxation of "same-origin" restrictions than what document.domain’s setter provides.

These restrictions on origin values apply to WebAuthn Clients.

Other specifications mimicking the WebAuthn API to enable WebAuthn public key credentials on non-Web platforms (e.g. native mobile applications), MAY define different rules for binding a caller to a Relying Party Identifier. Though, the RP ID syntaxes MUST conform to either valid domain strings or URIs [RFC3986] [URL].

Server-side Public Key Credential Source

Server-side Credential

[DEPRECATED] Non-Resident Credential

Note: Historically, server-side credentials have been known as non-resident credentials. For backwards compatibility purposes, the various WebAuthn API and Authenticator Model components with various forms of resident within their names have not been changed.

A Server-side Public Key Credential Source, or Server-side Credential for short, is a public key credential source that is only usable in an authentication ceremony when the Relying Party supplies its credential ID in navigator.credentials.get()’s allowCredentials argument. This means that the Relying Party must manage the credential’s storage and discovery, as well as be able to first identify the user in order to discover the credential IDs to supply in the navigator.credentials.get() call.

Client-side storage of the public key credential source is not required for a server-side credential. This is in contrast to a client-side discoverable credential, which instead does not require the user to first be identified in order to provide the user’s credential IDs to a navigator.credentials.get() call.

See also: server-side credential storage modality and non-discoverable credential.

Test of User Presence

A test of user presence is a simple form of authorization gesture and technical process where a user interacts with an authenticator by (typically) simply touching it (other modalities may also exist), yielding a Boolean result. Note that this does not constitute user verification because a user presence test, by definition, is not capable of biometric recognition, nor does it involve the presentation of a shared secret such as a password or PIN.

User Account

In the context of this specification, a user account denotes the mapping of a set of credentials [CREDENTIAL-MANAGEMENT-1] to a (sub)set of a Relying Party’s resources, as maintained and authorized by the Relying Party. The Relying Party maps a given public key credential to a user account by assigning a user account-specific value to the credential’s user handle and storing a credential record for the credential in the user account. This mapping, the set of credentials, and their authorizations, may evolve over time. A given user account might be accessed by one or more natural persons (also known as "users"), and one natural person might have access to one or more user accounts, depending on actions of the user(s) and the Relying Party.

User Consent

User consent means the user agrees with what they are being asked, i.e., it encompasses reading and understanding prompts. An authorization gesture is a ceremony component often employed to indicate user consent.

User Handle

A user handle is an identifier for a user account, specified by the Relying Party as user.id during registration. Discoverable credentials store this identifier and MUST return it as response.userHandle in authentication ceremonies started with an empty allowCredentials argument.

The main use of the user handle is to identify the user account in such authentication ceremonies, but the credential ID could be used instead. The main differences are that the credential ID is chosen by the authenticator and is unique for each credential, while the user handle is chosen by the Relying Party and ought to be the same for all credentials registered to the same user account.

Authenticators map pairs of RP ID and user handle to public key credential sources. As a consequence, an authenticator will store at most one discoverable credential per user handle per Relying Party. Therefore a secondary use of the user handle is to allow authenticators to know when to replace an existing discoverable credential with a new one during the registration ceremony.

A user handle is an opaque byte sequence with a maximum size of 64 bytes, and is not meant to be displayed to the user. It MUST NOT contain personally identifying information, see § 14.6.1 User Handle Contents.

User Present

Upon successful completion of a user presence test, the user is said to be "present".

User Verification

The technical process by which an authenticator locally authorizes the invocation of the authenticatorMakeCredential and authenticatorGetAssertion operations. User verification MAY be instigated through various authorization gesture modalities; for example, through a touch plus pin code, password entry, or biometric recognition (e.g., presenting a fingerprint) [ISOBiometricVocabulary]. The intent is to distinguish individual users. See also § 6.2.3 Authentication Factor Capability.

Note that user verification does not give the Relying Party a concrete identification of the user, but when 2 or more ceremonies with user verification have been done with that credential it expresses that it was the same user that performed all of them. The same user might not always be the same natural person, however, if multiple natural persons share access to the same authenticator.

Note: Distinguishing natural persons depends in significant part upon the client platform’s and authenticator’s capabilities. For example, some devices are intended to be used by a single individual, yet they may allow multiple natural persons to enroll fingerprints or know the same PIN and thus access the same user account(s) using that device.

NOTE: Invocation of the authenticatorMakeCredential and authenticatorGetAssertion operations implies use of key material managed by the authenticator.

For security, user verification and use of credential private keys MUST all occur within the logical security boundary defining the authenticator.

User verification procedures MAY implement rate limiting as a protection against brute force attacks.

User Verified

Upon successful completion of a user verification process, the user is said to be "verified".

5. Web Authentication API

This section normatively specifies the API for creating and using public key credentials. The basic idea is that the credentials belong to the user and are managed by a WebAuthn Authenticator, with which the WebAuthn Relying Party interacts through the client platform. Relying Party scripts can (with the user’s consent) request the browser to create a new credential for future use by the Relying Party. See Figure , below.

Scripts can also request the user’s permission to perform authentication operations with an existing credential. See Figure , below.

All such operations are performed in the authenticator and are mediated by the client platform on the user’s behalf. At no point does the script get access to the credentials themselves; it only gets information about the credentials in the form of objects.

In addition to the above script interface, the authenticator MAY implement (or come with client software that implements) a user interface for management. Such an interface MAY be used, for example, to reset the authenticator to a clean state or to inspect the current state of the authenticator. In other words, such an interface is similar to the user interfaces provided by browsers for managing user state such as history, saved passwords, and cookies. Authenticator management actions such as credential deletion are considered to be the responsibility of such a user interface and are deliberately omitted from the API exposed to scripts.

The security properties of this API are provided by the client and the authenticator working together. The authenticator, which holds and manages credentials, ensures that all operations are scoped to a particular origin, and cannot be replayed against a different origin, by incorporating the origin in its responses. Specifically, as defined in § 6.3 Authenticator Operations, the full origin of the requester is included, and signed over, in the attestation object produced when a new credential is created as well as in all assertions produced by WebAuthn credentials.

Additionally, to maintain user privacy and prevent malicious Relying Parties from probing for the presence of public key credentials belonging to other Relying Parties, each credential is also scoped to a Relying Party Identifier, or RP ID. This RP ID is provided by the client to the authenticator for all operations, and the authenticator ensures that credentials created by a Relying Party can only be used in operations requested by the same RP ID. Separating the origin from the RP ID in this way allows the API to be used in cases where a single Relying Party maintains multiple origins.

The client facilitates these security measures by providing the Relying Party’s origin and RP ID to the authenticator for each operation. Since this is an integral part of the WebAuthn security model, user agents only expose this API to callers in secure contexts. For web contexts in particular, this only includes those accessed via a secure transport (e.g., TLS) established without errors.

The Web Authentication API is defined by the union of the Web IDL fragments presented in the following sections. A combined IDL listing is given in the IDL Index.

5.1. PublicKeyCredential Interface

The PublicKeyCredential interface inherits from Credential [CREDENTIAL-MANAGEMENT-1], and contains the attributes that are returned to the caller when a new credential is created, or a new assertion is requested.

[, =]
  :  {
 []    ;
 []    ;
   ? ;
  ();
  <> ();
  ();
};

id

This attribute is inherited from Credential, though PublicKeyCredential overrides Credential’s getter, instead returning the base64url encoding of the data contained in the object’s [[identifier]] internal slot.

rawId

This attribute returns the ArrayBuffer contained in the [[identifier]] internal slot.

response, of type AuthenticatorResponse, readonly

This attribute contains the authenticator’s response to the client’s request to either create a public key credential, or generate an authentication assertion. If the PublicKeyCredential is created in response to create(), this attribute’s value will be an AuthenticatorAttestationResponse, otherwise, the PublicKeyCredential was created in response to get(), and this attribute’s value will be an AuthenticatorAssertionResponse.

authenticatorAttachment, of type DOMString, readonly, nullable

This attribute reports the authenticator attachment modality in effect at the time the navigator.credentials.create() or navigator.credentials.get() methods successfully complete. The attribute’s value SHOULD be a member of AuthenticatorAttachment. Relying Parties SHOULD treat unknown values as if the value were null.

Note: If, as the result of a registration or authentication ceremony, authenticatorAttachment’s value is "cross-platform" and concurrently isUserVerifyingPlatformAuthenticatorAvailable returns true, then the user employed a roaming authenticator for this ceremony while there is an available platform authenticator. Thus the Relying Party has the opportunity to prompt the user to register the available platform authenticator, which may enable more streamlined user experience flows.

An authenticator’s attachment modality could change over time. For example, a mobile phone might at one time only support platform attachment but later receive updates to support cross-platform attachment as well.

getClientExtensionResults()

This operation returns the value of [[clientExtensionsResults]], which is a map containing extension identifier → client extension output entries produced by the extension’s client extension processing.

isConditionalMediationAvailable()

PublicKeyCredential overrides this method to indicate availability for conditional mediation during navigator.credentials.get(). WebAuthn Relying Parties SHOULD verify availability before attempting to set options.mediation to conditional.

Upon invocation, a promise is returned that resolves with a value of true if conditional user mediation is available, or false otherwise.

This method has no arguments and returns a promise to a Boolean value.

The conditionalGet capability is equivalent to this promise resolving to true.

Note: If this method is not present, conditional user mediation is not available for navigator.credentials.get().

Note: This method does not indicate whether or not conditional user mediation is available in navigator.credentials.create(). For that, see the conditionalCreate capability in getClientCapabilities().

toJSON()

This operation returns RegistrationResponseJSON or AuthenticationResponseJSON, which are JSON type representations mirroring PublicKeyCredential, suitable for submission to a Relying Party server as an application/json payload. The client is in charge of serializing values to JSON types as usual, but MUST take additional steps to first encode any ArrayBuffer values to DOMString values using base64url encoding.

The RegistrationResponseJSON.clientExtensionResults or AuthenticationResponseJSON.clientExtensionResults member MUST be set to the output of getClientExtensionResults(), with any ArrayBuffer values encoded to DOMString values using base64url encoding. This MAY include ArrayBuffer values from extensions registered in the IANA "WebAuthn Extension Identifiers" registry [IANA-WebAuthn-Registries] but not defined in § 9 WebAuthn Extensions.

The AuthenticatorAttestationResponseJSON.transports member MUST be set to the output of getTransports().

The AuthenticatorAttestationResponseJSON.publicKey member MUST be set to the output of getPublicKey().

The AuthenticatorAttestationResponseJSON.publicKeyAlgorithm member MUST be set to the output of getPublicKeyAlgorithm().

  ;
// The structure of this object will be either
// RegistrationResponseJSON or AuthenticationResponseJSON
  ;

  {
   ;
   ;
   ;
  ;
   ;
   ;
};

  {
   ;
   ;
  <> ;
 // The publicKey field will be missing if pubKeyCredParams was used to
 // negotiate a public-key algorithm that the user agent doesn't
 // understand. (See section “Easily accessing credential data” for a
 // list of which algorithms user agents must support.) If using such an
 // algorithm then the public key must be parsed directly from
 // attestationObject or authenticatorData.
  ;
   ;
 // This value contains copies of some of the fields above. See
 // section “Easily accessing credential data”.
   ;
};

  {
   ;
   ;
   ;
  ;
   ;
   ;
};

  {
   ;
   ;
   ;
  ;
};

  {
};

[[type]]

The PublicKeyCredential interface object’s [[type]] internal slot’s value is the string "public-key".

Note: This is reflected via the type attribute getter inherited from Credential.

[[discovery]]

The PublicKeyCredential interface object’s [[discovery]] internal slot’s value is "remote".

[[identifier]]

This internal slot contains the credential ID, chosen by the authenticator. The credential ID is used to look up credentials for use, and is therefore expected to be globally unique with high probability across all credentials of the same type, across all authenticators.

This API does not constrain the format of this identifier, except that it MUST NOT be longer than 1023 bytes and MUST be sufficient for the authenticator to uniquely select a key. For example, an authenticator without on-board storage may create identifiers containing a credential private key wrapped with a symmetric key that is burned into the authenticator.

[[clientExtensionsResults]]

This internal slot contains the results of processing client extensions requested by the Relying Party upon the Relying Party’s invocation of either navigator.credentials.create() or navigator.credentials.get().

PublicKeyCredential’s interface object inherits Credential’s implementation of [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors), and defines its own implementation of each of [[Create]](origin, options, sameOriginWithAncestors), [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors), and [[Store]](credential, sameOriginWithAncestors).

Calling CredentialsContainer’s preventSilentAccess() method will have no effect on PublicKeyCredential credentials, since they always require user interaction.

5.1.1. CredentialCreationOptions Dictionary Extension

To support registration via navigator.credentials.create(), this document extends the CredentialCreationOptions dictionary as follows:

   {
  ;
};

5.1.2. CredentialRequestOptions Dictionary Extension

To support obtaining assertions via navigator.credentials.get(), this document extends the CredentialRequestOptions dictionary as follows:

   {
  ;
};

5.1.3. Create a New Credential - PublicKeyCredential’s [[Create]](origin, options, sameOriginWithAncestors) Internal Method

5.1.3.1. Create Request Exceptions

This section is not normative.

WebAuthn Relying Parties can encounter a number of exceptions from a call to navigator.credentials.create(). Some exceptions can have multiple reasons for why they happened, requiring the WebAuthn Relying Parties to infer the actual reason based on their use of WebAuthn.

Note: Exceptions that can be raised during processing of any WebAuthn Extensions, including ones defined outside of this specification, are not listed here.

The following DOMException exceptions can be raised:

AbortError

The ceremony was cancelled by an AbortController. See § 5.6 Abort Operations with AbortSignal and § 1.3.4 Aborting Authentication Operations.

ConstraintError

Either residentKey was set to required and no available authenticator supported resident keys, or userVerification was set to required and no available authenticator could perform user verification.

InvalidStateError

The authenticator used in the ceremony recognized an entry in excludeCredentials after the user consented to registering a credential.

NotSupportedError

No entry in pubKeyCredParams had a type property of public-key, or the authenticator did not support any of the signature algorithms specified in pubKeyCredParams.

SecurityError

The effective domain was not a valid domain, or rp.id was not equal to or a registrable domain suffix of the effective domain. In the latter case, the client does not support related origin requests or the related origins validation procedure failed.

NotAllowedError

A catch-all error covering a wide range of possible reasons, including common ones like the user canceling out of the ceremony. Some of these causes are documented throughout this spec, while others are client-specific.

The following simple exceptions can be raised:

TypeError

The options argument was not a valid CredentialCreationOptions value, or the value of user.id was empty or was longer than 64 bytes.

5.1.4. Use an Existing Credential to Make an Assertion

WebAuthn Relying Parties call navigator.credentials.get({publicKey:..., ...}) to discover and use an existing public key credential, with the user’s consent. Relying Party script optionally specifies some criteria to indicate what public key credential sources are acceptable to it. The client platform locates public key credential sources matching the specified criteria, and guides the user to pick one that the script will be allowed to use. The user may choose to decline the entire interaction even if a public key credential source is present, for example to maintain privacy. If the user picks a public key credential source, the user agent then uses § 6.3.3 The authenticatorGetAssertion Operation to sign a Relying Party-provided challenge and other collected data into an authentication assertion, which is used as a credential.

The navigator.credentials.get() implementation [CREDENTIAL-MANAGEMENT-1] calls PublicKeyCredential.[[CollectFromCredentialStore]]() to collect any credentials that should be available without user mediation (roughly, this specification’s authorization gesture), and if it does not find exactly one of those, it then calls PublicKeyCredential.[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) to have the user select a public key credential source.

Since this specification requires an authorization gesture to create any assertions, PublicKeyCredential inherits the default behavior of [[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors), of returning an empty set. PublicKeyCredential’s implementation of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) is specified in the next section.

In general, the user agent SHOULD show some UI to the user to guide them in selecting and authorizing an authenticator with which to complete the operation. By setting options.mediation to conditional, Relying Parties can indicate that a prominent modal UI should not be shown unless credentials are discovered. The Relying Party SHOULD first use isConditionalMediationAvailable() or getClientCapabilities() to check that the client supports the conditionalGet capability in order to prevent a user-visible error in case this feature is not available.

Any navigator.credentials.get() operation can be aborted by leveraging the AbortController; see DOM § 3.3 Using AbortController and AbortSignal objects in APIs for detailed instructions.

5.1.4.1. PublicKeyCredential’s [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) Internal Method

5.1.4.2. Issuing a Credential Request to an Authenticator

This sub-algorithm of [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) encompasses the specific UI context-independent steps necessary for requesting a credential from a given authenticator, using given PublicKeyCredentialRequestOptions. It is called by [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) from various points depending on which user mediation the present authentication ceremony is subject to (e.g.: conditional mediation).

This algorithm accepts the following arguments:

authenticator

A client platform-specific handle identifying an authenticator presently available on this client platform.

savedCredentialIds

A map containing authenticator → credential ID. This argument will be modified in this algorithm.

pkOptions

This argument is a PublicKeyCredentialRequestOptions object specifying the desired attributes of the public key credential to discover.

rpId

The request RP ID.

clientDataHash

The hash of the serialized client data represented by clientDataJSON.

authenticatorExtensions

A map containing extension identifiers to the base64url encoding of the client extension processing output for authenticator extensions.

This algorithm returns false if the client determines that the authenticator is not capable of handling the request, or true if the request was issued successfully.

The steps for issuing a credential request to an authenticator are as follows:

1. If pkOptions.userVerification is set to required and the authenticator is not capable of performing user verification, return false.

2. Let userVerification be the effective user verification requirement for assertion, a Boolean value, as follows. If pkOptions.userVerification

   is set to required

   Let userVerification be true.

   is set to preferred

   If the authenticator

   is capable of user verification

   Let userVerification be true.

   is not capable of user verification

   Let userVerification be false.

   is set to discouraged

   Let userVerification be false.

3. If pkOptions.allowCredentials

   is not empty

   1. Let allowCredentialDescriptorList be a new list.

   2. Execute a client platform-specific procedure to determine which, if any, public key credentials described by pkOptions.allowCredentials are bound to this authenticator, by matching with rpId, pkOptions.allowCredentials.id, and pkOptions.allowCredentials.type. Set allowCredentialDescriptorList to this filtered list.

   3. If allowCredentialDescriptorList is empty, return false.

   4. Let distinctTransports be a new ordered set.

   5. If allowCredentialDescriptorList has exactly one value, set savedCredentialIds[authenticator] to allowCredentialDescriptorList[0].id’s value (see here in § 6.3.3 The authenticatorGetAssertion Operation for more information).

   6. For each credential descriptor C in allowCredentialDescriptorList, append each value, if any, of C.transports to distinctTransports.

      Note: This will aggregate only distinct values of transports (for this authenticator) in distinctTransports due to the properties of ordered sets.

   7. If distinctTransports

      is not empty

      The client selects one transport value from distinctTransports, possibly incorporating local configuration knowledge of the appropriate transport to use with authenticator in making its selection.

      Then, using transport, invoke the authenticatorGetAssertion operation on authenticator, with rpId, clientDataHash, allowCredentialDescriptorList, userVerification, and authenticatorExtensions as parameters.

      is empty

      Using local configuration knowledge of the appropriate transport to use with authenticator, invoke the authenticatorGetAssertion operation on authenticator with rpId, clientDataHash, allowCredentialDescriptorList, userVerification, and authenticatorExtensions as parameters.

   is empty

   Using local configuration knowledge of the appropriate transport to use with authenticator, invoke the authenticatorGetAssertion operation on authenticator with rpId, clientDataHash, userVerification, and authenticatorExtensions as parameters.

   Note: In this case, the Relying Party did not supply a list of acceptable credential descriptors. Thus, the authenticator is being asked to exercise any credential it may possess that is scoped to the Relying Party, as identified by rpId.

4. Return true.

5.1.4.3. Get Request Exceptions

This section is not normative.

WebAuthn Relying Parties can encounter a number of exceptions from a call to navigator.credentials.get(). Some exceptions can have multiple reasons for why they happened, requiring the WebAuthn Relying Parties to infer the actual reason based on their use of WebAuthn.

Note: Exceptions that can be raised during processing of any WebAuthn Extensions, including ones defined outside of this specification, are not listed here.

The following DOMException exceptions can be raised:

AbortError

The ceremony was cancelled by an AbortController. See § 5.6 Abort Operations with AbortSignal and § 1.3.4 Aborting Authentication Operations.

SecurityError

The effective domain was not a valid domain, or rp.id was not equal to or a registrable domain suffix of the effective domain. In the latter case, the client does not support related origin requests or the related origins validation procedure failed.

NotAllowedError

A catch-all error covering a wide range of possible reasons, including common ones like the user canceling out of the ceremony. Some of these causes are documented throughout this spec, while others are client-specific.

The following simple exceptions can be raised:

TypeError

The options argument was not a valid CredentialRequestOptions value.

5.1.5. Store an Existing Credential - PublicKeyCredential’s [[Store]](credential, sameOriginWithAncestors) Internal Method

5.1.6. Availability of User-Verifying Platform Authenticator - PublicKeyCredential’s isUserVerifyingPlatformAuthenticatorAvailable() Method

   {
  <> ();
};

5.1.7. Availability of client capabilities - PublicKeyCredential’s getClientCapabilities() Method

   {
  <> ();
};

 <, > ;

5.1.8. Deserialize Registration ceremony options - PublicKeyCredential’s parseCreationOptionsFromJSON() Method

   {
   ( );
};

  {
   ;
   ;
   ;
  <> ;
  ;
 <>  = [];
  ;
 <>  = [];
   = "none";
 <>  = [];
  ;
};

  {
   ;
   ;
   ;
};

  {
   ;
   ;
 <> ;
};

  {
};

5.1.9. Deserialize Authentication ceremony options - PublicKeyCredential’s parseRequestOptionsFromJSON() Methods

   {
   ( );
};

  {
   ;
  ;
  ;
 <>  = [];
   = "preferred";
 <>  = [];
  ;
};

5.1.10. Signal Credential Changes to the Authenticator - PublicKeyCredential’s signal methods

   {
  <> ( );
  <> ( );
  <> ( );
};

  {
   ;
   ;
};

  {
   ;
   ;
  <> ;
};

  {
   ;
   ;
   ;
   ;
};

WebAuthn Relying Parties may use these signal methods to inform authenticators of the state of public key credentials, so that incorrect or revoked credentials may be updated, removed, or hidden. Clients provide this functionality opportunistically, since an authenticator may not support updating its credentials map or may not be attached at the time the request is made. Furthermore, in order to avoid revealing information about a user’s credentials without user consent, signal methods do not indicate whether the operation succeeded. A successfully resolved promise only means that the options object was well formed.

Each signal method includes authenticator actions. Authenticators MAY choose to deviate in their authenticator actions from the present specification, e.g. to ignore a change they have a reasonable belief would be contrary to the user’s wish, or to ask the user before making some change. Authenticator actions are thus provided as the recommended way to handle signal methods.

In cases where an authenticator does not have the capability to process an authenticator action, clients MAY choose to use existing infrastructure such as [FIDO-CTAP]’s authenticatorCredentialManagement command to achieve an equivalent effect.

Note: Signal methods intentionally avoid waiting for authenticators to complete executing the authenticator actions. This measure protects users from WebAuthn Relying Parties gaining information about availability of their credentials without user consent based on the timing of the request.

5.1.10.1. Asynchronous RP ID validation algorithm

The Asynchronous RP ID validation algorithm lets signal methods validate RP IDs in parallel. The algorithm takes a DOMString rpId as input and returns a promise that rejects if the validation fails. The steps are:

1. Let effectiveDomain be the relevant settings object’s origin’s effective domain. If effectiveDomain is not a valid domain, then return a promise rejected with "SecurityError" DOMException.

2. If rpId is a registrable domain suffix of or is equal to effectiveDomain, return a promise resolved with undefined.

3. If the client does not support related origin requests, return a promise rejected with a "SecurityError" DOMException.

4. Let p be a new promise.

5. Execute the following steps in parallel:

   1. If the result of running the related origins validation procedure with arguments callerOrigin and rpId is true, then resolve p.

   2. Otherwise, reject p with a "SecurityError" DOMException.

6. Return p.

5.1.10.2. signalUnknownCredential(options)

The signalUnknownCredential method signals that a credential id was not recognized by the WebAuthn Relying Party, e.g. because it was deleted by the user. Unlike signalAllAcceptedCredentials(options), this method does not require passing the entire list of accepted credential IDs and the userHandle, avoiding a privacy leak to an unauthenticated caller (see § 14.6.3 Privacy leak via credential IDs).

Upon invocation of signalUnknownCredential(options), the client executes these steps:

1. If the result of base64url decoding options.credentialId is an error, then return a promise rejected with a TypeError.

2. Let p be the result of executing the Asynchronous RP ID validation algorithm with options.rpId.

3. Upon fulfillment of p, run the following steps in parallel:

   1. For every authenticator presently available on this client platform, invoke the unknownCredentialId authenticator action with options as input.

4. Return p.

The unknownCredentialId authenticator action takes an UnknownCredentialOptions options and is as follows:

1. For each public key credential source credential in the authenticator’s credential map:

   1. If the credential’s rpId equals options.rpId and the credential’s id equals the result of base64url decoding options.credentialId, remove credential from the credentials map or employ an authenticator-specific procedure to hide it from future authentication ceremonies.

PublicKeyCredentialsignalUnknownCredential
 rpId 
 credentialId  

5.1.10.3. signalAllAcceptedCredentials(options)

Signals the complete list of credential ids for a given user. WebAuthn Relying Parties SHOULD prefer this method over signalUnknownCredential() when the user is authenticated and therefore there is no privacy leak risk (see § 14.6.3 Privacy leak via credential IDs), since the list offers a full snapshot of a user’s public key credentials and might reflect changes that haven’t yet been reported to currently attached authenticators.

Upon invocation of signalAllAcceptedCredentials(options), the client executes these steps:

1. If the result of base64url decoding options.userId is an error, then return a promise rejected with a TypeError.

2. For each credentialId in options.allAcceptedCredentialIds:

   1. If the result of base64url decoding credentialId is an error, then return a promise rejected with a TypeError.

3. Let p be the result of executing the Asynchronous RP ID validation algorithm with options.rpId.

4. Upon fulfillment of p, run the following steps in parallel:

   1. For every authenticator presently available on this client platform, invoke the allAcceptedCredentialIds authenticator action with options as input.

5. Return p.

The allAcceptedCredentialIds authenticator actions take an AllAcceptedCredentialsOptions options and are as follows:

1. Let userId be result of base64url decoding options.userId.

2. Assertion: userId is not an error.

3. Let credential be credentials map[options.rpId, userId].

4. If credential does not exist, abort these steps.

5. If options.allAcceptedCredentialIds does NOT contain the result of base64url encoding the credential’s id, then remove credential from the credentials map or employ an authenticator-specific procedure to hide it from future authentication ceremonies.

6. Else, if credential has been hidden by an authenticator-specific procedure, reverse the action so that credential is present in future authentication ceremonies.

PublicKeyCredentialsignalAllAcceptedCredentials
 rpId 
 userId  
 allAcceptedCredentialIds 
 
 

Note: Authenticators might not be attached at the time signalAllAcceptedCredentials(options) is executed. Therefore, WebAuthn Relying Parties may choose to run signalAllAcceptedCredentials(options) periodically, e.g. on every sign in.

Note: Credentials not present in allAcceptedCredentialIds will be removed or hidden, potentially irreversibly. Relying parties must exercise care that valid credential IDs are never omitted from the list. If a valid credential ID were accidentally omitted, the relying party should immediately include it in signalAllAcceptedCredentials(options) as soon as possible to "un-hide" it, if supported by the authenticator.

Authenticators SHOULD, whenever possible, prefer hiding public key credentials for a period of time instead of permanently removing them, to aid recovery if a WebAuthn Relying Party accidentally omits valid credential IDs from allAcceptedCredentialIds.

5.1.10.4. signalCurrentUserDetails(options)

The signalCurrentUserDetails method signals the user’s current name and displayName.

Upon invocation of signalCurrentUserDetails(options), the client executes these steps:

1. If the result of base64url decoding options.userId is an error, then return a promise rejected with a TypeError.

2. Let p be the result of executing the Asynchronous RP ID validation algorithm with options.rpId.

3. Upon fulfillment of p, run the following steps in parallel:

   1. For every authenticator presently available on this client platform, invoke the currentUserDetails authenticator action with options as input.

4. Return p.

The currentUserDetails authenticator action takes a CurrentUserDetailsOptions options and is as follows:

1. Let userId be result of base64url decoding options.userId.

2. Assertion: userId is not an error.

3. Let credential be credentials map[options.rpId, userId].

4. If credential does not exist, abort these steps.

5. Update the credential’s otherUI to match options.name and options.displayName.

PublicKeyCredentialsignalCurrentUserDetails
 rpId 
 userId  
 name 
 displayName 

Note: Authenticators might not be attached at the time signalCurrentUserDetails(options) is executed. Therefore, WebAuthn Relying Parties may choose to run signalCurrentUserDetails(options) periodically, e.g. on every sign in.

5.2. Authenticator Responses (interface AuthenticatorResponse)

Authenticators respond to Relying Party requests by returning an object derived from the AuthenticatorResponse interface:

[, =]
  {
 []    ;
};

5.2.1. Information About Public Key Credential (interface AuthenticatorAttestationResponse)

The AuthenticatorAttestationResponse interface represents the authenticator’s response to a client’s request for the creation of a new public key credential. It contains information about the new credential that can be used to identify it for later use, and metadata that can be used by the WebAuthn Relying Party to assess the characteristics of the credential during registration.

[, =]
  :  {
 []    ;
 <> ();
  ();
 ? ();
  ();
};

5.2.1.1. Easily accessing credential data

Every user of the [[Create]](origin, options, sameOriginWithAncestors) method will need to parse and store the returned credential public key in order to verify future authentication assertions. However, the credential public key is in COSE format [RFC9052], inside the credentialPublicKey member of the attestedCredentialData, inside the authenticator data, inside the attestation object conveyed by AuthenticatorAttestationResponse.attestationObject. Relying Parties wishing to use attestation are obliged to do the work of parsing the attestationObject and obtaining the credential public key because that public key copy is the one the authenticator signed. However, many valid WebAuthn use cases do not require attestation. For those uses, user agents can do the work of parsing, expose the authenticator data directly, and translate the credential public key into a more convenient format.

The getPublicKey() operation thus returns the credential public key as a SubjectPublicKeyInfo. This ArrayBuffer can, for example, be passed to Java’s java.security.spec.X509EncodedKeySpec, .NET’s System.Security.Cryptography.ECDsa.ImportSubjectPublicKeyInfo, or Go’s crypto/x509.ParsePKIXPublicKey.

Use of getPublicKey() does impose some limitations: by using pubKeyCredParams, a Relying Party can negotiate with the authenticator to use public key algorithms that the user agent may not understand. However, if the Relying Party does so, the user agent will not be able to translate the resulting credential public key into SubjectPublicKeyInfo format and the return value of getPublicKey() will be null.

User agents MUST be able to return a non-null value for getPublicKey() when the credential public key has a COSEAlgorithmIdentifier value of:

• -7 (ES256), where kty is 2 (with uncompressed points) and crv is 1 (P-256).

• -257 (RS256).

• -8 (EdDSA), where crv is 6 (Ed25519).

A SubjectPublicKeyInfo does not include information about the signing algorithm (for example, which hash function to use) that is included in the COSE public key. To provide this, getPublicKeyAlgorithm() returns the COSEAlgorithmIdentifier for the credential public key.

To remove the need to parse CBOR at all in many cases, getAuthenticatorData() returns the authenticator data from attestationObject. The authenticator data contains other fields that are encoded in a binary format. However, helper functions are not provided to access them because Relying Parties already need to extract those fields when getting an assertion. In contrast to credential creation, where signature verification is optional, Relying Parties should always be verifying signatures from an assertion and thus must extract fields from the signed authenticator data. The same functions used there will also serve during credential creation.

Relying Parties SHOULD use feature detection before using these functions by testing the value of 'getPublicKey' in AuthenticatorAttestationResponse.prototype.

Note: getPublicKey() and getAuthenticatorData() were only added in Level 2 of this specification. Relying Parties that require these functions to exist may not interoperate with older user-agents.

5.2.2. Web Authentication Assertion (interface AuthenticatorAssertionResponse)

The AuthenticatorAssertionResponse interface represents an authenticator’s response to a client’s request for generation of a new authentication assertion given the WebAuthn Relying Party’s challenge and OPTIONAL list of credentials it is aware of. This response contains a cryptographic signature proving possession of the credential private key, and optionally evidence of user consent to a specific transaction.

[, =]
  :  {
 []    ;
 []    ;
 []   ? ;
};

5.3. Parameters for Credential Generation (dictionary PublicKeyCredentialParameters)

  {
   ;
   ;
};

5.4. Options for Credential Creation (dictionary PublicKeyCredentialCreationOptions)

  {
   ;
   ;

   ;
  <> ;

  ;
 <>  = [];
  ;
 <>  = [];
   = "none";
 <>  = [];
  ;
};

5.4.1. Public Key Entity Description (dictionary PublicKeyCredentialEntity)

The PublicKeyCredentialEntity dictionary describes a user account, or a WebAuthn Relying Party, which a public key credential is associated with or scoped to, respectively.

  {
   ;
};

5.4.2. Relying Party Parameters for Credential Generation (dictionary PublicKeyCredentialRpEntity)

The PublicKeyCredentialRpEntity dictionary is used to supply additional Relying Party attributes when creating a new credential.

  :  {
  ;
};

5.4.3. User Account Parameters for Credential Generation (dictionary PublicKeyCredentialUserEntity)

The PublicKeyCredentialUserEntity dictionary is used to supply additional user account attributes when creating a new credential.

  :  {
   ;
   ;
};

5.4.4. Authenticator Selection Criteria (dictionary AuthenticatorSelectionCriteria)

WebAuthn Relying Parties may use the AuthenticatorSelectionCriteria dictionary to specify their requirements regarding authenticator attributes.

  {
  ;
  ;
   = ;
   = "preferred";
};

5.4.5. Authenticator Attachment Enumeration (enum AuthenticatorAttachment)

This enumeration’s values describe authenticators' attachment modalities. Relying Parties use this to express a preferred authenticator attachment modality when calling navigator.credentials.create() to create a credential, and clients use this to report the authenticator attachment modality used to complete a registration or authentication ceremony.

  {
 ,
 
};

Note: The AuthenticatorAttachment enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

Note: An authenticator attachment modality selection option is available only in the [[Create]](origin, options, sameOriginWithAncestors) operation. The Relying Party may use it to, for example, ensure the user has a roaming credential for authenticating on another client device; or to specifically register a platform credential for easier reauthentication using a particular client device. The [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operation has no authenticator attachment modality selection option. The client and user will use whichever credential is available and convenient at the time, subject to the allowCredentials option.

5.4.6. Resident Key Requirement Enumeration (enum ResidentKeyRequirement)

  {
 ,
 ,
 
};

Note: The ResidentKeyRequirement enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

This enumeration’s values describe the Relying Party’s requirements for client-side discoverable credentials (formerly known as resident credentials or resident keys):

Note: The Relying Party can seek information on whether or not the authenticator created a client-side discoverable credential using the resident key credential property of the Credential Properties Extension. This is useful when values of discouraged or preferred are used for options.authenticatorSelection.residentKey, because in those cases it is possible for an authenticator to create either a client-side discoverable credential or a server-side credential.

5.4.7. Attestation Conveyance Preference Enumeration (enum AttestationConveyancePreference)

WebAuthn Relying Parties may use AttestationConveyancePreference to specify their preference regarding attestation conveyance during credential generation.

  {
 ,
 ,
 ,
 
};

Note: The AttestationConveyancePreference enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.5. Options for Assertion Generation (dictionary PublicKeyCredentialRequestOptions)

The PublicKeyCredentialRequestOptions dictionary supplies get() with the data it needs to generate an assertion. Its challenge member MUST be present, while its other members are OPTIONAL.

  {
   ;
  ;
  ;
 <>  = [];
   = "preferred";
 <>  = [];
  ;
};

challenge, of type BufferSource

This member specifies a challenge that the authenticator signs, along with other data, when producing an authentication assertion. See the § 13.5.3 Cryptographic Challenges security consideration.

timeout, of type unsigned long

This OPTIONAL member specifies a time, in milliseconds, that the Relying Party is willing to wait for the call to complete. The value is treated as a hint, and MAY be overridden by the client.

rpId, of type DOMString

This OPTIONAL member specifies the RP ID claimed by the Relying Party. The client MUST verify that the Relying Party’s origin matches the scope of this RP ID. The authenticator MUST verify that this RP ID exactly equals the rpId of the credential to be used for the authentication ceremony.

If not specified, its value will be the CredentialsContainer object’s relevant settings object’s origin’s effective domain.

allowCredentials, of type sequence<PublicKeyCredentialDescriptor>, defaulting to []

This OPTIONAL member is used by the client to find authenticators eligible for this authentication ceremony. It can be used in two ways:

• If the user account to authenticate is already identified (e.g., if the user has entered a username), then the Relying Party SHOULD use this member to list credential descriptors for credential records in the user account. This SHOULD usually include all credential records in the user account.

  The items SHOULD specify transports whenever possible. This helps the client optimize the user experience for any given situation. Also note that the Relying Party does not need to filter the list when requesting user verification — the client will automatically ignore non-eligible credentials if userVerification is set to required.

  See also the § 14.6.3 Privacy leak via credential IDs privacy consideration.

• If the user account to authenticate is not already identified, then the Relying Party MAY leave this member empty or unspecified. In this case, only discoverable credentials will be utilized in this authentication ceremony, and the user account MAY be identified by the userHandle of the resulting AuthenticatorAssertionResponse. If the available authenticators contain more than one discoverable credential scoped to the Relying Party, the credentials are displayed by the client platform or authenticator for the user to select from (see step 7 of § 6.3.3 The authenticatorGetAssertion Operation).

If not empty, the client MUST return an error if none of the listed credentials can be used.

The list is ordered in descending order of preference: the first item in the list is the most preferred credential, and the last is the least preferred.

userVerification, of type DOMString, defaulting to "preferred"

This OPTIONAL member specifies the Relying Party’s requirements regarding user verification for the get() operation. The value SHOULD be a member of UserVerificationRequirement but client platforms MUST ignore unknown values, treating an unknown value as if the member does not exist. Eligible authenticators are filtered to only those capable of satisfying this requirement.

See UserVerificationRequirement for the description of userVerification’s values and semantics.

hints, of type sequence<DOMString>, defaulting to []

This OPTIONAL member contains zero or more elements from PublicKeyCredentialHint to guide the user agent in interacting with the user. Note that the elements have type DOMString despite being taken from that enumeration. See § 2.1.1 Enumerations as DOMString types.

extensions, of type AuthenticationExtensionsClientInputs

The Relying Party MAY use this OPTIONAL member to provide client extension inputs requesting additional processing by the client and authenticator.

The extensions framework is defined in § 9 WebAuthn Extensions. Some extensions are defined in § 10 Defined Extensions; consult the IANA "WebAuthn Extension Identifiers" registry [IANA-WebAuthn-Registries] established by [RFC8809] for an up-to-date list of registered WebAuthn Extensions.

5.6. Abort Operations with AbortSignal

Developers are encouraged to leverage the AbortController to manage the [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operations. See DOM § 3.3 Using AbortController and AbortSignal objects in APIs section for detailed instructions.

Note: DOM § 3.3 Using AbortController and AbortSignal objects in APIs section specifies that web platform APIs integrating with the AbortController must reject the promise immediately once the AbortSignal is aborted. Given the complex inheritance and parallelization structure of the [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) methods, the algorithms for the two APIs fulfills this requirement by checking the aborted property in three places. In the case of [[Create]](origin, options, sameOriginWithAncestors), the aborted property is checked first in Credential Management 1 § 2.5.4 Create a Credential immediately before calling [[Create]](origin, options, sameOriginWithAncestors), then in § 5.1.3 Create a New Credential - PublicKeyCredential’s [[Create]](origin, options, sameOriginWithAncestors) Internal Method right before authenticator sessions start, and finally during authenticator sessions. The same goes for [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors).

5.7. WebAuthn Extensions Inputs and Outputs

The subsections below define the data types used for conveying WebAuthn extension inputs and outputs.

Note: Authenticator extension outputs are conveyed as a part of authenticator data (see Table 1).

Note: The types defined below — AuthenticationExtensionsClientInputs and AuthenticationExtensionsClientOutputs — are applicable to both registration extensions and authentication extensions. The "Authentication..." portion of their names should be regarded as meaning "WebAuthentication..."

5.7.1. Authentication Extensions Client Inputs (dictionary AuthenticationExtensionsClientInputs)

  {
};

This is a dictionary containing the client extension input values for zero or more WebAuthn Extensions.

5.7.2. Authentication Extensions Client Outputs (dictionary AuthenticationExtensionsClientOutputs)

  {
};

This is a dictionary containing the client extension output values for zero or more WebAuthn Extensions.

5.7.3. Authentication Extensions Authenticator Inputs (CDDL type AuthenticationExtensionsAuthenticatorInputs)

AuthenticationExtensionsAuthenticatorInputs = {
 * $$extensionInput
} .within { * tstr => any }

The CDDL type AuthenticationExtensionsAuthenticatorInputs defines a CBOR map containing the authenticator extension input values for zero or more WebAuthn Extensions. Extensions can add members as described in § 9.3 Extending Request Parameters.

This type is not exposed to the Relying Party, but is used by the client and authenticator.

5.7.4. Authentication Extensions Authenticator Outputs (CDDL type AuthenticationExtensionsAuthenticatorOutputs)

AuthenticationExtensionsAuthenticatorOutputs = {
 * $$extensionOutput
} .within { * tstr => any }

The CDDL type AuthenticationExtensionsAuthenticatorOutputs defines a CBOR map containing the authenticator extension output values for zero or more WebAuthn Extensions. Extensions can add members as described in § 9.3 Extending Request Parameters.

5.8. Supporting Data Structures

The public key credential type uses certain data structures that are specified in supporting specifications. These are as follows.

5.8.1. Client Data Used in WebAuthn Signatures (dictionary CollectedClientData)

The client data represents the contextual bindings of both the WebAuthn Relying Party and the client. It is a key-value mapping whose keys are strings. Values can be any type that has a valid encoding in JSON. Its structure is defined by the following Web IDL.

Note: The CollectedClientData may be extended in the future. Therefore it’s critical when parsing to be tolerant of unknown keys and of any reordering of the keys. See also § 5.8.1.2 Limited Verification Algorithm.

  {
   ;
   ;
   ;
  ;
  ;
};

  {
   ;
  ;
};

  { ,  };

5.8.1.1. Serialization

The serialization of the CollectedClientData is a subset of the algorithm for JSON-serializing to bytes. I.e. it produces a valid JSON encoding of the CollectedClientData but also provides additional structure that may be exploited by verifiers to avoid integrating a full JSON parser. While verifiers are recommended to perform standard JSON parsing, they may use the more limited algorithm below in contexts where a full JSON parser is too large. This verification algorithm requires only base64url encoding, appending of bytestrings (which could be implemented by writing into a fixed template), and simple conditional checks (assuming that inputs are known not to need escaping).

The serialization algorithm works by appending successive byte strings to an, initially empty, partial result until the complete result is obtained.

1. Let result be an empty byte string.

2. Append 0x7b2274797065223a ({"type":) to result.

3. Append CCDToString(type) to result.

4. Append 0x2c226368616c6c656e6765223a (,"challenge":) to result.

5. Append CCDToString(challenge) to result.

6. Append 0x2c226f726967696e223a (,"origin":) to result.

7. Append CCDToString(origin) to result.

8. Append 0x2c2263726f73734f726967696e223a (,"crossOrigin":) to result.

9. If crossOrigin is not present, or is false:

   1. Append 0x66616c7365 (false) to result.

10. Otherwise:

    1. Append 0x74727565 (true) to result.

11. If topOrigin is present:

    1. Append 0x2c22746f704f726967696e223a (,"topOrigin":) to result.

    2. Append CCDToString(topOrigin) to result.

12. Create a temporary copy of the CollectedClientData and remove the fields type, challenge, origin, crossOrigin (if present), and topOrigin (if present).

13. If no fields remain in the temporary copy then:

    1. Append 0x7d (}) to result.

14. Otherwise:

    1. Invoke serialize JSON to bytes on the temporary copy to produce a byte string remainder.

    2. Append 0x2c (,) to result.

    3. Remove the leading byte from remainder.

    4. Append remainder to result.

15. The result of the serialization is the value of result.

The function CCDToString is used in the above algorithm and is defined as:

1. Let encoded be an empty byte string.

2. Append 0x22 (") to encoded.

3. Invoke ToString on the given object to convert to a string.

4. For each code point in the resulting string, if the code point:

   is in the set {U+0020, U+0021, U+0023–U+005B, U+005D–U+10FFFF}

   Append the UTF-8 encoding of that code point to encoded.

   is U+0022

   Append 0x5c22 (\") to encoded.

   is U+005C

   Append 0x5c5c () to encoded.

   otherwise

   Append 0x5c75 (\u) to encoded, followed by four, lower-case hex digits that, when interpreted as a base-16 number, represent that code point.

5. Append 0x22 (") to encoded.

6. The result of this function is the value of encoded.

5.8.1.2. Limited Verification Algorithm

Verifiers may use the following algorithm to verify an encoded CollectedClientData if they cannot support a full JSON parser:

1. The inputs to the algorithm are:

   1. A bytestring, clientDataJSON, that contains clientDataJSON — the serialized CollectedClientData that is to be verified.

   2. A string, type, that contains the expected type.

   3. A byte string, challenge, that contains the challenge byte string that was given in the PublicKeyCredentialRequestOptions or PublicKeyCredentialCreationOptions.

   4. A string, origin, that contains the expected origin that issued the request to the user agent.

   5. An optional string, topOrigin, that contains the expected topOrigin that issued the request to the user agent, if available.

   6. A boolean, requireTopOrigin, that is true if, and only if, the verification should fail if topOrigin is defined and the topOrigin attribute is not present in clientDataJSON.

      This means that the verification algorithm is backwards compatible with the JSON-compatible serialization algorithm in Web Authentication Level 2 [webauthn-2-20210408] if, and only if, requireTopOrigin is false.

2. Let expected be an empty byte string.

3. Append 0x7b2274797065223a ({"type":) to expected.

4. Append CCDToString(type) to expected.

5. Append 0x2c226368616c6c656e6765223a (,"challenge":) to expected.

6. Perform base64url encoding on challenge to produce a string, challengeBase64.

7. Append CCDToString(challengeBase64) to expected.

8. Append 0x2c226f726967696e223a (,"origin":) to expected.

9. Append CCDToString(origin) to expected.

10. Append 0x2c2263726f73734f726967696e223a (,"crossOrigin":) to expected.

11. If topOrigin is defined:

    1. Append 0x74727565 (true) to expected.

    2. If requireTopOrigin is true or if 0x2c22746f704f726967696e223a (,"topOrigin":) is a prefix of the substring of clientDataJSON beginning at the offset equal to the length of expected:

       1. Append 0x2c22746f704f726967696e223a (,"topOrigin":) to expected.

       2. Append CCDToString(topOrigin) to expected.

12. Otherwise, i.e. topOrigin is not defined:

    1. Append 0x66616c7365 (false) to expected.

13. If expected is not a prefix of clientDataJSON then the verification has failed.

14. If clientDataJSON is not at least one byte longer than expected then the verification has failed.

15. If the byte of clientDataJSON at the offset equal to the length of expected:

    is 0x7d

    The verification is successful.

    is 0x2c

    The verification is successful.

    otherwise

    The verification has failed.

5.8.1.3. Future development

In order to remain compatible with the limited verification algorithm, future versions of this specification must not remove any of the fields type, challenge, origin, crossOrigin, or topOrigin from CollectedClientData. They also must not change the serialization algorithm to change the order in which those fields are serialized, or insert new fields between them.

If additional fields are added to CollectedClientData then verifiers that employ the limited verification algorithm will not be able to consider them until the two algorithms above are updated to include them. Once such an update occurs then the added fields inherit the same limitations as described in the previous paragraph. Such an algorithm update would have to accomodate serializations produced by previous versions. I.e. the verification algorithm would have to handle the fact that a sixth key–value pair may not appear sixth (or at all) if generated by a user agent working from a previous version.

5.8.2. Credential Type Enumeration (enum PublicKeyCredentialType)

  {
 
};

Note: The PublicKeyCredentialType enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.8.3. Credential Descriptor (dictionary PublicKeyCredentialDescriptor)

  {
   ;
   ;
 <> ;
};

This dictionary identifies a specific public key credential. It is used in create() to prevent creating duplicate credentials on the same authenticator, and in get() to determine if and how the credential can currently be reached by the client.

The credential descriptor for a credential record is a subset of the properties of that credential record, and mirrors some fields of the PublicKeyCredential object returned by create() and get().

5.8.4. Authenticator Transport Enumeration (enum AuthenticatorTransport)

  {
 ,
 ,
 ,
 ,
 ,
 
};

Note: The AuthenticatorTransport enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.8.5. Cryptographic Algorithm Identifier (typedef COSEAlgorithmIdentifier)

  ;

Note: There are many checks neccessary to correctly implement signature verification using these algorithms. One of these is that, when processing uncompressed elliptic-curve points, implementations should check that the point is actually on the curve. This check is highlighted because it’s judged to be at particular risk of falling through the gap between a cryptographic library and other code.

5.8.6. User Verification Requirement Enumeration (enum UserVerificationRequirement)

  {
 ,
 ,
 
};

A WebAuthn Relying Party may require user verification for some of its operations but not for others, and may use this type to express its needs.

Note: The UserVerificationRequirement enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.8.7. Client Capability Enumeration (enum ClientCapability)

  {
 ,
 ,
 ,
 ,
 ,
 ,
 ,
 ,
 
};

This enumeration defines a limited set of client capabilities which a WebAuthn Relying Party may evaluate to offer certain workflows and experiences to users.

Relying Parties may use the getClientCapabilities() method of PublicKeyCredential to obtain a description of available capabilities.

Note: The ClientCapability enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.8.8. User-agent Hints Enumeration (enum PublicKeyCredentialHint)

  {
 ,
 ,
 ,
};

Note: The PublicKeyCredentialHint enumeration is deliberately not referenced, see § 2.1.1 Enumerations as DOMString types.

5.9. Permissions Policy integration

This specification defines three policy-controlled features [Permissions-Policy].

Two features are identified by the feature-identifier tokens "publickey-credentials-create" and "publickey-credentials-get". Their default allowlists are both 'self'.

A third feature is identified by the feature-identifier token "publickey-credentials-remote-client-data-json". Its default allowlist is 'none', meaning it is disabled for all origins by default. This feature is also a powerful feature ([Permissions]) identified by the name "publickey-credentials-remote-client-data-json", with default permission state "denied".

A Document’s permissions policy determines whether any content in that document is allowed to successfully invoke the Web Authentication API, i.e., via navigator.credentials.create({publicKey:..., ...}) or navigator.credentials.get({publicKey:..., ...}) If disabled in any document, no content in the document will be allowed to use the foregoing methods: attempting to do so will return an error.

Note: Algorithms specified in [CREDENTIAL-MANAGEMENT-1] perform the actual permissions policy evaluation. This is because such policy evaluation needs to occur when there is access to the current settings object. The [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) internal methods do not have such access since they are invoked in parallel by CredentialsContainer’s Create a Credential and Request a Credential abstract operations [CREDENTIAL-MANAGEMENT-1].

5.10. Using Web Authentication within iframe elements

The Web Authentication API is disabled by default in cross-origin iframes. To override this default policy and indicate that a cross-origin iframe is allowed to invoke the Web Authentication API’s [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) methods, specify the allow attribute on the iframe element and include the publickey-credentials-create or publickey-credentials-get feature-identifier token, respectively, in the allow attribute’s value.

Relying Parties utilizing the WebAuthn API in an embedded context should review § 13.5.2 Visibility Considerations for Embedded Usage regarding UI redressing and its possible mitigations.

5.11. Using Web Authentication across related origins

By default, Web Authentication requires that the RP ID be equal to the origin’s effective domain, or a registrable domain suffix of the origin’s effective domain.

This can make deployment challenging for large environments where multiple country-specific domains are in use (e.g. example.com vs example.co.uk vs example.sg), where alternative or brand domains are required (e.g. myexampletravel.com vs examplecruises.com), and/or where platform as a service providers are used to support mobile apps.

WebAuthn Relying Parties can opt in to allowing WebAuthn Clients to enable a credential to be created and used across a limited set of related origins. Such Relying Parties MUST choose a common RP ID to use across all ceremonies from related origins.

A JSON document MUST be hosted at the webauthn well-known URL [RFC8615] for the RP ID, and MUST be served using HTTPS. The JSON document MUST be returned as follows:

• The content type MUST be application/json.

• The top-level JSON object MUST contain a key named origins whose value MUST be an array of one or more strings containing web origins.

For example, for the RP ID example.com:

WebAuthn Clients supporting this feature MUST support at least five registrable origin labels. Client policy SHOULD define an upper limit to prevent abuse.

Requests to this well-known endpoint by WebAuthn Clients MUST be made without credentials, without a referrer, and using the https: scheme. When following redirects, WebAuthn Clients MUST explicitly require all redirects to also use the https: scheme.

WebAuthn Clients supporting this feature SHOULD include relatedOrigins in their response to getClientCapabilities().

5.11.1. Validating Related Origins

The related origins validation procedure, given arguments callerOrigin and rpIdRequested, is as follows:

1. Let maxLabels be the maximum number of registrable origin labels allowed by client policy.

2. Fetch the webauthn well-known URL [RFC8615] for the RP ID rpIdRequested (i.e., https://rpIdRequested/.well-known/webauthn) without credentials, without a referrer and using the https: scheme.

   1. If the fetch fails, the response does not have a content type of application/json, or does not have a status code (after following redirects) of 200, then throw a "SecurityError" DOMException.

   2. If the body of the resource is not a valid JSON object, then throw a "SecurityError" DOMException.

   3. If the value of the origins property of the JSON object is missing, or is not an array of strings, then throw a "SecurityError" DOMException.

3. Let labelsSeen be a new empty set.

4. For each originItem of origins:

   1. Let url be the result of running the URL parser with originItem as the input. If that fails, continue.

   2. Let domain be the effective domain of url. If that is null, continue.

   3. Let label be registrable origin label of domain.

   4. If label is empty or null, continue.

   5. If the size of labelsSeen is greater than or equal to maxLabels and labelsSeen does not contain label, continue.

   6. If callerOrigin and url are same origin, return true.

   7. If the size of labelsSeen is less than maxLabels, append label to labelsSeen.

5. Return false.