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.4 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, as well as outline further scenarios. Additional scenarios, including sample code, are given later in § 1.3 Sample API Usage Scenarios.

1.2.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 register this device with 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.2. Authentication

• On a laptop or desktop:

  • User pairs their phone with the laptop or desktop via Bluetooth.

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

  • User gets a message from the browser, "Please complete this action on your 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.3. New Device Registration

This use case scenario illustrates how a Relying Party can leverage a combination of a roaming authenticator (e.g., a USB security key fob) 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.

Note: This approach of registering multiple authenticators for an account is also useful in account recovery use cases.

• First, on a desktop computer (lacking a platform authenticator):

  • 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.

  • User navigates to account security settings and selects "Register security key".

  • Website prompts the user to plug in a USB security key fob; the user does.

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

  • Website shows message, "Registration complete."

  Note: Since this computer lacks a platform authenticator, the website may require the user to present their USB security key from time to time or each time the user interacts with the website. This is at the website’s discretion.

• Later, on their laptop (which features a platform authenticator):

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

  • Website prompts the user to plug in their USB security key.

  • User plugs in the previously registered USB security key and presses the button.

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

  • Website prompts, "Do you want to register this computer with example.com?"

  • User agrees.

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

  • Website shows message, "Registration complete."

  • User signs out.

• Later, again on their laptop:

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

  • Website shows message, "Please follow your computer’s prompts to complete sign in."

  • Laptop prompts the user for an authorization gesture (PIN, biometric, etc.); the user provides this.

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

1.2.4. 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 "fob" with USB or USB+NFC/BLE 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 fob.

• 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 first-factor 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:

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

var publicKey = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([21,31,105 /* 29 more random bytes generated by the server */]),

  // Relying Party:
  rp: {
    name: "ACME Corporation"
  },

  // User:
  user: {
    id: Uint8Array.from(window.atob("MIIBkzCCATigAwIBAjCCAZMwggE4oAMCAQIwggGTMII="), c=>c.charCodeAt(0)),
    name: "[email protected]",
    displayName: "Alex Müller",
  },

  // This Relying Party will accept either an ES256 or RS256 credential, but
  // prefers an ES256 credential.
  pubKeyCredParams: [
    {
      type: "public-key",
      alg: -7 // "ES256" as registered in the IANA COSE Algorithms registry
    },
    {
      type: "public-key",
      alg: -257 // Value registered by this specification for "RS256"
    }
  ],

  authenticatorSelection: {
    // Try to use UV if possible. This is also the default.
    userVerification: "preferred"
  },

  timeout: 300000,  // 5 minutes
  excludeCredentials: [
    // Don’t re-register any authenticator that has one of these credentials
    {"id": Uint8Array.from(window.atob("ufJWp8YGlibm1Kd9XQBWN1WAw2jy5In2Xhon9HAqcXE="), c=>c.charCodeAt(0)), "type": "public-key"},
    {"id": Uint8Array.from(window.atob("E/e1dhZc++mIsz4f9hb6NifAzJpF1V4mEtRlIPBiWdY="), c=>c.charCodeAt(0)), "type": "public-key"}
  ],

  // Make excludeCredentials check backwards compatible with credentials registered with U2F
  extensions: {"appidExclude": "https://acme.example.com"}
};

// Note: The following call will cause the authenticator to display UI.
navigator.credentials.create({ publicKey })
  .then(function (newCredentialInfo) {
    // Send new credential info to server for verification and registration.
  }).catch(function (err) {
    // No acceptable authenticator or user refused consent. Handle appropriately.
  });

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.

if (!window.PublicKeyCredential) { /* Client not capable of the API. Handle error. */ }

PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()
    .then(function (uvpaAvailable) {
        // If there is a user-verifying platform authenticator
        if (uvpaAvailable) {
            // Render some RP-specific UI and get a Promise for a Boolean value
            return askIfUserWantsToCreateCredential();
        }
    }).then(function (userSaidYes) {
        // If there is a user-verifying platform authenticator
        // AND the user wants to create a credential
        if (userSaidYes) {
            var publicKeyOptions = { /* Public key credential creation options. */};
            return navigator.credentials.create({ "publicKey": publicKeyOptions });
        }
    }).then(function (newCredentialInfo) {
        if (newCredentialInfo) {
            // Send new credential info to server for verification and registration.
        }
    }).catch(function (err) {
        // Something went wrong. Handle appropriately.
    });

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:

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

// credentialId is generated by the authenticator and is an opaque random byte array
var credentialId = new Uint8Array([183, 148, 245 /* more random bytes previously generated by the authenticator */]);
var options = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([4,101,15 /* 29 more random bytes generated by the server */]),
  timeout: 300000,  // 5 minutes
  allowCredentials: [{ type: "public-key", id: credentialId }]
};

navigator.credentials.get({ "publicKey": options })
    .then(function (assertion) {
    // Send assertion to server for verification
}).catch(function (err) {
    // No acceptable credential or user refused consent. Handle appropriately.
});

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.

if (!window.PublicKeyCredential) { /* Client not capable. Handle error. */ }

var encoder = new TextEncoder();
var acceptableCredential1 = {
    type: "public-key",
    id: encoder.encode("BA44712732CE")
};
var acceptableCredential2 = {
    type: "public-key",
    id: encoder.encode("BG35122345NF")
};

var options = {
  // The challenge is produced by the server; see the Security Considerations
  challenge: new Uint8Array([8,18,33 /* 29 more random bytes generated by the server */]),
  timeout: 300000,  // 5 minutes
  allowCredentials: [acceptableCredential1, acceptableCredential2],
  extensions: { 'credProps': true }
};

navigator.credentials.get({ "publicKey": options })
    .then(function (assertion) {
    // Send assertion to server for verification
}).catch(function (err) {
    // No acceptable credential or user refused consent. Handle appropriately.
});

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.

const authAbortController = new AbortController();
const authAbortSignal = authAbortController.signal;

authAbortSignal.onabort = function () {
    // Once the page knows the abort started, inform user it is attempting to abort.
}

var options = {
    // A list of options.
}

navigator.credentials.create({
    publicKey: options,
    signal: authAbortSignal})
    .then(function (attestation) {
        // Register the user.
    }).catch(function (error) {
        if (error == "AbortError") {
            // Inform user the credential hasn’t been created.
            // Let the server know a key hasn’t been created.
        }
    });

// Assume widget shows up whenever authentication occurs.
if (widget == "disappear") {
    authAbortController.abort();
}

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.4.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].

HTML

The concepts of browsing context, origin, opaque origin, tuple origin, relevant settings object, same site and is a registrable domain suffix of or is equal to are defined in [HTML].

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", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

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

User Credential

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.

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.

Hardware-bound Device Key Pair

Device-bound Key

Device Private Key

Device Public Key

A hardware-bound device key pair, also known as a device-bound key, is an authenticator-, Relying Party-, and user credential-specific public key pair created upon a Relying Party's request via the devicePubKey WebAuthn extension. The authenticator that a hardware-bound device key pair is created upon guarantees that the device private key is securely stored in hardware, i.e., it is unextractable. See also § 10.2.2 Device-bound public key extension (devicePubKey).

Note: All guarantees about the operation of an authenticator operation rely on attestation. In particular, Relying Parties MUST NOT rely on the above guarantee of unextractability unless supported by a valid, trusted attestation statement.

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.

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) Method and § 5.1.4 Use an Existing Credential to Make an Assertion - PublicKeyCredential’s [[Get]](options) Method.

Note: 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.

• The origin's scheme must be https.

• 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.

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.

Also, 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.

[SecureContext, Exposed=Window]
interface PublicKeyCredential : Credential {
    [SameObject] readonly attribute ArrayBuffer              rawId;
    [SameObject] readonly attribute AuthenticatorResponse    response;
    [SameObject] readonly attribute DOMString?               authenticatorAttachment;
    AuthenticationExtensionsClientOutputs getClientExtensionResults();
    static Promise<boolean> isConditionalMediationAvailable();
    PublicKeyCredentialJSON toJSON();
};

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. 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.

Note: If this method is not present, conditional user mediation is not available.

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().

typedef DOMString Base64URLString;
typedef (RegistrationResponseJSON or AuthenticationResponseJSON) PublicKeyCredentialJSON;

dictionary RegistrationResponseJSON {
    required Base64URLString id;
    required Base64URLString rawId;
    required AuthenticatorAttestationResponseJSON response;
    DOMString authenticatorAttachment;
    required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
    required DOMString type;
};

dictionary AuthenticatorAttestationResponseJSON {
    required Base64URLString clientDataJSON;
    required Base64URLString authenticatorData;
    required sequence<DOMString> transports;
    // 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.
    Base64URLString publicKey;
    required long long publicKeyAlgorithm;
    // This value contains copies of some of the fields above. See
    // section “Easily accessing credential data”.
    required Base64URLString attestationObject;
};

dictionary AuthenticationResponseJSON {
    required Base64URLString id;
    required Base64URLString rawId;
    required AuthenticatorAssertionResponseJSON response;
    DOMString authenticatorAttachment;
    required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
    required DOMString type;
};

dictionary AuthenticatorAssertionResponseJSON {
    required Base64URLString clientDataJSON;
    required Base64URLString authenticatorData;
    required Base64URLString signature;
    Base64URLString userHandle;
    Base64URLString attestationObject;
};

dictionary AuthenticationExtensionsClientOutputsJSON {
};

[[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.

Note: This API does not constrain the format or length of this identifier, except that it 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).

5.1.1. CredentialCreationOptions Dictionary Extension

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

partial dictionary CredentialCreationOptions {
    PublicKeyCredentialCreationOptions      publicKey;
};

5.1.2. CredentialRequestOptions Dictionary Extension

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

partial dictionary CredentialRequestOptions {
    PublicKeyCredentialRequestOptions      publicKey;
};

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

5.1.4. Use an Existing Credential to Make an Assertion - PublicKeyCredential’s [[Get]](options) Method

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]]() to have the user select a public key credential source.

Since this specification requires an authorization gesture to create any assertions, the PublicKeyCredential.[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors) internal method inherits the default behavior of Credential.[[CollectFromCredentialStore]](), of returning an empty set.

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. Relying Party script SHOULD first check that isConditionalMediationAvailable() returns true in order to avoid the possibility of causing a user-visible error to be returned if the user agent does not support conditional user mediation.

This 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) Method

5.1.4.2. Issuing a Credential Request to an Authenticator

This sub-algorithm of [[DiscoverFromExternalSource]]() encompasses the specific UI context-independent steps necessary for requesting a credential from a given authenticator, using given PublicKeyCredentialRequestOptions. It is called by [[DiscoverFromExternalSource]]() 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. Let enterpriseAttestationPossible be a Boolean value, as follows. If pkOptions.attestation

   is set to enterprise

   Let enterpriseAttestationPossible be true if the user agent wishes to support enterprise attestation for rpId (see Step 7 of § 5.1.4.1 PublicKeyCredential’s [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) Method). Otherwise false.

   otherwise

   Let enterpriseAttestationPossible be false.

4. Let attestationFormats be a list of strings, initialized to the value of pkOptions.attestationFormats.

5. If pkOptions.attestation

   is set to none

   Set attestationFormats be the single-element list containing the string “none”

6. 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, enterpriseAttestationPossible, attestationFormats, 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, enterpriseAttestationPossible, attestationFormats, 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, enterpriseAttestationPossible, attestationFormats, 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.

7. Return true.

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

5.1.6. Preventing Silent Access to an Existing Credential - PublicKeyCredential’s [[preventSilentAccess]](credential, sameOriginWithAncestors) Method

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

partial interface PublicKeyCredential {
    static Promise<boolean> isUserVerifyingPlatformAuthenticatorAvailable();
};

5.1.8. Availability of a passkey platform authenticator - PublicKeyCredential’s isPasskeyPlatformAuthenticatorAvailable() Method

partial interface PublicKeyCredential {
    static Promise<boolean> isPasskeyPlatformAuthenticatorAvailable();
};

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

partial interface PublicKeyCredential {
    static PublicKeyCredentialCreationOptions parseCreationOptionsFromJSON(PublicKeyCredentialCreationOptionsJSON options);
};

dictionary PublicKeyCredentialCreationOptionsJSON {
    required PublicKeyCredentialRpEntity                    rp;
    required PublicKeyCredentialUserEntityJSON              user;
    required Base64URLString                                challenge;
    required sequence<PublicKeyCredentialParameters>        pubKeyCredParams;
    unsigned long                                           timeout;
    sequence<PublicKeyCredentialDescriptorJSON>             excludeCredentials = [];
    AuthenticatorSelectionCriteria                          authenticatorSelection;
    sequence<DOMString>                                     hints = [];
    DOMString                                               attestation = "none";
    sequence<DOMString>                                     attestationFormats = [];
    AuthenticationExtensionsClientInputsJSON                extensions;
};

dictionary PublicKeyCredentialUserEntityJSON {
    required Base64URLString        id;
    required DOMString              name;
    required DOMString              displayName;
};

dictionary PublicKeyCredentialDescriptorJSON {
    required Base64URLString        id;
    required DOMString              type;
    sequence<DOMString>             transports;
};

dictionary AuthenticationExtensionsClientInputsJSON {
};

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

partial interface PublicKeyCredential {
    static PublicKeyCredentialRequestOptions parseRequestOptionsFromJSON(PublicKeyCredentialRequestOptionsJSON options);
};

dictionary PublicKeyCredentialRequestOptionsJSON {
    required Base64URLString                                challenge;
    unsigned long                                           timeout;
    DOMString                                               rpId;
    sequence<PublicKeyCredentialDescriptorJSON>             allowCredentials = [];
    DOMString                                               userVerification = "preferred";
    sequence<DOMString>                                     hints = [];
    DOMString                                               attestation = "none";
    sequence<DOMString>                                     attestationFormats = [];
    AuthenticationExtensionsClientInputsJSON                extensions;
};

5.2. Authenticator Responses (interface AuthenticatorResponse)

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

[SecureContext, Exposed=Window]
interface AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      clientDataJSON;
};

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.

[SecureContext, Exposed=Window]
interface AuthenticatorAttestationResponse : AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      attestationObject;
    sequence<DOMString>                              getTransports();
    ArrayBuffer                                      getAuthenticatorData();
    ArrayBuffer?                                     getPublicKey();
    COSEAlgorithmIdentifier                          getPublicKeyAlgorithm();
};

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.

Note: getPublicKey() and getAuthenticatorData() were only added in level two of this spec. Relying Parties SHOULD use feature detection before using these functions by testing the value of 'getPublicKey' in AuthenticatorAttestationResponse.prototype. Relying Parties that require this function 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.

[SecureContext, Exposed=Window]
interface AuthenticatorAssertionResponse : AuthenticatorResponse {
    [SameObject] readonly attribute ArrayBuffer      authenticatorData;
    [SameObject] readonly attribute ArrayBuffer      signature;
    [SameObject] readonly attribute ArrayBuffer?     userHandle;
    [SameObject] readonly attribute ArrayBuffer?     attestationObject;
};

5.3. Parameters for Credential Generation (dictionary PublicKeyCredentialParameters)

dictionary PublicKeyCredentialParameters {
    required DOMString                    type;
    required COSEAlgorithmIdentifier      alg;
};

5.4. Options for Credential Creation (dictionary PublicKeyCredentialCreationOptions)

dictionary PublicKeyCredentialCreationOptions {
    required PublicKeyCredentialRpEntity         rp;
    required PublicKeyCredentialUserEntity       user;

    required BufferSource                             challenge;
    required sequence<PublicKeyCredentialParameters>  pubKeyCredParams;

    unsigned long                                timeout;
    sequence<PublicKeyCredentialDescriptor>      excludeCredentials = [];
    AuthenticatorSelectionCriteria               authenticatorSelection;
    sequence<DOMString>                          hints = [];
    DOMString                                    attestation = "none";
    sequence<DOMString>                          attestationFormats = [];
    AuthenticationExtensionsClientInputs         extensions;
};

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.

dictionary PublicKeyCredentialEntity {
    required DOMString    name;
};

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.

dictionary PublicKeyCredentialRpEntity : PublicKeyCredentialEntity {
    DOMString      id;
};

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.

dictionary PublicKeyCredentialUserEntity : PublicKeyCredentialEntity {
    required BufferSource   id;
    required DOMString      displayName;
};

5.4.4. Authenticator Selection Criteria (dictionary AuthenticatorSelectionCriteria)

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

dictionary AuthenticatorSelectionCriteria {
    DOMString                    authenticatorAttachment;
    DOMString                    residentKey;
    boolean                      requireResidentKey = false;
    DOMString                    userVerification = "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.

enum AuthenticatorAttachment {
    "platform",
    "cross-platform"
};

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, so the Relying Party SHOULD accept any of the user’s registered credentials. The client and user will then use whichever is available and convenient at the time.

5.4.6. Resident Key Requirement Enumeration (enum ResidentKeyRequirement)

enum ResidentKeyRequirement {
    "discouraged",
    "preferred",
    "required"
};

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.

enum AttestationConveyancePreference {
    "none",
    "indirect",
    "direct",
    "enterprise"
};

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.

dictionary PublicKeyCredentialRequestOptions {
    required BufferSource                challenge;
    unsigned long                        timeout;
    USVString                            rpId;
    sequence<PublicKeyCredentialDescriptor> allowCredentials = [];
    DOMString                            userVerification = "preferred";
    sequence<DOMString>                  hints = [];
    DOMString                            attestation = "none";
    sequence<DOMString>                  attestationFormats = [];
    AuthenticationExtensionsClientInputs extensions;
};

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.4.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 USVString

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 PublicKeyCredentialHints 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.

attestation, of type DOMString, defaulting to "none"

The Relying Party MAY use this OPTIONAL member to specify a preference regarding attestation conveyance. Its value SHOULD be a member of AttestationConveyancePreference. Client platforms MUST ignore unknown values, treating an unknown value as if the member does not exist.

The default value is none.

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

The Relying Party MAY use this OPTIONAL member to specify a preference regarding the attestation statement format used by the authenticator. Values SHOULD be taken from the IANA "WebAuthn Attestation Statement Format Identifiers" registry [IANA-WebAuthn-Registries] established by [RFC8809]. Values are ordered from most preferable to least preferable. This parameter is advisory and the authenticator MAY use an attestation statement not enumerated in this parameter.

The default value is the empty list, which indicates no preference.

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) Method right before authenticator sessions start, and finally during authenticator sessions. The same goes for [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors).

The visibility and focus state of the Window object determines whether the [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operations should continue. When the Window object associated with the Document loses focus, [[Create]](origin, options, sameOriginWithAncestors) and [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) operations SHOULD be aborted.

The WHATWG HTML WG is discussing whether to provide a hook when a browsing context gains or loses focuses. If a hook is provided, the above paragraph will be updated to include the hook. See WHATWG HTML WG Issue #2711 for more details.

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)

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)

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.

dictionary CollectedClientData {
    required DOMString           type;
    required DOMString           challenge;
    required DOMString           origin;
    DOMString                    topOrigin;
    boolean                      crossOrigin;
};

dictionary TokenBinding {
    required DOMString status;
    DOMString id;
};

enum TokenBindingStatus { "present", "supported" };

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. A boolean, crossOrigin, that is true if, and only if, the request should have been performed within a cross-origin iframe.

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 crossOrigin is true:

    1. Append 0x74727565 (true) to expected.

12. Otherwise, i.e. crossOrigin is false:

    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)

enum PublicKeyCredentialType {
    "public-key"
};

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

5.8.3. Credential Descriptor (dictionary PublicKeyCredentialDescriptor)

dictionary PublicKeyCredentialDescriptor {
    required DOMString                    type;
    required BufferSource                 id;
    sequence<DOMString>                   transports;
};

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. It mirrors some fields of the PublicKeyCredential object returned by create() and get().