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.