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

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