This feature is available only in (HTTPS), in some or all . Secure context secure contexts supporting browsers The Web Authentication API is an extension of the that enables strong authentication with public key cryptography, enabling passwordless authentication and/or secure second-factor authentication without SMS texts. Credential Management API Web authentication concepts and usage The Web Authentication API (also referred to as WebAuthn) uses instead of passwords or SMS texts for registering, authenticating, and with websites. This resolves significant security problems related to , , and attacks against SMS texts or other second-factor authentication methods while at the same time significantly increasing ease of use (since users don't have to manage dozens of increasingly complicated passwords). asymmetric (public-key) cryptography second-factor authentication phishing data breaches Many websites already have pages that allow users to register new accounts or sign in to an existing account, and the Web Authentication API acts as a replacement or supplement to those on those existing webpages. Similar to the other forms of the , the Web Authentication API has two basic methods that correspond to register and login: Credential Management API - when used with the publicKey option, creates new credentials, either for registering a new account or for associating a new asymmetric key pair credentials with an existing account. navigator.credentials.create() - when used with the publicKey option, uses an existing set of credentials to authenticate to a service, either logging a user in or as a form of second-factor authentication. navigator.credentials.get() both create() and get() require a (e.g. - the server is connected by https or is the localhost), and will not be available for use if the browser is not operating in a secure context. Please note: Secure Context In their most basic forms, both create() and get() receive a very large random number called a challenge from the server and they return the challenge signed by the private key back to the server. This proves to the server that a user is in possession of the private key required for authentication without revealing any secrets over the network. In order to understand how the create() and get() methods fit into the bigger picture, it is important to understand that they sit between two components that are outside the browser: - the Web Authentication API is intended to register new credentials on a server (also referred to as a service or a ) and later use those same credentials on that same server to authenticate a user. Server relying party - the credentials are created and stored in a device called an authenticator. This is a new concept in authentication: when authenticating using passwords, the password is stored in a user's brain and no other device is needed; when authenticating using web authentication, the password is replaced with a key pair that is stored in an authenticator. The authenticator may be embedded into an operating system, such as Windows Hello, or may be a physical token, such as a USB or Bluetooth Security Key. Authenticator A typical registration process has six steps, as illustrated in Figure 1 and described further below. This is a simplification of the data required for the registration process that is only intended to provide an overview. Registration The full set of required fields, optional fields, and their meanings for creating a registration request can be found in the dictionary. PublicKeyCredentialCreationOptions Likewise, the full set of response fields can be found in the interface (where is the interface). Note most JavaScript programmers that are creating an application will only really care about steps 1 and 5 where the create() function is called and subsequently returns; however, steps 2, 3, and 4 are essential to understanding the processing that takes place in the browser and authenticator and what the resulting data means. PublicKeyCredential PublicKeyCredential.response AuthenticatorAttestationResponse Figure 1 - a diagram showing the sequence of actions for a web authentication registration and the essential data associated with each action. The registration steps are: - The application makes the initial registration request. The protocol and format of this request is outside of the scope of the Web Authentication API. 1. Application Requests Registration The server sends a challenge, user information, and relying party information to the JavaScript program. The protocol for communicating with the server is not specified and is outside of the scope of the Web Authentication API. Typically, server communications would be over https (probably using or ), but they could also be , or nearly any other protocol provided that the protocol is secure. 2. Server Sends Challenge, User Info, and Relying Party Info REST XMLHttpRequest Fetch SOAP RFC 2549 The parameters received from the server will be passed to the call, typically with little or no modification and returns a that will resolve to a containing an . create() Promise PublicKeyCredential AuthenticatorAttestationResponse Note that it is absolutely critical that the challenge be a buffer of random information (at least 16 bytes) and it MUST be generated on the server in order to ensure the security of the registration process. - Internally, the browser will validate the parameters and fill in any defaults, which become the .  One of the most important parameters is the origin, which is recorded as part of the clientData so that the origin can be verified by the server later. 3. Browser Calls authenticatorMakeCredential() on Authenticator AuthenticatorResponse.clientDataJSON The parameters to the create() call are passed to the authenticator, along with a SHA-256 hash of the clientDataJSON (only a hash is sent because the link to the authenticator may be a low-bandwidth NFC or Bluetooth link and the authenticator is just going to sign over the hash to ensure that it isn't tampered with). - Before doing anything, the authenticator will typically ask for some form of user verification. This could be entering a PIN, using a fingerprint, doing an iris scan, etc. to prove that the user is present and consenting to the registration. 4. Authenticator Creates New Key Pair and Attestation After the user verification, the authenticator will create a new asymmetric key pair and safely store the private key for future reference. The public key will become part of the attestation, which the authenticator will sign over with a private key that was burned into the authenticator during its manufacturing process and that has a certificate chain that can be validated back to a root of trust. - The new public key, a globally unique credential id, and other attestation data are returned to the browser where they become the attestationObject. 5. Authenticator Returns Data to Browser - The create() Promise resolves to an , which has a that is the globally unique credential id along with a response that is the containing the and . 6. Browser Creates Final Data, Application sends response to Server PublicKeyCredential PublicKeyCredential.rawId AuthenticatorAttestationResponse AuthenticatorResponse.clientDataJSON AuthenticatorAttestationResponse.attestationObject The is sent back to the server using any desired formatting and protocol (note that the ArrayBuffer properties need to be be base64 encoded or similar). PublicKeyCredential - Finally, the server is required to perform a series of checks to ensure that the registration was complete and not tampered with. These include: 7. Server Validates and Finalizes Registration Verifying that the challenge is the same as the challenge that was sent Ensuring that the origin was the origin expected Validating that the signature over the clientDataHash and the attestation using the certificate chain for that specific model of the authenticator A complete list of validation steps . Assuming that the checks pan out, the server will store the new public key associated with the user's account for future use -- that is, whenever the user desires to use the public key for authentication. After a user has registered with web authentication, they can subsequently authenticate (a.k.a. - login or sign-in) with the service. The authentication flow looks similar to the registration flow, and the illustration of actions in Figure 2 may be recognizable as being similar to the illustration of registration actions in Figure 1. can be found in the Web Authentication API specification Authentication The primary differences between registration and authentication are that: 1) authentication doesn't require user or relying party information; and 2) authentication creates an assertion using the previously generated key pair for the service rather than creating an attestation with the key pair that was burned into the authenticator during manufacturing. Again, the description of authentication below is a broad overview rather than getting into all the options and features of the Web Authentication API. The specific options for authenticating can be found in the dictionary, and the resulting data can be found in the interface (where is the interface) . PublicKeyCredentialRequestOptions PublicKeyCredential PublicKeyCredential.response AuthenticatorAssertionResponse Figure 2 - similar to Figure 1, a diagram showing the sequence of actions for a web authentication and the essential data associated with each action. - The application makes the initial authentication request. The protocol and format of this request is outside of the scope of the Web Authentication API. 1. Application Requests Authentication - The server sends a challenge to the JavaScript program. The protocol for communicating with the server is not specified and is outside of the scope of the Web Authentication API. Typically, server communications would be over https (probably using or ), but they could also be , or nearly any other protocol provided that the protocol is secure. The parameters received from the server will be passed to the call, typically with little or no modification. 2. Server Sends Challenge REST XMLHttpRequest Fetch SOAP RFC 2549 get() Note that it is absolutely critical that the challenge be a buffer of random information (at least 16 bytes) and it MUST be generated on the server in order to ensure the security of the authentication process. - Internally, the browser will validate the parameters and fill in any defaults, which become the . One of the most important parameters is the origin, which recorded as part of the clientData so that the origin can be verified by the server later. 3. Browser Calls authenticatorGetCredential() on Authenticator AuthenticatorResponse.clientDataJSON The parameters to the get() call are passed to the authenticator, along with a SHA-256 hash of the clientDataJSON (only a hash is sent because the link to the authenticator may be a low-bandwidth NFC or Bluetooth link and the authenticator is just going to sign over the hash to ensure that it isn't tampered with). - The authenticator finds a credential for this service that matches the Relying Party ID and prompts a user to consent to the authentication. Assuming both of those steps are successful, the authenticator will create a new assertion by signing over the clientDataHash and authenticatorData with the private key generated for this account during the registration call. 4. Authenticator Creates an Assertion - The authenticator returns the authenticatorData and assertion signature back to the browser. 5. Authenticator Returns Data to Browser - The browser resolves the to a with a that contains the . 6. Browser Creates Final Data, Application sends response to Server Promise PublicKeyCredential PublicKeyCredential.response AuthenticatorAssertionResponse It is up to the JavaScript application to transmit this data back to the server using any protocol and format of its choice. - Upon receiving the result of the authentication request, the server performs validation of the response such as: 7. Server Validates and Finalizes Authentication Using the public key that was stored during the registration request to validate the signature by the authenticator. Ensuring that the challenge that was signed by the authenticator matches the challenge that was generated by the server. Checking that the Relying Party ID is the one expected for this service. A full list of the . Assuming the validation is successful, the server will note that the user is now authenticated. This is outside the scope of the Web Authentication API specification, but one option would be to drop a new cookie for the user session. steps for validating an assertion can be found in the Web Authentication API specification Interfaces Credential Provides information about an entity as a prerequisite to a trust decision. CredentialsContainer Exposes methods to request credentials and notify the user agent when events such as successful sign in or sign out happen. This interface is accessible from . The Web Authentication specification adds a member to the and methods to either create a new public key pair or get an authentication for a key pair, repsectively. Navigator.credentials publicKey create() get() 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. AuthenticatorResponse The base interface for and , which provide a cryptographic root of trust for a key pair. Returned by and , respectively, the child interfaces include information from the browser such as the challenge origin. Either may be returned from . AuthenticatorAttestationResponse AuthenticatorAssertionResponse CredentialsContainer.create() CredentialsContainer.get() PublicKeyCredential.response AuthenticatorAttestationResponse Returned by when a is passed, and provides a cryptographic root of trust for the new key pair that has been generated. CredentialsContainer.create() PublicKeyCredential AuthenticatorAssertionResponse Returned by when a is passed, and provides proof to a service that it has a key pair and that the authentication request is valid and approved. CredentialsContainer.get() PublicKeyCredential Options PublicKeyCredentialCreationOptions The options passed to . CredentialsContainer.create() PublicKeyCredentialRequestOptions The options passed to . CredentialsContainer.get() Examples For security reasons, web authentication calls ( and ) are cancelled if the browser window loses focus while the call is pending. create() get() createCredentialDefaultArgs = { : { rp: { : }, user: { : ( ), : , : }, : [{ : , : }], : , : , : ([ , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ]).buffer
    }
}; getCredentialDefaultArgs = { : { : , challenge: ([ , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ]).buffer
    },
}; navigator.credentials.create(createCredentialDefaultArgs)
    .then( { .log( , cred); idList = [{ : cred.rawId, : [ , , ], : }];
        getCredentialDefaultArgs.publicKey.allowCredentials = idList; navigator.credentials.get(getCredentialDefaultArgs);
    })
    .then( { .log( , assertion);
    })
    .catch( { .log( , err);
    }); // sample arguments for registration var publicKey // Relying Party (a.k.a. - Service): name "Acme" // User: id new Uint8Array 16 name "john.p.smith@example.com" displayName "John P. Smith" pubKeyCredParams type "public-key" alg -7 attestation "direct" timeout 60000 challenge new Uint8Array // must be a cryptographically random number sent from a server 0x8C 0x0A 0x26 0xFF 0x22 0x91 0xC1 0xE9 0xB9 0x4E 0x2E 0x17 0x1A 0x98 0x6A 0x73 0x71 0x9D 0x43 0x48 0xD5 0xA7 0x6A 0x15 0x7E 0x38 0x94 0x52 0x77 0x97 0x0F 0xEF // sample arguments for login var publicKey timeout 60000 // allowCredentials: [newCredential] // see below new Uint8Array // must be a cryptographically random number sent from a server 0x79 0x50 0x68 0x71 0xDA 0xEE 0xEE 0xB9 0x94 0xC3 0xC2 0x15 0x67 0x65 0x26 0x22 0xE3 0xF3 0xAB 0x3B 0x78 0x2E 0xD5 0x6F 0x81 0x26 0xE2 0xA6 0x01 0x7D 0x74 0x50 // register / create a new credential ( ) => cred console "NEW CREDENTIAL" // normally the credential IDs available for an account would come from a server // but we can just copy them from above... var id transports "usb" "nfc" "ble" type "public-key" return ( ) => assertion console "ASSERTION" ( ) => err console "ERROR" website and its . Mozilla Demo source code website and its . Google Demo source code and its and webauthn.org client source code server source code Specifications Browser compatibility CredentialsContainer.create See also , ( 2FA) is an additional layer of security you can add to your login page. WordPress Two-Factor Authentication WordPress Credits Source: https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API Published under licence Open CC Attribution ShareAlike 3.0

Flow

Chain

Fetch

Google

Mozilla

Web Crypto API: A Low-Level Interface for Internet Security

Getting Started with Web Audio API

Read My Stories

Too Long; Didn't Read

Web Auth Standard: Guide to Web Authentication API 

Web Auth Standard: Guide to Web Authentication API

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

A Quick Introduction to the Resize Observer API

161 Stories To Learn About Authentication

3 Reasons for B2C Enterprises to Implement Single Sign-on Authentication

4 Dangers of Sticking with Outdated MFA Methods

The Noonification: Tailwindcss? Ill Pass (8/27/2023)

80% Devices in 2023 Are Already Passkey-Ready: Apple, Microsoft, and Google Pushing It Even Higher

A Quick Introduction to the Resize Observer API

161 Stories To Learn About Authentication

3 Reasons for B2C Enterprises to Implement Single Sign-on Authentication

4 Dangers of Sticking with Outdated MFA Methods

The Noonification: Tailwindcss? Ill Pass (8/27/2023)

80% Devices in 2023 Are Already Passkey-Ready: Apple, Microsoft, and Google Pushing It Even Higher

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps