Web Authentication API

WebAuthn uses asymmetric (public-key) cryptography instead of passwords or SMS texts for registering, authenticating, and multi-factor authentication with websites. This has some benefits:

• Protection against phishing: An attacker who creates a fake login website can't login as the user because the signature changes with the origin of the website.
• Reduced impact of data breaches: Developers don't need to hash the public key, and if an attacker gets access to the public key used to verify the authentication, it can't authenticate because it needs the private key.
• Invulnerable to password attacks: Some users might reuse passwords, and an attacker may obtain the user's password for another website (e.g. via a data breach). Also, text passwords are much easier to brute-force than a digital signature.

Many websites already have pages that allow users to register new accounts or sign into an existing account, and WebAuthn acts as a replacement or enhancement for the authentication part of the system. It extends the Credential Management API, abstracting communication between the user agent and an authenticator and providing the following new functionality:

• When navigator.credentials.create() is used with the publicKey option, the user agent creates new credentials via an authenticator — either for registering a new account or for associating a new asymmetric key pair with an existing account.
  • When registering a new account, these credentials are stored on a server (also referred to as a service or a relying party) and can be subsequently used to log a user in.
  • The asymmetric key pair is stored in the authenticator, which can then be used to authenticate a user with a relying party for example during MFA. The authenticator may be embedded into the user agent, into an operating system, such as Windows Hello, or it may be a physical token, such as a USB or Bluetooth Security Key.
• When navigator.credentials.get() is used with the publicKey option, the user agent uses an existing set of credentials to authenticate to a relying party (either as the primary login or to provide an additional factor during MFA as described above).

In their most basic forms, both create() and get() receive a very large random number called the "challenge" from the server and return the challenge signed by the private key back to the server. This proves to the server that a user has the private key required for authentication without revealing any secrets over the network.

To illustrate how the credential creation process works, let's describe the typical flow that occurs when a user wants to register a credential to a relying party:

1. The relying party server sends user and relying party information to the web app handling the registration process, along with the "challenge", using an appropriate secure mechanism (for example Fetch or XMLHttpRequest).

   Note: The format for sharing information between the relying party server and the web app is up to the application. A recommended approach is to exchange JSON type representation objects for credentials and credential options. Convenience methods have been created in PublicKeyCredential for converting from the JSON representations to the form required by the authentication APIs: parseCreationOptionsFromJSON(), parseRequestOptionsFromJSON() and PublicKeyCredential.toJSON().

2. The web app initiates generation of a new credential via the authenticator, on behalf of the relying party, via a navigator.credentials.create() call. This call is passed a publicKey option specifying device capabilities, e.g., whether the device provides its own user authentication (for example with biometrics).

   A typical create() call might look like so:

   js

   let credential = await navigator.credentials.create({
     publicKey: {
       challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]),
       rp: { id: "acme.com", name: "ACME Corporation" },
       user: {
         id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),
         name: "jamiedoe",
         displayName: "Jamie Doe"
       },
       pubKeyCredParams: [ {type: "public-key", alg: -7} ]
     }
   });
   

   The parameters of the create() call are passed to the authenticator, along with a SHA-256 hash that is signed to ensure that it isn't tampered with.

3. After the authenticator obtains user consent, it generates a key pair and returns the public key and optional signed attestation to the web app. This is provided when the Promise returned by the create() call fulfills, in the form of a PublicKeyCredential object instance (the PublicKeyCredential.response property contains the attestation information).

4. The web app forwards the PublicKeyCredential to the server, again using an appropriate mechanism.

5. The server stores the public key, coupled with the user identity, to remember the credential for future authentications. During this process, it performs a series of checks to ensure that the registration was complete and not tampered with. These include:

   1. Verifying that the challenge is the same as the challenge that was sent.
   2. Ensuring that the origin was the origin expected.
   3. Validating that the signature and attestation are using the correct certificate chain for the specific model of the authenticator used to generated the key par in the first place.

After a user has registered with WebAuthn, they can authenticate (i.e., login) with the service. The authentication flow looks similar to the registration flow, the main differences being that authentication:

1. Doesn't require user or relying party information
2. Creates an assertion using the previously-generated key pair for the service, rather than the authenticator's key pair.

A typical authentication flow is as follows:

1. The relying party generates a "challenge" and sends it to the user agent using an appropriate secure mechanism, along with a list of relying party and user credentials. It can also indicate where to look for the credential, e.g., on a local built-in authenticator, or on an external one over USB, BLE, etc.

2. The browser asks the authenticator to sign the challenge via a navigator.credentials.get() call, which is passed the credentials in a publicKey option.

   A typical get() call might look like so:

   js

   let credential = await navigator.credentials.get({
     publicKey: {
       challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]),
       rpId: "acme.com",
       allowCredentials: [{
         type: "public-key",
         id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...])
       }],
       userVerification: "required",
     }
   });
   

   The parameters of the get() call are passed to the authenticator to handle the authentication.

3. If the authenticator contains one of the given credentials and is able to successfully sign the challenge, it returns a signed assertion to the web app after receiving user consent. This is provided when the Promise returned by the get() call fulfills, in the form of a PublicKeyCredential object instance (the PublicKeyCredential.response property contains the assertion information).

4. The web app forwards the signed assertion to the relying party server for the relying party to validate. The validation checks include:

   1. Using the public key that was stored during the registration request to validate the signature by the authenticator.
   2. Ensuring that the challenge that was signed by the authenticator matches the challenge that was generated by the server.
   3. Checking that the Relying Party ID is the one expected for this service.

5. Once verified by the server, the authentication flow is considered successful.

The availability of WebAuthn can be controlled using a Permissions Policy, specifying two directives in particular:

• publickey-credentials-create: Controls the availability of navigator.credentials.create() with the publicKey option.
• publickey-credentials-get: Controls the availability of navigator.credentials.get() with the publicKey option.

Both directives have a default allowlist value of "self", meaning that by default these methods can be used in top-level document contexts. In addition, get() can be used in nested browsing contexts loaded from the same origin as the top-most document. get() and create() can be used in nested browsing contexts loaded from the different origins to the top-most document (i.e. in cross-origin <iframes>), if allowed by the publickey-credentials-get and publickey-credentials-create Permission-Policy directives, respectively. For cross-origin create() calls, where the permission was granted by allow= on an iframe, the frame must also have Transient activation.

If you wish to allow access to a specific subdomain only, you could provide it like this:

Permissions-Policy: publickey-credentials-get=("https://subdomain.example.com")
Permissions-Policy: publickey-credentials-create=("https://subdomain.example.com")

If you wish to authenticate with get() or create() in an <iframe>, there are a couple of steps to follow:

1. The site embedding the relying party site must provide permission via an allow attribute:

   • If using get():

     html

     <iframe
       src="https://auth.provider.com"
       allow="publickey-credentials-get *">
     </iframe>
     

   • If using create():

     html

     <iframe
       src="https://auth.provider.com"
       allow="publickey-credentials-create 'self' https://a.auth.provider.com https://b.auth.provider.com">
     </iframe>
     

     The <iframe> must also have Transient activation if create() is called cross-origin.

2. The relying party site must provide permission for the above access via a Permissions-Policy header:

   http

   Permissions-Policy: publickey-credentials-get=*
   Permissions-Policy: publickey-credentials-create=*
   

   Or to allow only a specific URL to embed the relying party site in an <iframe>:

   http

   Permissions-Policy: publickey-credentials-get=("https://subdomain.example.com")
   Permissions-Policy: publickey-credentials-create=("https://*.auth.provider.com")
   

AuthenticatorAssertionResponse

Provides proof to a service that an authenticator has the necessary key pair to successfully handle an authentication request initiated by a CredentialsContainer.get() call. Available in the response property of the PublicKeyCredential instance obtained when the get() Promise fulfills.

AuthenticatorAttestationResponse

The result of a WebAuthn credential registration (i.e., a CredentialsContainer.create() call). It contains information about the credential that the server needs to perform WebAuthn assertions, such as its credential ID and public key. Available in the response property of the PublicKeyCredential instance obtained when the create() Promise fulfills.

AuthenticatorResponse

The base interface for AuthenticatorAttestationResponse and AuthenticatorAssertionResponse.

PublicKeyCredential

Provides information about a public key / private key pair, which is a credential for logging in to a service using an un-phishable and data-breach resistant asymmetric key pair instead of a password. Obtained when the Promise returned via a create() or get() call fulfills.

CredentialsContainer.create(), the publicKey option

Calling create() with a publicKey option initiates the creation of new asymmetric key credentials via an authenticator, as explained above.

CredentialsContainer.get(), the publicKey option

Calling get() with a publicKey option instructs the user agent uses an existing set of credentials to authenticate to a relying party.

• Mozilla Demo website and its source code.
• Google Demo website and its source code.
• WebAuthn.io demo website and its source code.
• github.com/webauthn-open-source and its client source code and server source code