The Web Authentication API

December 22, 2019 · 📖 5 min read

What is WebAuthn?

WebAuthn is a specification in the W3C. The primary contributors are Mozilla, Microsoft, Google, FIDO Alliance and the W3C.

It defines a standard by which browsers can get assertions from authenticators, and how web servers can validate those assertions. It also defines a JavaScript API for web applications to request credentials from the browser.

The Web Authentication API, combined with the Client-to-Authenticator Protocol (CTAP), make up the FIDO2 protocol.

How does it work?

Using a device called an authenticator

a separate device, known as an external, cross-platform or roaming authenticator
built in to a phone or laptop, known as an internal, platform or bound authenticator

What gets sent from the server to your device

a “challenge” for the authenticator to sign using its private key
(optionally) more configuration options for the authentication process

What gets sent from your device to the server

for registering credentials:
- credential ID
- public key
- signed challenge (for server to verify using the public key)
- website information (origin and an identifier)
- authenticator type
- attestation statement (details about the authenticator)
for getting credentials
- credential ID
- signed challenge
- website information (origin and an identifier)
- details about authentication (e.g. whether “user verification” happened)

You may have noticed that we never send anything secret like a password or personally identifiable.

The authenticator can store credential information for each login you’d like to use

website identifier
user identifier
credential identifier

Can I use it?

In a word, yes. Read on if you want more detail 😆

Can I Use allows you to import data from your country, and also has a “usage relative” option, which can help narrow down to your targeted users, or you can import actual data for your users from Google Analytics.

At time of writing, it is supported in Chrome, Firefox, Edge and Safari (macOS), and not supported on Safari (or any other browser) on iOS. UPDATE: 22/12/2019: Safari iOS 13.2 has support behind a feature flag, and 13.3 is enabled by default

Whether someone can actually use WebAuthn depends on if they have an external authenticator or if their phone/computer can act as an authenticator.

I don’t have numbers, but I’m going to guess that a very small minority own authenticator devices like a Yubikey.

It’s more likely that someone will have a phone/computer that is capable:

✅ Android phone from Android 7 and above (~58% of Android phones)
✅ Windows 10 device capable of Windows Hello — ℹ some devices are capable of using Windows Hello with a PIN, so you may not need a computer with a fingerprint scanner or an infra-red camera.
✅ macOS device with Face ID or Touch ID
❌ unfortunately, it’s not supported on iOS yet. UPDATE 22/12/2019: Coming soon! experimental in iOS 13.2 and enabled in iOS 13.3

The lack of support on some devices doesn’t need to hold you back, though. You can detect support in the browser and provide different experiences for users on devices without those capabilities, without taking anything away.

How do I use the JavaScript API?

The JavaScript API only has a few methods.

// feature detection for WebAuthn
window.PublicKeyCredential

// detection for platform/on-device authenticator
await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable()

// registration of authenticator
await window.navigator.credentials.create(options)

// authenticate with authenticator
await window.navigator.credentials.get(options)

If you’re wondering about those options parameters, webauthn.guide by Duo does a much better job explaining them than I would.

In the next post, we’ll look at how the user experience changes, and how you might start enabling this for your users.

Written by Ben Lowry who lives and works in Perth building ~~useful~~ things. You should follow him on Twitter