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 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: "alex.mueller@example.com",
    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: 360000,  // 6 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.