I'm pleased to announce the release of the v2.0 of my WebAuthn library!

This library greatly simplifies the usage of passkeys by invoking the WebAuthn protocol more conveniently. It is open source, opinionated, dependency-free and minimalistic (9kb only).

👀 Demos

• Basic Demo
• Autocomplete with conditional mediation
• Authenticators list
• Testing Playground

These demos are plain HTML/JS, not minimized. Just open the sources in your browser if you are curious.

📦 Installation

Modules (recommended)

npm install @passwordless-id/webauthn

The base package contains both client and server side modules. You can import the client submodule or the server depending on your needs.

import {client} from '@passwordless-id/webauthn'
import {server} from '@passwordless-id/webauthn'

Note: the brackets in the import are important!

Alternatives

For browsers, it can be imported using a CDN link in the page, or even inside the script itself.

<script type="module">
  import {client} from src="https://cdn.jsdelivr.net/npm/@passwordless-id/webauthn@2.0.0/dist/webauthn.min.js"
</script>

Lastly, a CommonJS variant is also available for old Node stacks, to be imported using require('@passwordless-id/webauthn'). It's usage is discouraged though, in favor of the default ES modules.

Note that at least NodeJS 19+ is necessary. (The reason is that previous Node versions had no WebCrypto being globally available, making it impossible to have a "universal build")

🚀 Getting started

There are multiple ways to use and invoke the WebAuthn protocol. What follows is just an example of the most straightforward use case.

Registration

import {client} from '@passwordless-id/webauthn'
await client.register({
  challenge: 'a random string generated by the server',
  user: 'John Doe'
})

By default, this registers a passkey on any authenticator (local or roaming) with preferred user verification. For further options, see → Registration docs

Authentication

import {client} from '@passwordless-id/webauthn'
await client.authenticate({
  challenge: 'a random string generated by the server'
})

By default, this triggers the native passkey selection dialog, for any authenticator (local or roaming) and with preferred user verification. For further options, see → Authentication docs

Verification

import {server} from '@passwordless-id/webauthn'
await server.verifyRegistration(registration, expected)
await server.verifyAuthentication(registration, expected)

Look at the docs for registration and authentication for the corresponding verification examples. Or simply interact with real-life examples in the Testing Playground.

⁉️ Why a "Version 2"?

Nobody likes breaking changes, so what's the reason for it? The "Version 2" is not only a complete overhaul of the first version, it also differs from the previous mainly regarding its default behavior and "intermediate payloads". The said, it remains similar, striving for simplicity and ease-of-use.

A bit of ❤️ for security keys

Previously, this lib defaulted to using the platform as authenticator if possible. The user experience was improved that way, going straight to user verification instead of intermediate popup(s) to select the authenticator. It was a smooth experience.

This behavior was born from a time where credentials were always device-bound. The terms "synced credentials" and "passkeys" did not even exist when the initial version of this lib was made. Nowadays, most platforms / authenticators now sync credentials in the cloud. While this is certainly convenient, the security and privacy guarantees are not as strong as with device-bound credentials. That is why security keys now deserve some love, since they are the only ones providing such strong guarantees.

The new behavior is to let the user choose the authenticator by default. It's also the native protocol's default. We want to give the choice to use security by default, since they are more secure.

In order to better support for security keys, some defaults also changed, like the user verification now being preferred and being discoverable also being preferred. Both should allow a broader set of security keys to be usable by default.

Reflects latest protocol changes

The protocol evolved with time, and still is. For example, autocomplete with "conditional mediation" was added. It's an addition I'm not fan of, but certainly has its merits. It basically let's you trigger authentication using the autocomplete feature of a username input field. This is especially useful because there is no way to know if a credential has already been registered for the user or not. However, be wary that this feature is not universally supported for all platforms / browsers / authenticators.

Another recent change is the usage of hints ("security-key", "client-device", "hybrid"), which should replace the authenticatorAttachment and transports properties in the long term. They were kind of wacky anyway. That said, only Chrome supports hints for now, but it's handled in a backwards-compatible way by this library.

Payloads compatible with other server-side libs

This is another crucial large change. The response format has been changed completely to be compatible with the output as the PublicKeyCredential.toJson() method. An official part of the spec that only FireFox implements.

That way, it is possible to use the browser-side of this library and use almost any other server-side library for your favorite platform. Using this intermediate format increases compatibility cross-libraries in the long term.

🙏 Last words

The original project https://passwordless.id is currently in limbo between proof-of-concept and production-ready. It would simply take more time than I can afford. However, I wanted to wrap up the changes in this library, since the scope is way smaller, and it seems more used by a wider range of people. It also follows the same goal: getting rid of annoying passwords while providing more security. Although I wanted to achieve this goal on a grander scale, this library should at least help others to use passkeys more easily.

...but it's kind of crazy that I do this. Actually, I'm currently on holiday and I should rather play with my kids outside rather than writing this article. Well, I'm still kind of an old nerd too. I just wanted to wrap it up. Consider this lib stable, use it to your heart's content and if you want to help the open-source ecosystem keep its balance, consider sponsoring this project too.

Have a nice week, Arnaud

The WebAuthn protocol is more than 200 pages long, it's complex and gets constantly tweaked. Moreover, the reality of browsers and authenticators have their own quirks and deviate from the official RFC. As such, all information on the web should be taken with a grain of salt.

Also, there is some confusion regarding where passkeys are stored because the protocol evolved quite a bit in the past few years. In the beginning, "public key credentials" were hardware-bound. Then, major vendors pushed their agenda with "passkeys" synced with the user account in the cloud. Then, even password managers joined in with synced accounts shared with the whole family for example.

How the protocol works, and its security implications, became fuzzier and more nuanced.

What is a passkey?

Depending on who you ask, the answer may vary. According to the W3C specifications, it's a discoverable public key credential.

If you ask me, that's a pretty dumb definition. Calling any public key credential a passkey would have been more straightforward.

What is an authenticator?

The authenticator is the hardware or software that issues public key credentials and signs the authentication payload.

Hardware authenticators are typically security keys or the device itself using a dedicated chip. Software authenticators are password managers, either built-in in the platform or as dedicated app.

Is the passkey hardware-bound or synced in the cloud?

It depends. It can be either and it's up to the authenticator to decide.

In the past, where security keys pioneered the field, hardware-bound keys were the norm. However, now that the big three (Apple, Google, Microsoft) built it in directly in their platform, software-bound keys, synced with the platform's user account in the cloud became the norm. These are sometimes also dubbed "multi-device" credentials.

Can I decide if the created credential should be hardware-bound or synced?

Sadly, that is something only the authenticator can decide. You cannot influence whether the passkey should be synced or not, nor can you filter the authenticators that can be used.

Concerns have been raised many times in the RFC, see issue #1714, issue #1739 and issue #1688 among others (and voice your opinion!).

Are passkeys a form of 2FA?

Not by default. Passkeys are a single step 2FA only if:

• The credential is hardware-bound, not synced. Then this first factor is "something you possess".

• The flag userVerification is required. Then this second factor is "something you are" (biometrics) or "something you know" (PIN code).

While requiring user verification would be ideal, this also restrict the hardware authenticators that can be used. Not all USB security keys have fingerprint sensor or PIN.

Are hardware-bound credentials more secure than synced ones?

Yes. When the credential is hardware-bound, the security guarantees are straightforward. You must possess the device. Extremely simple and effective.

When using synced "multi-device" passkeys, the "cloud" has the key, your devices have the key, and the key is in-transit over the wire. While vendors go to great length to secure every aspect, it is still exposed to more risk. All security guarantees are hereby delegated to the software authenticator, whether it's built-in in the platform or a password manager. At best, these passkeys are as safe as the main account itself. If the account is hacked, whether it's by a stolen password, temporary access to your device or a lax recovery procedure, all the passkeys would come along with the hacked account. While it offers convenience, the security guarantees are not as strong as with hardware bound authenticators.

The privacy concerns are similar. It is a matter of thrust with the vendor.

How to deal with recovery when using hardware-bound credentials?

A device can be lost, broken, or stolen. You must deal with it. The most straightforward way is to offer the user a way to register multiple passkeys, so that losing one device does not imply locking oneself out.

Another alternative is to provide a recovery procedure per SMS, TOTP or some other thrusted means. Relying on solely a password as recovery is discouraged, since the recovery per password then becomes the "weakest link" of the authentication system.

Discoverable vs non-discoverable?

There are two ways to trigger authentication. By providing a list of allowed credential ids for the user or not.

If no list is provided, the default, an OS native popup will appear to let the user pick a passkey. One of the discoverable credential registered for the website. However, if the credential is not discoverable, it will not be listed.

Another way is to first prompt the user for its username, then the list of allowed credential IDs for this user from the server. Then, calling the authentication with allowCredentials: [...]. This usually avoids a native popup and goes straight to user verification.

There is also another indirect consequence for "security keys" (USB sticks like a Yubikey). Discoverable credentials need the ability to be listed, and as such require some storage on the security key, also named a "slot", which are typically fairly limited. On the other hand, non-discoverable credential do not need such storage, so unlimited non-discoverable keys can be used. There is an interesting article about it here.

Can I know if a passkey is already registered?

No, the underlying WebAuthn protocol does not support it.

A request to add an exists() method to guide user experience has been brought up by me, but was ignored so far. See issue #1749 (and voice your opinion!).

As an alternative to the problem of not being able to detect the existence of passkeys, major vendors pushed for an alternative called "conditional UI" which in turn pushes discoverable synced credentials.

What is conditional UI and mediation?

This mechanism leverages the browser's input field autocomplete feature to provide public key credentials in the list. Instead of invoking the WebAuthn authentication on a button click directly, it will be called when loading the page with "conditional mediation". That way, the credential selection and user verification will be triggered when the user selects an entry in the input field autocomplete.

Note that the input field must have autocomplete="username webauthn" to work.

What is attestation?

The attestation is a proof of the authenticator model.

Note that several platforms and password managers do not provide this information. Moreover, some browsers allow replacing it with a generic attestation to increase privacy.

Do I need attestation?

Unless you have stringent security requirements where you want only specific hardware devices to be allowed, you won't need it. Furthermore, the UX is deteriorated because the user first creates the credential client-side, which is then rejected server-side.

There was a feature request sent to the RFC to allow/exlude authenticators in the registration call, but it never landed in the specs.

Usernameless authentication?

While it is in theory possible, it faces a very practical issue: how do you identify the credential ID to be used? Browsers do not allow having a unique identifier for the device, it would be a privacy issue. Also, things like local storage or cookies could be cleared at any moment. But if you have a way to identify the user, in a way or another, then you can also deduct the credential ID and trigger the authentication flow directly.

What about the security aspects?

The security aspects are vastly different depending on:

1. Synced or hardware-bound

2. User verification or not

3. Discoverable or not

A hardware-bound key is a "factor", since you have to possess the device. The other factor would be "user verification", since it is something that you know (device PIN or password) or are (biometrics like fingerprint).

Many implementations favor synced credentials with optional user verification though, for the sake of convinience, combined with discoverable credentials. This is even the default in the WebAuthn protocol and what many guides recommend.

In that case, the security guarantee becomes: "the user has access to the software authenticator account". It's a delegated guarantee. It is obvious that having the software authenticator compromised (platform account or password manager), would leak all passkeys since they are synced.

What about privacy aspects?

Well, if the passkeys are synced, it's like handing over the keys to your buddy, the software authenticator, in good faith. That's all. If the software authenticator has bad intents, gets hacked or the NSA/police knocks on their door, your keys may be given over.

Note that if a password manager has an "account recovery" or "sharing" feature, it also means it is able to decrypt your (hopefully encrypted) keys / passwords. On the opposite, password managers without recovery feature usually encrypt your data with your main password. This is the more secure/private option, since that way, even they cannot decrypt your data.

Passwordless.ID isn't progressing lately. While I would love to have Passwordless.ID already done and wrapped up, it's still far from it.

The reason: lack of time, lack of resources.

It's a personal project. It's not some big company or big bucks behind this. It's just an idealistic me, cursing at the utterly complex always forgotten passwords as a user and cursing at OAuth2 providers for the incurred complexity you have to deal with as a developer. Not to mention the account breaches due to insufficient precautions. With the recent WebAuthn/Passkeys protocol, started my journey to simplify all this. Make things simple, secure and "passwordless" for everyone. That was the goal (and still is).

However, as I mentioned before, it progresses at a snails pace. I sometimes work on it when commuting in the train, sometimes an hour in the evening or during the week-end. But this is not very productive. What should take hours take days, what should take days take weeks, what should take weeks take months. And it all overlaps with my personal time, which sometimes feels pleasant, sometimes feels like a burden, resulting in development even more spread over time.

And this feels quite annoying in itself. When developing in such a way, small piece after small piece, everything takes so long. You don't have this burst of productive work with satisfaction that a big chunk is done. It's like watching a snail sloooowly move without feeling any substantial progress.

It's ready to be overtaken by other "authentication solutions". Or rather, lagging behind the whole time. But who knows, there is a saying "slow and steady wins the race", and that's exactly what I'm doing now. I still work on it every week and small habits also get things done over a long time.

The solution attempt

There is only one way to put this on the fast track: time & money.

My current workplace did not support this project. It costs my precious working time and does not earn money. In other words, it's not a profitable endeavour for the company. I can't blame them. The other reason is a bit more subtle. The top brass prefers to use "big brands" for authentication rather than some yet unknown project. This is another ice difficult to break through. But I'll talk to them again, to see if there is a way I could spend some time on this.

Alternatively, I also recently applied to "Prototype.Fund" which is some funding initiative for open source projects in Germany. While there is no guarantee to be selected, I do hope it goes through as it would be a silver-lining to get started. At least, I could develop freely without digging in my employer's pockets. My major project at work should also be settled by the time the funding start, so the timing is right. We'll see, let's cross the fingers.

I even considered pushing all my cards into it, resigning and working full time on it. However, this is too risky for me. I got family and need financial stability, it's too big of a gamble. Not to mention that earning a stable income with a free public service is challenging.

Since I have little time to cater about Passwordless.ID lately, I wanted to at publish some little update. So here we go, the WebAuthn library (to enable passwordless login using passkeys) now also delivers more information about the "authenticator". In particular the icon and whether it is a multi-device or device-bound credential. (The latter one is actually just interpreting the existing flags)

👇 Check out the simple demo if you want.

👇 Or the list of authenticators.

👇 Or the playground to experiment with the various options.

⚠️ As a side note, please do not forget that the challenge should be randomly generated server side! I have found repositories on GitHub using hardcoded challenges, which is of course a red flag regarding security since it opens the way to replay attacks!

Read here or here if you want a brief introduction of how the WebAuthn protocol behind Passkeys works.

Starting from version 1.4.0+, the parsed registration payload now looks as follows, with extra properties synced, icon_light and icon_dark.

{
  "username": "Arnaud",
  "credential": {...},
  "client": {...},
  "authenticator": {
    "rpIdHash": "T7IIVvJKaufa_CeBCQrIR3rm4r0HJmAjbMYUxvt8LqA=",
    "flags": {...},
    "counter": 0,
    "synced": false,
    "aaguid": "08987058-cadc-4b81-b6e1-30de50dcbe96",
    "name": "Windows Hello",
    "icon_light": "https://webauthn.passwordless.id/authenticators/08987058-cadc-4b81-b6e1-30de50dcbe96-light.png",
    "icon_dark": "https://webauthn.passwordless.id/authenticators/08987058-cadc-4b81-b6e1-30de50dcbe96-dark.png"
  },
  "attestation": "o2NmbXRjdHBtZ2F0dFN0bXSmY2FsZzn__mNzaWdZAQB25KbRrQPjtlx0qZ2Tsvh2YHaPTPTUJznShhr5XnP3zBmVv..."
}

The icons are deliberately made as links to keep the library compact. Otherwise, it would be bloated way beyond the megabyte. Instead, all icons are available as links.

These authenticator icons were made thanks to this repository which contains the icons as data urls, sometimes in PNG, sometimes in SVG, sometimes square, sometimes rectangle, some tiny, some really large, etc. So some extra scripting was done to homogenize them as 64x64 PNGs and host them so that each "aaguid" can be shown through a direct link.

Thanks for reading. If you like it, leaving a comment or a star is appreciated. Getting some feedback is always nice.

Have a nice day!

In security, the main concern is protecting against breaches altogether. However, it is also a good idea to think about mitigating impact in case of breaches. Assuming we deal with some kind of sensitive user data, let's have some thoughts on what should be on the labels and the content of these wooden boxes.

What should be the user "identifier"?

Should it be the e-mail? Or a username? ...

TL;DR: No, it should be an anonymous ID.

How to identify users is something to be decided at the very beginning. It's crucial information that spreads everywhere: in the database, in links, in software logic... Soon, everything will be tied to it and too late to change. Doing so will be extremely difficult in the best case, or impossible in the worst case.

But why should it be an anonymous ID? ...It's not only about data breaches.

That ID is probably going to show up in extern systems too. In URLs, in logs, in databases, sent to third-party services... So, in the grand scheme of things, privacy-wise, it's better to be anonymized.

Security-wise, using a username/e-mail as the primary ID is not a vulnerability by itself. However, it slightly increases the "attack surface". For example, imagine you have a REST API with some endpoints accidentally not properly controlling access. If they accept a username/e-mail as parameter, it's trivial to invoke these endpoints with other user's username/e-mail as input, since these are fairly easy to find out. On the other hand, using anonymized IDs would already make exploiting such a vulnerability more difficult, since you don't know other's ID in the first place. This not only applies for REST API, but in all kinds of hacking, whether it's digging in a stolen file or eavesdropping traffic. It does not make your system invulnerable, but it's an additional layer of safety.

Imagine again the wooden boxes above, just don't place names on it for everyone to see but use some other identifier instead. For example, use the SHA256 of the username/e-mail with a salt. That's simple, deterministic and anonymous.

What about the stored data?

Most of the time, plain data is read and written directly to the database. The connection is typically protected by credentials to restrict access. This is all good and fine but the main access credentials become critical. If the access credentials are leaked or stolen, all the data can be extracted. Plain and simple.

Depending on the sensitivity of the data, like for example personal or financial data, another layer of protection is required: encrypting the data. Instead of placing the original text sheet in the wooden box, you encrypt it beforehand. Reading and writing encrypted data in the database makes it unreadable to others. Even database administrators would not be able to pry into the stored data, nor any other software not in possession of the encryption key. Likewise, this also increases privacy.

Note that although most databases also feature some encryption mechanisms, it typically refers to the raw data persisted on disk. To make the database storage files unreadable when stolen. These should not be mixed up and ideally, both should be used.

TL;DR: always encrypt all personal, financial or otherwise sensitive information when storing it in a database

Hash what you can!

Not only passwords but also recovery codes and other nonces.

As an anecdote, it reminds me of a story about a hacker who found an SQL injection vulnerability, enabling him to pry into the database. Of course, the user passwords were hashed. Even the sensitive data was encrypted. On the other hand, the recovery codes were stored "as is". The hacker now just had to start a recovery procedure for an arbitrary user account, and then look up the corresponding plain text recovery code. Bam! The hacker could now simply complete the recovery procedure and reset the password for any user account. That escalated quickly.

So if you don't really need the plain text data, don't even store it, just a hash of it.

TL;DR: hash not only passwords but also recovery codes, nonces, challenges and such.

Pairwise identifiers

User accounts are usually identified by some sort of ID. It might be a hash, a UUID, a username, an e-mail, whatever. When some third-party interacts with your service, it'll likely use this ID to identify the user or resource.

This also means that this ID is "universal" and that everyone out there will use this ID as an identifier. A user can be tracked that way, and attack attempts can be carried out that way using the known ID from another party.

A concept to push privacy and security further is called "pairwise identifiers". Each "consumer" of your service will be provided with different user identifiers.

Third-party service XYZ: can you please send me data related to user ABC123 ?

Provider: sure ...let me check ...for you XYZ, the account ABC123 is mapped to "Bob" ...here you go.

Of course, "Bob" is not the username, but should be the internal primary id.

It's about providing a mapping so that each third-party sees different IDs, so that they cannot correlate users among themselves. Also, it prevents leaked IDs from being used by others. As usual, these benefits both privacy and security.

TL;DR: it's best to provide third-party services anonymized IDs, unique third-party for each third-party. Both for privacy and security.

Good ol' cookies

This last advice is not directly related to the database but rather to how to maintain browser sessions. There are two camps: "use a good ol' session ID cookie" vs "use a JSON Web Token" (In an Authorization header or as cookie). The latter sounds more modern and trendy but it has drawbacks regarding security.

Let's review the good old way of handling sessions first. It's fairly straightforward: set a "Http-Only" cookie with some random session identifier when the user is authenticated. Voila, done. The browser will automatically send the cookie on each subsequent request and it cannot be read nor written by scripts. Server-side, you can retrieve the session data based on that id. Then, when the user signs out you can remove the cookie and clear your session data. Same if the user is inactive for too long. Simple, effective and there is not much that can go wrong.

Regarding the JWT tokens, there are two dangers with it. First, if the token which is typically stored browser side is stolen, the attacker can impersonate the user, even long after the user signed out... Except if you keep a database of revoked tokens, which not only loses the main benefit of JWT being "stateless" but also adds undesired complexity.

The second danger is the signing key being stolen, whether it's because of an accident, a vulnerability exploit or a malicious insider. Although this is unlikely because the key should be well protected, the potential consequences of a breach are catastrophic. Basically, your service would be doomed overnight because attackers would be able to impersonate any user at will, bypassing authentication altogether. This is a worst-case scenario that would not be possible for sessions identified by random IDs.

TL;DR: prefer random identifiers in a Http-Only cookie over using JWT tokens for user sessions

Doing it "later" is no good

It might be tempting to delay it, since it introduces complexity to the codebase. However, it's no good. The more you delay it, the more effort and time will be consumed in a later stage refactoring anyway. But even more importantly, while some changes can be delayed, others would break the API and data compatibility for all "consuming" software!

In particular, everything regarding hashed user IDs and pairwise identifiers will be breaking all software and integrations relying on these IDs. Changing these is a "hard cut" that should be done ASAP early on, ideally during the conception phase.

Other changes have a less critical impact. For example, hashing of short-lived recovery codes, nonces, challenges, etc. can be done in a version update. This will invalidate existing codes, nonces, and challenges and cause a small disturbance, but everything will work fine again afterwards.

The only change which is delayable with less concern is the data encryption. This is an internal database change, opaque to the API which remains unchanged and the consumers as well. It can be done in one fell swoop by encrypting all the data in the database at once using a background process.

TL;DR: don't delay it, do it ASAP since it's breaking changes

Side benefits

Following these recommendations will increase the security and privacy of your system, but that's not all. Doing this, although it sounds complex, has its benefits too regarding code structure. It forces the software to access user data through a streamlined access point instead of fetching it directly from the database. When all calls for user data go through this access point, it's also easier to monitor, control access and properly handle the data in this one place.

At least, that's what we experienced after our "endless refactoring" at Passwordless.ID. The refactoring is large, and the "version 2" breaks compatibility, requiring us to deploy a separate version and clear all user accounts. It is a very hard cut. However, we are pleased with the result. The system is now more secure, with better privacy, and better structured than ever before. Something I am proud of!

TL;DR: it will even make your codebase structure cleaner!

Thanks for reading! If you liked it, leave a comment!

This is a tale of such refactoring for Passwordless.ID, or rather how a large refactoring was aborded in the middle in favour of an intermediate solution.

Well, it turns out the refactoring was closer to a whole rewrite. But before delving into the details, let's check the "why" it was done, since the goals are what drive such refactoring.

Why?

The big refactoring started to take place, mainly driven by a follow-up of UI, API, DB: pushing "three-tier architecture" too far?.

Before, front-end and back-end were in two separate repositories, with their own lifecycle. However, from a workflow perspective, having both the API and UI in the same repository is more convenient. Changes always go hand-in-hand, you have a single URL for previews, no CORS necessary, a single pipeline and deployment, etc. The code is almost the same, it's just more convenient to work with a single repository.

The second goal was improving user experience, and specifically reducing "time-to-rendering" as much as possible. Currently, this was slowed down by:

• 130kb assets loading due to frontend framework (not that much, but way larger than it could be)

• "Waterfall loading" (load initial assets, run script, fetch dynamic content, load other stuff, render it all ...duh, feels sluggish)

• Cross-origin requests (adds one more "preflight" HTTP round-trip)

The combination of these things resulted in rendering times above a second when not cached, sometimes even two or three if the CDN caches also missed. In other words, it was slow despite being a super simple page.

Lastly, some structural changes to improve security and privacy would require changes on the data level. This includes changing the primary ID from the username to a hash and another round of encryption for the stored data. This would break the compatibility with existing data. Please note though that the privacy and security of the existing version is by no means compromised. This is about being paranoid and security/privacy in-depth by adding one more protection layer.

How?

There were three main areas related to the refactoring.

1. Combining both codebases with same domain previews

2. Making the UI more lightweight

3. Adapting the data layer

These are just a few sentences but represent lots of work. In particular, the UI refactoring. Making this more lightweight is easier said than done. Investigating alternatives and shifting away from the larger Vue framework turned out to be quite the burden.

The mistake made

We proceeded as follows

• Merge both codebases

• Refactor the backend code while we are at it 🙄

• Investigate frontend framework alternatives 😅

• Try out various frontend techs😬

• Start porting UI🥵

What started as a refactoring was turning more and more in the direction of a full rewrite.

The refactoring of the backend code was a bit time-consuming but worth it IMHO. It's slightly more lightweight and forcing a proper file structure is a good thing. It makes the code more organized and neater. You can directly pinpoint API endpoints to source code files and the related middleware without even looking at the code.

On the other hand, exploring the vast space of technologies available to replace the front-end was a bottomless pit. Even the first steps of refactoring the UI became a huge time sink. It's not only comparing the few major frameworks, it's even broader, related to the methodology: ranging from SPA (single-page-applications), to SSR (server-side rendering), to SSG (server-side generation), to bundling tools for plain HTML/TS/JS/CSS. Each of these methodologies has its own ecosystem and tools, with many frameworks to compare. Last but not least, many frameworks are often hybrids and can be "configured" differently to span a range of SPA/SRR/SSG.

In retrospect, it was a big mistake. It slowly but surely evolved into a complete rewrite. The UI refactoring is a huge endeavour that should have been left untouched and made separately. Not because it should not be done, but because it should not have been done now.

How it should have proceeded

The whole order in which we started the "big refactoring" was wrong. Of course, it wasn't originally expected to be that time-consuming either, it was just "let's refactor that". In hindsight, we should have paid much more attention to the priorities and plan the refactoring accordingly. It should have been done in smaller steps, one after another, and in an order that makes sense according to the priorities.

In particular, the UI-related one should have been done last. Of course, from a marketing and business point of view, one might disagree. The holy UI/UX would take priority, with the slogan "make it nice first, with a slicker UI which loads super fast". Something that "looks awesome" ...but that would hide and delay upcoming breaking changes, which would just frustrate early adopters later on. I'm against these kinds of short-term wins at the price of long-term liabilities. The sooner the breaking change is done, the better. That is also why any kind of promotion is on hold until this time-consuming refactoring is completed.

What should have been prioritized is merging both codebases into one for single domain deployment, data schema refactoring to use hashes as IDs and one more encryption layer. The reason to handle them first is because it's a breaking change. These two things make it incompatible with the original first version.

• Merge both codebases

• Ensure single domain dev previews work fine

• Apply schema changes for hashed IDs

• Add extra encryption round

Once this is done, the new version can be published. And afterwards, the UI and back-end related "improvements" can take place. Those which take more time but keep compatibility.

To abord or to persevere?

We're now stuck "in the middle" of the rewrite including the new UI, so it's kind of annoying to drop the work in progress halfway. On the other hand, it looks like the road ahead is still quite long. So, despite it's annoying to let the work in progress halfway done, it's better for Passwordless.ID as a whole. The sooner the "v2" is released, the better.

Also, what we did not investigate was how to make the existing UI lighter. We aren't talking about excessive amounts here, it's ~130kb gzipped JS/CSS over the wire. But for a simple sign in/up page, it's still unnecessarily large. After some experimenting, it turns out that ~100kb can be spared, just by dropping the bootstrap-vue-next lib in favour of using plain bootstrap classes directly and a few workarounds for special components. That the lib came in with that much "baggage" and could not be properly "tree-shaken" came unsuspected. Dropping it, the page goes from ~130kb => ~30kb, already much nicer.

The full UI rewrite will still take place later on, to be even more efficient and internationalized. But for now, we will make the bare minimum UI changes and focus on the breaking change first, which will hopefully be completed sooner.

Stay tuned!

What may look ideal in theory, may turn out cumbersome in practice.

-- Myself

During inception, the Passwordless.ID "app" was built in the purest form of a three-tier architecture.

• The UI - A vue app "compiled" into a single-page-application

• The API - An API built with Cloudflare Workers

• The DB - A distributed DB as a service

In particular, each "tier" was completely independent, built with its own tech stack and deployed on a dedicated subdomain.

• The UI: https://ui.passwordless.id

• The API: https://api.passwordless.id

• The DB: internal network

This complete separation of "tiers" may look ideal. It seems to be full of advantages.

• There is a clear separation of concerns

• Each tier can be updated independently

• One could make changes to the UI without affecting the API and vice-versa.

• They can scale independently

• The UI is fully browser cached

• Each "tier" (UI, API, DB) could theoretically be swapped out with another tech in the long term...

This might seem like an exemplary separation of concerns, something ideal to strive for. It's also what we strived for during inception. Sounds great right? Well, it turns out it's not that great ...it's actually pretty bad.

Decoupling back-end and front-end sucks

Being able to update and make changes to UI and API independently sounds great, but in practice, it turns out it's very rarely needed.

The vast majority of the time, when you work on something, whether it is a new feature, a change or a bug, you typically update mostly the UI and API hand in hand. You change files in both, test both together, and deploy both.

In the daily routine, having two repositories, toolchains and domains to deploy to turns out to be counter-productive. It'll lead to two commits, two builds, a "joint deploy", etc. It's not that big of a deal either, it's just annoying.

Cross-origin requests suck

Due to the UI and API being on two distinct subdomains, requests between the UI and the API are now "cross-origin requests". It applies to different subdomains too. Configuring the API to allow such "cross-origin requests" is no big deal when you know how it works, but some developers may find it cumbersome.

The subtle disadvantage is that it introduces one more round-trip: the Preflight requests. These requests are automatically sent by the browser to check if the requests from UI to API are allowed, before sending the actual requests. While not dramatic, it makes the UI slightly less responsive since it doubles the first request's latency.

Lastly, it also has an impact on session handling and security aspects due to its cross-origin nature. However, that's a whole other topic itself.

Latency sucks

You probably know it, when you develop locally, everything is snappy. The page loads instantly and you are happy ...and once it's deployed, you notice that the experience on your phone in "real life" is not that great, especially before all the browser caching kicks in.

The slowness comes from various things:

• the loading of assets from the SPA

• the UI pre-flight requests to the API

• the UI actual requests to the API

• the API calls to the distributed DB

• the "rendering" of the page content

Each of these things makes the UI sluggish and is a consequence of the distinct tiers being fully separated. To be more precise, it is because network calls are involved between all parts, each one increasing the latency and sluggishness by a notch.

Moreover, you typically don't notice this "sneaky" behaviour during the initial phase of development. When testing locally, everything appears lightning fast since everything occurs locally without network latency. Often, the sluggishness introduced by the network calls is only discovered when the first prototype is deployed and going "live".

That is why an application which combines everything locally, or in a same subnet, is usually much more responsive than having distinct "tiers" like UI / API / DB each separated by a network, which is common in a SaaS world.

Distinct subdomains suck

Whether you want to show your users a feature preview, provide a developer sandbox, make A/B testing or reproduce some bug in real-life conditions, "staging" environments are always useful.

If both the UI and API are packaged in the same app, deploying it at a single domain like https://prod.passwordless.id would be straightforward. Then, you could also work on a feature branch and deploy it to https://new-feature.passwordless.id to test it out in a live environment.

However, this becomes much more complex if you have it split. It would become something like this:

• https://ui.new-feature.passwordless.id

• https://api.new-feature.passwordless.id

It also requires some plumbing, so that the new feature UI talks with the corresponding API URLs, including adjusting CORS properly. This is extra work and is error-prone.

If the UI and API were bundled together in the same (sub)domain, that would not be a problem since relative URLs could simply be used and CORS are not involved either.

SPAs (sometimes) suck

SPAs like Vue, React or Angular are not bad. You have plenty of libraries with all kinds of widgets and fancy stuff. You can just "magically" quickly generate whole apps with some initializer. But it has a cost too: the learning curve, the complex toolchain, the clunky dependencies ...and the initial page load time due to larger size and rendering delays.

It's a tradeoff. While SPAs typically have a longer initial loading time, they offer complex widgets and increased interactivity in return. It offers ways to structure complex web applications in a modular way to keep their complexity under control. All these things are great ...if you need them. Otherwise, when you just need a few basic pages, it would likely turn into useless overhead.

In the end, whether SPAs "make sense" totally depends on the app. The more complex and user interaction-heavy the app is, the better suited it will be for SPAs. However, in the case for Passwordless.ID, which has a relatively simple UI, it was counter-productive.

Doing it as a Vue SPA was great to get started quickly, but in the meantime, it hinders me more than benefits me. The UI library used was bug-ridden, the various toolchains between UI, API and deployment platform do not always play well together, the resulting bundle is 400kb big and it'd cost time and effort to reduce it and the bad resulting latency is the nail in the coffin. Good ol' HTML ain't that bad after all.

Back to the basics

Lately, there is a renaissance of good ol' server-side templating. The basics are making a comeback under two umbrella names: SSR (Server-side rendering) and SSG (Server-side generation). SSG means templating at build time, like "generating" pages in various languages, while SSR means templating with dynamic data, like showing the result of a database query. Both have their roles and are complementary.

It's just going back to the forgotten roots of the web, noticing that after all, it's quite handy to produce HTML with the right data inside directly. It's simple, fast and "slim". This is a contrast to the SPAs which typically inflate, requiring larger JS assets, fetch the data in a second step and add rendering delays.

Sadly, the ecosystem is very fragmented in this area.

Porting software sucks

It would be foolish to leave the "architecture" decision purely to theoretical arguments. Moreover, it usually involves switching or at least adapting the technology stack. As such, its ecosystem plays a crucial role. If you go against the "intended usage" of your tech stack, you may fight an uphill battle not worth it.

In particular, at the time of Passwordless.ID's inception in mid-2022, Cloudflare pages functions simply did not exist yet. As such, the option to package both (with Cloudflare) was not even possible at that point. Pages functions appeared later, by the end of 2022. It certainly would have been able to use a more traditional technology stack at that time. However, the deployment and scalability comfort from a Cloudflare Pages/Workers combo was what pulled us over. It was a pragmatic choice rather than the ideal tech stack.

The point is that it would now be possible to combine the back-end and front-end in a single codebase. Is it worth porting the existing codebase? Tough question. I'd say "probably" but it's a substantial effort. The main issue is that in our case, the whole ecosystem around Cloudflare pages functions is very young. It lacks tooling, libraries, Q&A, documentation and so on. It is a "bleeding edge" right now.

Let's make it suck less

Do you know what also sucks? Authentication. It sucks for users (because they create oh so many accounts), it sucks for developers (because it's so complex) and it sucks for security (because passwords are vulnerable).

So at least, let's try to make authentication suck less and use Passwordless.ID. Think of it as a free universal account, a free public service, that makes your developer's life easy, is comfortable for the users and is more secure.

In the meantime, we'll start porting the "tiered" app to a "bundled" app, making it even better, swifter and more lightweight. Thanks for reading and stay tuned!

This minimal example shows an integration between FastAPI and Passwordless.ID.

Source code: https://github.com/passwordless-id/fast-api-demo

Running it

To run it: uvicorn main:app

And open http://localhost:8000/docs

For authentication, you can choose either the implicit flow or the authorization code. For both, the client_id should be your domain ("http://localhost:8000") in our case.

For the authorization code flow, ignore the client_secret and leave it empty. (That sounds fishy right? A section related to security concerns is at the end of this page)

Once you are authenticated and authorized access, you can return the user information server side.

The source code

The whole app is just this handful of lines.

from typing import Annotated

from fastapi import Depends, FastAPI
from fastapi.security import OpenIdConnect
import requests

app = FastAPI()

openid = OpenIdConnect(openIdConnectUrl="https://api.passwordless.id/.well-known/openid-configuration")

@app.get("/userinfo")
async def userinfo(authHeader: Annotated[str, Depends(openid)]):
    res = requests.get('https://api.passwordless.id/openid/userinfo', headers = {"Authorization":authHeader})
    return res.json()

The authHeader contains a short-lived access token that will expire after a short while. It should be used during the sign-in process to fetch the user information (like username or email) and establish a normal user session. This can be done either by setting a session ID cookie and keeping the user information in memory, using a database, using a self-signed JWT or whatever. How exactly this is done is left to your own preference. Lastly, maintaining your own user session avoids uselessly repeating the request and makes the experience more snappy for the user.

Security aspects

Let's understand what is going on in this "authorization code" flow.

1. The OpenAPI docs page redirects to an URL like https://api.passwordless.id/openid/authorize?...

2. Once the user authenticates and grants permission to see the profile, the user's browser is redirected back to the OpenAPI docs with a code

3. Server-side, python exchanges this code for an access token

4. With the token, you can send one more request to obtain the user profile

In the third step, where the code is exchanged for the access token, the server usually sends a client_secret too, to prove it's really him. This is to protect against attacks where your code was leaked, to prevent the attacker to get the access token.

For Passwordless.ID, this is mitigated by only allowing redirections back to the client_id requested. That already avoids the code being send somewhere else by an attacker tempering with redirect_uri.

Bottom line is that as long as your front-end is not compromised, the code should not get leaked. It is also a "nonce", which means that once exchanged for a token, it is "consumed" and cannot be used again. Lastly, the token too is rather short lived.

Security-wise, the authorization code flow without secret is still better than the implicit flow. While the first exposes an exchange code in the browser'S URL, the latter exposes the token and user profile directly, which would make stealing it much more convinient if your front-end is compromised.

For even better security, we recommend using the authorization code with PKCE. This is similar to dynamically created secrets. Using and verifying a nonce would also be an option since it is supported by Passwordless.ID. Sadly, neither is widely supported by FastAPI nor OpenAPI.

Demo source code: https://github.com/passwordless-id/spring-boot-demo

Dependencies

Spring Boot already has everything needed built-in for OpenID authentication. Thanks to that, adding a single dependency is enough.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Adding this dependency will also add spring-security which will "protect" the whole web application by requiring the user to be authenticated to access anything.

OpenID configuration

First, in resources/application.properties (or ".yaml"), Passwordless.ID has to be declared as identity provider.

spring.security.oauth2.client.provider.passwordless.issuer-uri = https://api.passwordless.id

Then, also how to configure the authentication requests.

spring.security.oauth2.client.registration.passwordless.client-id = http://localhost:8080
spring.security.oauth2.client.registration.passwordless.scope = openid avatar email

The client-id must be the domain where the web application runs. As a security measure from Passwordless.ID, redirects to URLs outside your client-id domain will be denied. On the other hand, all redirect URLs within this domain will be allowed, without the need to register them beforehand. Also, localhost constitutes an exception: it is always allowed and does not require https.

The scope represents what you want to read from the user's profile and must be granted by the user. The scope avatar is a convinience scope specific to Passwordless.ID which encompasses the claims nickname, picture and preferred_username. It is more privacy oriented than the usual profile which contains the real name of the user and additional personal information.

Getting the user

Spring will do all the heavy lifting, and inject the OpenID Connect user obtained from Passwordless.ID. It works out-of-the-box, without the need to add any code.

In our example, only a single controller is present the user information: MyController.java.

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.oidc.OidcUserInfo;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MyController {

    @GetMapping("/")
    public OidcUserInfo getUserInfo(@AuthenticationPrincipal OidcUser user) {
        return user.getUserInfo();
    }
}

Try it out

Run the program, then open http://localhost:8080 . It should directly redirect to Passwordless.ID in order to authenticate you. Once done, it will return to the original endpoint. It should display something like this:

Adjusting the security policies

By default, all endpoints are secured by Spring Security and require authentication beforehand.

Of course, it's possible to fine-tune which URLs require authentication, and which do not, as well as many other things. Explaining how Spring Security works and how it to configure every possible thing is beyond the scope of this minimalistic tutorial though. For a good starting point, I recommend checking out this tutorial about Spring Security and OpenID.

Beware, technical article ahead!

OAuth 2 and OpenID are complex protocols. It's full of tiny details that are there for the sake of security and it's not always clear why some checks are necessary. This article is about such a detail.

Prelude

Before stating what is missing, let us briefly look at how the OAuth2 "exchange" takes place.

1. First is the authorization request which redirects the user to the provider:

GET /authorize
    ?response_type=code
    &client_id=...
    &redirect_uri=https%3A%2F%2Fexample.org%2Fcallback
    &...

1. Once the user grants the scope, the callback is invoked with the authorization code. The server provided in the redirect_uri receives this code as follows.

https://example.org/callback
?code=Qcb0Orv1zh30vL1MPRsbm&...

1. Now, at example.org's server side, the authorization code (which is basically a nonce) is exchanged for the "real" access token. The URL to exchange the authorization code for a token looks like this:

POST /token
?grant_type=authorization_code
&code=Qcb0Orv1zh30vL1MPRsbm
&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback

Some parameters were omitted for brevity's sake, but it's sufficient for the upcoming explanation.

Why is the `redirect_uri` sent again?

Sending the redirect_uri in the first step is obvious, it's to know where the authorization code should be sent to via redirect.

However, when exchanging the authorization code for a token, why send it again?

Let's assume an attacker manages to manipulate the redirect_uri of a victim. Let's also assume this manipulated redirect is accepted by the provider for whatever reason. The attack pattern may look like this:

1. The attacker achieves to manipulate the URI in the first step as follows /authorize?...&redirect_uri=https://attacker.xyz/callback

2. The attacker receives the authorization code https://attacker.xyz/callback?code=...

3. The attacker can now invoke /token?code=...&redirect_uri=https://attacker.xyz/callback or /token?code=...&redirect_uri=https://example.org/callback as it please.

It makes no difference since the attacker is in full control of what is sent as redirect_uri ...right?

Anyway, it's probably further protected by a client secret or PKCE. Is there a way around it?!

Here comes the trick!

Let's assume Alice is the attacker and Vincent the victim.

Both Alice and Vincent have an account at example.org, which can for example use google photos to make collages of your family pictures.

Somehow Alice manages to manipulate the redirect_uri of Vincent, redirecting him to https://attacker.xyz/callback?code=ABC...

This attacker's website will probably also discreetly redirect back to example.org after grabbing the code. Vincent won't see example.org working properly, probably saying something went wrong, without suspecting anything bad.

On the other hand, Alice could go to example.org and use Vincent's code to complete the OAuth2 flow for herself, simply by pasting https://example.org/callback?code=ABC...

In other words, Alice will be able to impersonate Bob and make photo collages of Vincent's family.

This is of course just an example to illustrate the issue, but you certainly see the extent of this kind of exploit, which lets the attacker impersonate someone else.

Verifying the redirect_uri is there to prevent such "code stealing". It ensures such a triangle with an attacker in the middle did not take place by verifying that the code was indeed sent to the place the client app expected. Nothing more, nothing less.

How likely is it to have a valid attacker redirect_uri?

This cannot happen if a single redirect_uri is defined. It happens in scenarios where multiple callback URIs are defined (or if the server check is missing!) or where some loose matching takes place. Imagine for example a service which lets developers host their own apps behind a subdomain, providing authentication as a convenience. This could lead to a legitimate app goodapp.example.org being manipulated to leak the code to badapp.example.org, which might have a legitimate redirect_uri for example.org too. This could also be a larger organization, where some isolated app was hacked, and so on.

I would like to automatically log out the current user if there is no activity for x time. Haven't thought of the implementation, but is there an API for that?

Before answering that, let's start with the basics.

What is a session?

HTTP is at its core a stateless protocol. In order to "remember" things (like products in a shopping cart), associating the HTTP requests to a certain user (signed in or anonymous) is required. This is also called a session and is typically done in either of two ways:

• A Cookie storing some ID

  • Automatically sent by the browser on each request

  • For security reasons, it is highly recommended to enforce Secure (ensures HTTPS) and HttpOnly (inaccessible by javascript) cookies.

  • Session tracking can be performed before the user even signs in, or even be unrelated

• An Authorization header with some token

  • The token can be anything: a JWT from a thrid-party, an API key...

  • Tokens must be sent explicitly in the Authorization header for each HTTP request

  • Tokens add some logic client side to obtain them, refresh them and potentially cache them

On the server side, the cookie or token is read, making it possible to associate the HTTP request to the adequate "session".

Cookies are the classic way to handle sessions server side, they are simple, secure and practical. On the other hand, Json Web Tokens (JWT) are often used to obtain a signed token from a third party to act as proof of identity or for distributed APIs.

Whose session is it?

When using Passwordless.ID, there are actually two sessions involved.

• The session between example.xyz and the user

• The session between passwordless.id and the user

Please note also that a session for example.xyz is not strictly required. It could simply directly forward the id_token from passwordless.id directly to the server/APIs with Authorization: Bearer {{id_token}} and not use sessions at all. Or, it could send it once at the beginning to establish a cookie based session.

The session of Passwordless.ID is independent, a bit like how you are currently signed in with Google/Microsoft/Apple. If you are currently signed in with Passwordless.ID, every website you visit using Passwordless.ID will see you as signed in, and when you sign out or switch the account, it will reflect on all other websites too. That is also why you cannot forcibly sign out the user from Passwordless.ID. This would affect everyone.

Typically, when example.xyz requires authentication, it will perform a call to passwordless.id() using the @passwordless-id/connect packacge. If the passwordless.id session is still alive, a brand new id_token/token will be returned without user interaction, also called silent authentication. Otherwise, if the passwordless.id session expired or because the user deliberately signed out, the sign in dialog will appear before the id_token/token is returned.

Lastly, the user information of Passwordless.ID might be cached by other websites in their own sessions. This results in the signed in effect appear to be "sticky" even if the user has signed out from Passwordless.ID separately.

So what about inactivity expiration?

Activity on your website is for you to track. Whether you use a timer in the browser or check with your server if the session still exists is up to you. How you keep track of activity and expiration delays are all under your control.

But as stated before, even if the session at example.xyz expires, the session at passwordless.id might still be active, silently re-authenticating automatically.

But I want explicit re-authentication!

Currently, this is unavailable. However, future support for this is planned as explained below.

While silent re-authentication might be really comfortable in some cases, in other cases you may want explicit re-authentication. This is especially true in security sensitive contexts like banking or finance-related apps. After some inactivity delay, explicitly re-verify the user may be required.

Moreover, this explicit user verification might also be desired during a session, for example when accessing a restricted area or before triggering some sensitive operation. For example, it is common to verify the user before allowing a payment.

To do that, an additional parameter prompt will be offered in an upcoming version.

/openid/authorize?...&prompt=login

This upcoming parameter will explicitly re-trigger authentication and verify the user using biometrics or local authentication. This can be used as proof for sensitive operations or to re-sign-in users explicitly after an expired session.

This can be invoked through the @passwordless-id/connect lib as follows.

passwordless.id({
    prompt: 'login'
})

On the opposite, prompt: 'none' (the default) would perform silent authentication if possible.

By default, the retrieved token/id_token is cached in sessionStorage. When you want to keep track of the session on your own, it is also recommended not to cache the token, to avoid accidentally re-using the cached token.

passwordless.id({
    cache: false,
    prompt: 'login'
})

That is why it is IMHO time for an early push in adoption and community building rather than developing the next feature. After all, isn't it pointless to develop something if nobody uses it? Building a community around it is a challenge itself.

Sponsorship available

At last! Dunno why but GitHub sure took its time to approve the sponsorship. Now that it's there, check it out! Be the first sponsor! Yay! ...even if it's a single dollar and not enough to buy a coffee, it doesn't matter, it's the gesture that counts.

I also wonder if Github Sponsors is the right choice or if I should try to place an alternative funding platform like Patreon or OpenCollectives. What do you think?

Discord channel added

Come chat if you like! ...it's brand new and a ghost town right now. The community is non-existent at this point, so be a community pioneer and leave a message. ;)

Reserve your username now!

...pick a cool username before you're stuck with something like "dsiufgziuzgi45678" in the far future.

What's next?

I'm divided between reaching out for early sponsors or further developing it to make it better. It is still lacking a bit in some areas. I think I will do something in-between and reach out to two organizations I have in mind, then continue developing it before broadening the outreach.

Thanks for reading!

What is WebAuthn?

WebAuthn is a specification. It is an "RFC" issued by W3C, standing for "Web Authentication" to specify a set of interfaces for browsers to implement.

How does it work?

Fundamentally, the protocol's concept is rather straightforward.

During registration, the device (called "authenticator") generates a cryptographic key pair. The public key is sent to the server and the private key is safely stored locally.

During authentication, the server then asks the client to sign a message with a nonce (called "challenge") with its private key pair. This signed message with the nonce can then be verified by the server using the public key obtained through registration.

Moreover, the private key was never exposed. The signing of the message is done directly by the "authenticator", the device, and protected by some form of local user verification (like fingerprint, face, local PIN, swipe pattern, etc).

This had really strong security properties because the private key was hardware bound, and needed user's local verification to access it.

Why did I use the past tense? Because of ...Passkeys!

What are Passkeys?

Passkeys is basically the platform's implementations of the WebAuthn. Until now, the protocol had a shortcoming: if the user lost their device, they lost the private key and were locked out of their accounts. Bam!

The websites and users would have to either let them register multiple devices, with an associated key pair each, or rely on a (possibly less secure) account recovery mechanism.

To circumvent that, Apple, Google and Microsoft decided to go forward with "Passkeys". This is basically nothing else than WebAuthn but they sync your private keys into the cloud. Your private keys are not tied to the device anymore, they are "backed up" in the cloud, as they say.

It's like handing over a copy of your keys to Apple/Google/Microsoft saying "Here are my keys guys, keep it safe!". This is both a boon and a curse. On one hand, the users don't have to worry about losing their keys. On the other hand, it has of course strong implications on security, privacy and vendor lock-in.

Security-wise, the attack surface becomes bigger: on the device level (since it goes in an out of the secure hardware key store), on the network level by intercepting the syncing mechanism, on the vendor level in case of data breach and on the recovery level with someone trying to impersonate you.

Privacy-wise, they have your keys. Whether it's for their purpose, because of the NSA or whatever agency, they could access all your private accounts. That's a question of thrust here that they don't do.

Regarding vendor lock-in, if they have all your keys and you want to switch the platform ...well, you got a problem. You would probably have to re-register or launch recovery procedures on most accounts. It's quite a pain, and more sneaky since it only becomes obvious once it's too late. If keys were not synced, websites would put more effort into supporting multiple keys per account, thus being cross-platform by default. But with Passkeys they'll likely prefer to let the platform handle it.

Passkeys in practice

The main issue is also that you cannot opt in or out. The WebAuthn protocol lets the platform dictate. It was also raised in this issue that this is problematic: reduced security guarantees, regulations that cannot be applied, no way to block insecure device models, etc... However, the spec is driven by the big player's implementations rather than the other way around.

The other issue is that, in reality, it turns out to be more complex for websites to deal with ...at least, if you want to do it properly. Before Passkeys, you just had to let the users register multiple devices or have sound recovery mechanisms. Now, websites have to deal with devices that are maybe synced, or maybe not, or maybe not yet. Perhaps the user used a hardware key, which is not synced, or disabled it somehow if the platform permits it, or simply hasn't synced the key yet. In other words, there are more cases to take into account while still needing the same safety measures to avoid that a device loss leads to account "lock-out".

Lastly, these security, privacy and vendor lock-in effects are not recognized by average users. They just want to sign in. It is our duty as developers to deal with these issues responsibly.

WebAuthn in practice

In practice, it's a mess. The specification is overly complicated, long, unclear and there is a clear gap between the specs and implementations.

For example, let me cite the second sentence of the abstract.

Conceptually, one or more public key credentials, each scoped to a given WebAuthn Relying Party, are created by and bound to authenticators as requested by the web application.

Well, it's simply not true anymore since mid-2021 and noted in an issue but the specs remains unchained until now.

So, the specs differ from implementations and every platform and browser will deliver you another experience... which is IMHO still seriously lacking. Moreover, "Open" Browsers like Firefox are struggling and lagging behind with partial implementations due to the complexity of the specs, Linux as well...

So, although it's great on paper, the practical experience is a hit-or-miss thing. As it stands now, I strongly recommend to offer an alternative sign in experience if WebAuthn isn't properly supported or if "it doesn't work properly" on the user's device.

Moreover, it's not for the faint of heart. As a developer, you will have to deal with ArrayBuffers using a CBOR encoding and lots of low-level things. The whole process is not simple either, for example, registration is described as a 26 step procedure and authentication requires 23 steps to verify. Have fun! (sarcastic tone)

Conclusion

In my humble opinion, WebAuthn is an awesome concept with terrible execution. The promise is to get vastly improved security and convenience in the same package. However, what you get is a spec that a normal person cannot read, incredible complexity for developers, and browser implementations that are sometimes not working as expected or with poor UX. So here goes your vastly improved security with the touch of a finger ...down the drain. It's just a lot of painful work to get it right properly.

Moreover, it feels like the "big players" move to Passkeys was mostly a hype attempt ...and to pursue their own agenda of user retention rather than being truly helpful to the developer community. They wanted a new start, to remove the hurdle of multiple keys per account and encourage adoption that way. However, it does this at the cost of security, privacy and lock-in, so while useful it is a steep price. Moreover, "rebranding" the struggling WebAuthn specs as Passkeys rather adds to the confusion while not resolving the core problems, namely the complexity of the protocol itself.

So what's my take on it? If you have sufficient resources and time to pour into this, yes, you should support WebAuthn/Passkeys. It is better security-wise and depending how it's implemented, it might be more convenient too. However, if you do not, use an existing authentication provider. Using OpenID/OAuth2 is really much simpler than WebAuthn. You can also combine both by using Passwordless.ID for example, it's a public free identity provider offering passwordless authentication using WebAuthn. Try it if you want.

Thanks for reading and feel free to share your opinion!

Passwordless.ID is a free public identity provider allowing users to sign in/up in web apps using their fingerprint, face recognition or local authentication mechanisms like swipe pattern or PIN code. The results are no more passwords, a much smoother user experience and vastly improved security. It provides two-factor authentication using a single touch or a smile in the camera. Awesome, right? Try it now, it's a public service free forever, no account necessary!

Since a picture is worth a thousand words, here it comes... and actually, a bunch of them.

Authentication on various platforms

I used my own phone/laptop with a German locale, sorry guys. 😅

The cornerstone of this authentication service is to delegate user verification to the local platform. You may use your device's fingerprint sensor, some swipe pattern, windows hello with face recognition or even plain old passwords ...whatever is configured on your device locally.

By the way, if anybody could provide me a screenshot from a Mac or IPhone, that would be great!

Creating a new user

Creating a new user only requires a username. An e-mail address (although useful) is entirely optional. Why? Because there is no need for "I forgot my password"!

Upon clicking "Create Account" you will be prompted for local authentication. Once done your account is created. That's it. What follows is simply defining your profile ...if you want to.

Signing in

Once you pick your avatar, you must prove it's you by using local authentication. Don't worry, none of the information like fingerprint or pin codes is ever sent to the server. It is used locally to sign a message using asymmetric cryptography and prove you are you.

OAuth2 / OpenID flow

That is the whole purpose of this service. So that any website on the internet can easily ask "Who are you?". Since it is public, you can use it out of the box, even without account.

Managing devices

One of the more unusual aspects of this kind of authentication is that it is more secure by default. Only your registered devices can sign in. As such, it is important to easily add a new device.

Once you scan the QR code, you will be able to register your other device directly.

And after a while, you may end up with several authorized devices.

If you cannot scan the QR code or open the link in the e-mail, you can also enter the OTP code manually.

Recovery options

Now, if you have registered only a single device, without email or phone, you might be in trouble. In that case, losing your device would make it impossible to connect to your account anymore. That's why the interface emphasizes user guidance. It is a new topic for the users too.

After a classic e-mail confirmation, it looks already much better. Alternatively, you could also have just registered another device per QR Code. Both are ways to ensure safety.

E-Mail confirmation and recovery

IMHO the screenshots do not really convey the usage and the feeling of this "service" very well. However, it might give a slight idea of it. I recommend trying out the demo if you are curious or looking at the main site.

Although it's usable and has the fundamental things working right, it is still a bit rough around the edges. It still has to be fleshed out regarding certain aspects and needs some polish too. But it's working. It is in a kind of an early preview.

That is why feedback is always welcome!

A verification e-mail is automatically when the user sets or updates it in the profile.

Thanks to a verified e-mail, it can also be used to recover an account or register a new device.

...well, the e-mail template is far from perfect. The wording is a bit amiss and the "{{ method }}" is superfluous.

But as with most things, there is still much to do beyond fundamentals. Actually, the whole "recovery" mail is a bit misleading. It should rather just be called "Sign in link" instead and in the welcome screen let the user decide if the device should be registered or if it's a temporary session.

Among other things to do...

• Change "recovery" in "Sign in e-mail"

• A nicer "Sign in email sent" view

• An "email (un)verified" hint in the profile

• A "send confirmation email again" button

• Allow usage of e-mail instead of username too

• Check whether the e-mail was really properly sent

• Nicer error messages

Even for simple functionality, there is always many things to do. It might look like details, but that is what makes the difference between a great polished UI and an unconvincing one.

Thanks for reading,
See you next time,
Arnaud

Passwordless.ID is a free public identity provider allowing users to sign in/up in web apps using their fingerprint, face recognition or local authentication mechanisms like swipe pattern or PIN code. The results are no more passwords, a much smoother user experience and vastly improved security. It provides two-factor authentication using a single touch or a smile in the camera. Awesome, right? Try it now, it's a public service free forever, no account necessary!

Things have been calm lately as I had to shift my focus to other tasks in my life. Nevertheless, things are going forward, although at a slower pace than I would wish to be.

For those who are curious about where it's headed to and what's still to be done, I invite you to check the following roadmap!

Passwordless.ID Roadmap

The next steps are (at last) verifying the user's e-mail. In case you haven't experienced yourself, Passwordless.ID does not require an e-mail at all. It's optional. However, it's both important information to verify if it is provided, and a potential recovery mechanism in case of device loss.

Since only registered devices can be used to authenticate the user, the only "safe" way to use Passwordless.ID is to register at least a second device.

However, this is currently not so obvious. ...I would even say "dangerous" right now because an average user would not be aware that losing their device would make their account inaccessible. That's also why there is a TODO on the roadmap: to make such information more obvious in the UI and encourage the user to register a second device or verify e-mail/phone information during registration itself.

Stay tuned!

Passwordless authentication using your phone's fingerprint sensor, or face recognition using your webcam is now possible in the browser thanks to the WebAuthn protocol. It is not only more comfortable for users but also more secure since it is two-factor authentication in a single step.

In this demo, we will use the free Passwordless.ID API. This is a public identity provider, and it will take care of the heavy lifting for us. It's free and you don't even need to register an account or download anything to use it.

The following picture describes what we are about to do.

Our demo website will simply redirect to passwordless.id to authenticate "passwordlessly" (no e-mail required either) and authorize reading the profile, then return to the original demo page.

Thanks to it, we will obtain the user's avatar for that demo and display it, that's it! What is also obtained, besides the user's profile, is a signed Json Web Token. This token can later be sent to your APIs as proof of the user's identity. More on that later.

Live Demo

Please note that the authentication will be blocked within the IFrame for security reasons, click on the upper right to open the CodeSandbox in its own tab!

If somehow the CodeSandbox is not shown properly or does not work, you can also see the live demo here and the source code here.

The Passwordless.ID API follows the OAuth2 / OpenID standards, just like google or facebook logins. It is nevertheless simpler and easier to integrate with since it is a public API, not requiring any kind of special authorization.

Step by step tutorial

Although it is compatible with most other "Sign in with..." client libraries as a generic OpenID provider, the easiest way to integrate with it though is to use the @passwordless-id/connect library.

Let us go through the code, starting with the "Sign In" button.

<button id="sign-in" hidden class="btn btn-light" onclick="app.signIn()">Sign In</button>

Now, this is very basic, and depending on the frontend framework you use it will look different, but this is the gist of it.

The app.signIn() looks as follows.

import passwordless from 'https://unpkg.com/@passwordless-id/connect'

function signIn() {
    // redirects to the authentication/authorization page and back
    passwordless.auth({scope: 'openid avatar email'})
}

// a global `app` object just for the purpose of the demo
window.app = {
    signIn
}

Once the passwordless.auth() method is called, the user will be redirected to the Passwordless.ID UI which will prompt it to create an account or sign in and then to authorize your app to read the openid, avatar and email of your profile. In case the user is already signed in and has granted access, the redirect would come back directly to the app.

When redirecting back, it will append the id_token to the URL hash value (https://example.com/mypage#id_token=...) . The profile can then be extracted from the URL using the following piece of code.

const user = await passwordless.id({scope: 'openid avatar email'})
if(user.signedIn && user.scopeGranted) {
    // great, user.profile contains the information
    // and user.id_token can be sent to APIs
}
    // the user is not signed in or has refused
    // to grant authorization
}

This chuck of code is typically executed when loading the page. The id() function will first look at the current URL and try to parse the id_token in the hash if present. Otherwise, a request will directly be sent to the Passwordless.ID API to obtain it (if the user is signed in and has previously granted the scope of course).

The function always returns. If the user is signed in and has granted the scope, the resulting user would look as follows.

{
 "signedIn": true,
 "scopeGranted": true,
 "id_token": "eyJ0eXAiOiJK...",
 "profile": {
  "nickname": "Johny",
  "picture": "https://ui.passwordless.id/avatars/sam.svg",
  "preferred_username": "johndoe",
  "...": "...more attributes depending on requested scope"
 }
}

That's it! You have signed in a user and read its profile!

What you might also need is a way to sign out the user. Since Passwordless.ID is a centralized authentication system, being signed in or out affects all websites using it. As such, you cannot forcibly sign out users. You can ask them nicely "do you want to sign out?" using the following line.

// redirects the user to the sign out page
passwordless.logout()

This will redirect the user to a sign out page, and once done (or not), back to the current URL.

Everything is now there to sign in, sign out and retrieve the user. Congrats! For the sake of brevity, we will skip the part of displaying the profile and other UI interactions. That is up to you to freely customize according to your website's style.

What about the servers?

The example before shows browser side interaction, with the profile information being directly available. But how could you trust that information server side? That's what the id_token in the response is for! It is a "Json Web Token" (JWT), a signed proof of the user's identity.

The id_token is signed usings Passwordless.ID's secret private key and can be verified using its public key.

There are two ways to validate the token:

1. Locally, by using one of the many JWT libraries available.

2. By calling /openid/validate

That way, your servers and APIs can be sure of the user's identity. Each id_token will also possess a sub field according to the OpenID standard, which is a unique user identifier. You may also request the email as scope, but please be aware that an email is optional in Passwordless.ID, so you might not always obtain one even if you request it.

It's only an "Alpha Version"!

Passwordless.ID is not yet fully ready. It's at a proof-of-concept stage. Although it can already be used for testing and integration purposes, it is not yet quite ready for production.

If you think this is a meaningful public service and if you liked the tutorial, please like it and share it! The best way to make it succeed is to spread the word and encourage us. I hope you enjoyed it, I would be glad to hear your feedback!

Web authentication through local device authentication like Android Touch ID, Windows Hello Face recognition or just a local device PIN code. This is now available for Browsers and offers not only a smoother user experience but is also more secure.

It has many names: namely "Passwordless", "WebAuthn" and "PassKeys" but they all revolve around the same. It leverages a recent browser protocol called WebAuthn which acts as a glue to invoke the local device authentication mechanism. Before going into details, let's see what it looks like (with my laptop/phone using a German locale).

Looks great, right? Do you know anyone who likes passwords? Me neither. No more passwords == better UX. All those complex password rules, not reusing them, etc. is just annoying. And in the end, you forget the password anyway and must reset it.

Getting rid of passwords makes any registration/authentication much smoother and quicker. Moreover, it has several other benefits.

More secure

Better than passwords

It is two-factor authentication in a single step.

• The first factor is something you have. The authentication only works on registered devices.

• The second factor is something you are, or something you know. A biometric verification, or the device PIN code, is required.

A combination of both is required to authenticate the user.

It protects from phishing

Phishing usually involves the user typing their password into a fake website. It is the most common way to hack accounts.

By getting rid of passwords, you get rid of phishing! Great, right?

Moreover, it also protects against further security threats like password reuse, social engineering attempts and the like.

It protects against server breaches

The underlying protocol relies on asymmetric cryptography. The private key is stored on the device while only the public key is known by the server. Even if the clear text data on the server is stolen, it is not sufficient to authenticate the user. The user's device platform itself must be hacked to do so.

Privacy oriented

Your fingerprint/face never leaves your device

Biometric verification uses the local authentication mechanism from your device. On the device, this biometric information is strongly protected and never exposed.

Verification is a safety measure used to prove you are you, then create or access cryptographic keys stored on your device. These keys, also known as passkeys, are in turn used for the authentication mechanism.

You can choose not to use fingerprint/face

The user verification is delegated to your platform. If you are uncomfortable with such a mechanism, you can still use a PIN, a password, a swipe pattern configured, or whatever is configured on your device as the local authentication mechanism.

You are anonym

The protocol does not reveal anything about you. It just receives randomly generated key pair IDs and public keys. Moreover, each website has its own set of credentials and has no idea about the credentials used by other websites.

How does it work exactly?

Introduction

The authentication relies on a recent browser protocol called webauthn which is based on asymmetric cryptography.

During registration on a website, a pair of public and private keys is generated for the user. The private key is stored on the user’s device, while the public key is sent to the server.

When a user wants to authenticate themselves, they first request a challenge from the server. Then, they will reply with a message containing this challenge and signed using their private key.

The signature can lastly be verified by the server using the user’s public key obtained during registration. If the signature matches (and some other properties), the user is authenticated.

This simplified explanation of the protocol is illustrated by the following diagram.

Show me the code!

To provide meaningful examples while avoiding the overhead of the native protocol, the following sections will make use of the @passwordless-id/webauthn library, which is a high-level wrapper around the protocol.

It can be installed via npm install @passwordless-id/webauthn or imported directly in browser module scripts using import { client } from 'https://unpkg.com/@passwordless-id/webauthn'

Registration (browser part)

For registration, a cryptographic key pair must be generated for the user, it will be called a "credential" in the WebAuthn terminology. It can be created using the following call.

import { client } from '@passwordless-id/webauthn' 

const registration = await client.register("MyUsername", "some-random-generated-by-server")

For further options, check out the library's docs. Once the user confirms it using biometrics or PIN code, the key pair will be created, and the function will return. The private key is stored on the device, protected by local authentication, while the public key is returned.

{
  "username": "MyUsername",
  "credential": {
    "id": "3924HhJdJMy...",
    "publicKey": "...",
    "algorithm": "ES256"
  },
  "authenticatorData": "...",
  "clientData": "..."
}

This is a plain JSON object to be sent to the server. It contains various base64url encoded data that will first have to be parsed and verified.

Registration (server side)

Since the library also handles the server side, it can be used too there.

import { server } from '@passwordless-id/webauthn' 

const expected = {
    challenge: "whatever-was-randomly-generated-by-the-server",
    origin: "http://localhost:8080",
}
const registrationParsed = await server.verifyRegistration(registration, expected)

Either this operation fails and throws an Error, or the verification is successful and returns the parsed registration. Example result:

{
  "username": "Arnaud",
  "credential": {
    "id": "3924HhJdJMy...",
    "publicKey": "...",
    "algorithm": "ES256"
  },
  "authenticator": {
    ...
    "name": "Windows Hello Hardware Authenticator"
  },
  ...
}

The registration is now considered complete.

What must be stored server side is:

• The credential (id, publicKey, algorithm)

• Associate the credential.id to the user

When the user wants to authenticate later, you will need the public key and algorithm to verify the signature. It is imperative to store it. In contrast, the authenticator part is optional. It delivers information about the authenticating device and is not verified.

Authentication (browser side)

When a user wants to authenticate themselves, they must sign a random "challenge" using their private key. This signature is sent to the server, which verifies it using the user's public key.

import { client } from 'webauthn'

const authentication = await webauthn.authenticate(["allowed-credential-id", "other-allowed-credential-id"], "random-server-challenge")

Again, for all the available options, just consult the library's documentation. Once the user confirms the authentication attempt through biometric or PIN verification, the method returns the result.

{
  "credentialId": "3924HhJdJMy...",
  "authenticatorData": "...",
  "clientData": "...",
  "signature": "..."
}

Unlike the registration, there is no credential object, just the credentialId. This JSON can be sent as it is to the server.

Please note that the username is not present. It is not part of the WebAuthn authentication protocol. Therefore, a mapping credentialId -> username might be particularly useful to maintain server side. Alternatively, inject username in the JSON object before sending it.

Authentication (server side)

The most important parts now are to:

• Verify the challenge

• Verify the signature

• Validate a few more "details"

Given the credentialId, the server should possess the corresponding publicKey and algorithm used. These will be needed to verify the signature. The authentication verification procedure can be done with a single call.

import { server } from '@passwordless-id/webauthn' 

// obtained from database by looking up `authentication.credentialId`
const credentialKey = { 
    id: "3924HhJdJMy...",
    publicKey: "...",
    algorithm: "ES256"
}

const expected = {
    challenge: "whatever-was-generated-server-side",
    origin: "http://localhost:8080",
    userVerified: true,
    counter: 0 
}

Again, consult the documentation for all parameters. For example, a function predicate can be used for challenge and origin to make the verification more dynamic.

const authenticationParsed = await server.verifyAuthentication(authentication, credentialKey, expected)

Either this operation fails and throws an Error, or the verification is successful and returns the parsed authentication payload.

Please note that this parsed result authenticationParsed has no real use. It is solely returned for the sake of completeness. The verifyAuthentication already verifies the payload, including the signature.

Important final remarks

While it looks like an easy replacement for password based authentication. A bit more thought should be put into it.

Unlike traditional authentication systems that can be accessed from anywhere using a single password, authentication here is device bound. Losing a device means losing the private key used to sign in.

That the authentication is device bound affects many aspects of the user authentication:

• anonymous "usernameless" authentication becomes possible (where each device is its own account)

• by default, relying on a single registered device also implies losing access completely if the device is lost/broken/stolen

• registering multiple devices and being able to modify the list of allowed devices should be considered

• more diverse account recovery options become possible, like through another registered device

Taking care of all these aspects should not be underestimated. Especially if the goal is to replace traditional password based user authentication in an existing system.

Passwordless.ID

The vision

Passwordless authentication comes with its fair share of complexity and gotchas. "Passwordless.ID" aims to solve this by being a "free public identity provider".

Its philosophy is simple.

• Make the web a safer place

• Make it easier for developers

• More comfort and control for users

This is achieved by providing tools and services to delegate the authentication to the Passwordless.ID API.

OAuh2 / OpenID compatible

Passwordless.ID is compatible with both OAuth2 and OpenID protocols. That way, you can use it as a generic OpenID provider for a "Sign in with..." button.

If you are familiar with OAuth, you probably know that it is an "authorization" protocol. Usually, the API also offers a set of operations to grant permission to. In the case of Passwordless.ID, the only operation is accessing (part of) the user profile.

If you want to add Passwordless.ID as an additional social login provider using some predefined library, check out our OAuth2/OpenID guide!

Sign in with...

For a straightforward and smooth integration, you can use the @passwordless-id/connect library. This library makes it possible to trigger the authentication/authorization using a single call.

Check out the standalone demo to try it out and the user guide for implementing this on your site in 5 minutes! Not even an account is necessary!

Shared Profile

Why would you need to register your profile information, portrait, address over and over for every website or app? It is simply annoying for everyone. Using this shared profile, any website or app can request read access to it. That way, the user has a single place to maintain the profile up to date.

The same goes for the list of authorized devices. It simply makes more sense to maintain it in one place.

Free and public

Passwordless.ID is free for everyone and forever without a catch. It is our conviction that making it publicly available is the best way to make the internet a safer place as a whole.

To keep it striving in the long term, some funding is crucial. We would love to find some sponsors. If you are interested, please contact us or just drop a comment here.

Empowering the users

Using Passwordless.ID, the privacy and security settings will be in the hands of the users instead of the websites and apps. The users will choose whether they stay logged in or not, what account recovery mechanisms they deem safe enough, what information they agree to share without explicit consent, and so on.

In particular, the last point is interesting. For example, a user might agree to share its nickname and portrait publicly. That way, any website could show its avatar in the corner without explicit authorization request beforehand.

Currently in development

Passwordless.ID is not yet "finished". It is currently at the early proof of concept stage.

Although it lacks capabilities, it can already be used for testing and integration purposes. However, please note that the database might be reset at any point in the future until further notice.

We need you!

Any feedback is welcome

This was made with love, sweat and considerate thoughts. We strive to make the best possible authentication experience and are glad to hear any feedback. Even a little "like" on this article is encouraging.

Use it

This is meant to be a public identity provider. Help us make the web a better and safer place while making your developer's life easier. The best way is to use it. If you need help, just post an issue. And if you already integrated it, we would be glad to feature you in a future blog article!

Wanna write about it?

In case you plan to write a blog article, a tutorial, some news or anything alike, we would be glad to hear from you. Here are some logos and banners if you want. We might feature it on our blog too!

Share it

If you like it too, talk about it to others! Share it with someone! Every little act is of helps make it succeed. Thank you!

Some further links:

• Passwordless.ID website

• Sign in with Passwordless.ID demo

• Introduction to the WebAuthn protocol

• High-level WebAuthn library

• WebAuthn library playground

• Official WebAuthn specifications

Can registration/authentication be both smoother and more secure? Yes, it can! Without any password. This is sometimes called "webauthn", or "passkeys", or "passwordless authentication". It relies on the local platform authentication (using fingerprint recognition, a swipe pattern, PIN code or whatever) and asymmetric cryptographic signatures to authenticate the user. This is quite a lot packed in a small sentence, it will be explained in more details later. First, let us take a look and experience it for yourself!

If you do not see the following demo in the iframe, you can check out directly https://passwordless.id which has the demo on top.

And just to avoid some misconceptions upfront...

The fingerprint, swipe pattern, face, etc. is never sent to the server, it's used for local authentication. Moreover "passwordless" authentication is actually more secure than passwords since it is two-factor authentication by design

So how does it work exactly?

This is based on the low-level webauthn protocol, an official W3C standard implemented by all major platforms and browsers. For a more "digestible" version, I advise to look at the webauthn guide explainers.

The flow looks like this:

This flow diagram is of course very simplified, but it outlines the core principle.

During registration, a key pair is generated. This key pair, also called a passkey, is tied to the web domain (or a parent domain) and its access protected by the local platform authentication. The public key is sent to the server and later used to verify authentication attempts.

The private key is kept safe on the device. During authentication, the server sends a challenge, which is basically a nonce to avoid replay attacks, that the client must sign. This challenge can only be signed in the domain's context and requires the local platform authentication. The private key is never revealed at any point.

On the server side, the signature can be verified using the public key obtained during registration. Done. This also avoids a whole bunch of security vulnerabilities like password reuse, phishing, replay attacks, database breaches, etc. It's simply more secure by design.

The library

The native protocol is fairly complex and low level. However, here is a library to make your life easier!

• NPM: https://www.npmjs.com/package/@passwordless-id/webauthn
• GitHub: https://github.com/passwordless-id/webauthn

So either install it per npm:

npm install @passwordless-id/webauthn

Or import it directly in your web page! In case you don't know it, by declaring a <script type="module"> on your page you can import modules directly on a plain html page. As an example, the first thing to do is to import the package and check if webauthn is available.

<script type="module">
import { client } from 'https://unpkg.com/@passwordless-id/webauthn'

if(client.isAvailable())
  alert("Sorry, passwordless authentication is not yet available on your platform/browser!")
</script>

Please note though that this does not work in codepen, jsfiddle or other such environment because you will be constrained by the iframe policy. You need to serve it directly, localhost is fine though.

Likewise, it only works for chrome and edge. Safari has not yet been tested and firefox is not yet supported because they are a bit behind in their implementation, but that should change in the near future.

Registration

Overview

The registration process occurs in four steps:

1. The browser requests a challenge from the server
2. The browser triggers client.register(...) and sends the result to the server
3. The server parses and verifies the registration payload
4. The server stores the credential key of this device for the user account

Note that unlike traditionnal authentication, the credential key is attached to the device. Therefore, it might make sense for a single user account to have multiple credential keys.

1. Requesting challenge

As explained previously, the challenge is basically a nonce to avoid replay attacks.

const challenge = /* request it from server */

Remember it on the server side during a certain amount of time and "consume" it once used.

2. Trigger registration in browser

Example call:

import { client } from '@passwordless-id/webauthn'

const registration = await client.register("my-username", "randomly-generated-challenge-to-avoid-replay-attacks")

There are a few more options that you can set, but the default is just fine too.

Once the biometric or user input for local authentication is given, the function succeeds. The registration object that is obtained looks like this:

{
  "username": "Arnaud",
  "credential": {
    "id": "3924HhJdJMy_...",
    "publicKey": "MFkwEwYHK...",
    "algorithm": "ES256"
  },
  "authenticatorData": "SZYN5YgOjGh0NBcPZH....",
  "clientData": "eyJ0eXBlIjoid2ViYX..."
}

Then simply send this object as JSON to the server.

3. Verify it server side

The typescript library provides both sides, for the client and server. Simply import the corresponding module.

import { server } from '@passwordless-id/webauthn' 

const expected = {
    challenge: "random-challenge-to-avoid-replay-attacks",
    origin: "http://localhost:8080",
}
const registrationParsed = await server.verifyRegistration(registration, expected)

Either this operation fails and throws an Error, or the verification is successful and returns the parsed registration. Example result:

{
  "username": "Arnaud",
  "credential": {
    "id": "3924HhJdJMy_...",
    "publicKey": "MFkwEwYH...",
    "algorithm": "ES256"
  },
  "authenticator": {
    ...
    "name": "Windows Hello Hardware Authenticator"
  },
  ...
}

4. Store the credential key

The credential key is the most important part and should be stored in a database for later since it will be used to verify the authentication signature.

Please note that unlike traditional systems, a user might have multiple credential keys, one per device.

Authentication

Overview

There are actually two kinds of authentications possible:

1. By providing a list of allowed credential IDs
2. By letting the platform offer a default UI to select the user and its credential

Both have their advantages and disadvantages that go beyond the scope of this tutorial.

The authentication procedure is similar to the procedure and divided in four steps.

1. The browser requests a challenge from the server
2. The browser triggers client.authenticate(...) and sends the result to the server
3. The server loads the credential key used for authentication
4. The server parses and verifies the authentication payload

1. Requesting challenge

Again, the challenge is basically a nonce to avoid replay attacks.

const challenge = /* request it from server */

Remember it on the server side during a certain amount of time and "consume" it once used.

2. Trigger authentication in browser

import { client } from 'webauthn'

const authentication = await webauthn.authenticate(["the-credential-id"], "random-challenge-to-avoid-replay-attacks")

Like with the registration, we will omit any options since the defaults are just fine.

Once the biometric or user input for local authentication is given, the function succeeds and the obtained authentication object looks like this.

{
  "credentialId": "3924HhJdJMy_...",
  "authenticatorData": "SZYN5YgOjG...",
  "clientData": "eyJ0eXBlIjoid2ViYXV0aG...",
  "signature": "MEUCIAqtFVRrn7q9HvJC..."
}

The signature is the important part here. It proves that the user possesses the corresponding private key.

3. In the server, load the credential key

import { server } from '@passwordless-id/webauthn' 

const credentialKey = { // obtained from database by looking up `authentication.credentialId`
    id: "3924HhJdJMy_...",
    publicKey: "MFkwEwYHKoZIzj0CAQ....",
    algorithm: "ES256"
} as const

const expected = {
    challenge: "random-challenge-to-avoid-replay-attacks",
    origin: "http://localhost:8080",
    userVerified: true, // should be set if `userVerification` was set to `required` in the authentication options (default)
    counter: 0 // for enhanced security, you can store the number of times this authenticator was used and ensure it increases each time
}

Often, it might also be more practical to use functions to verify challenge or origin. This is possible too:

const expected = {
    challenge: async (challenge) => { /* async call to DB for example */ return true },
    origin: (origin) => listOfAllowedOrigins.includes(origin),
    userVerified: true, // no function allowed here
    counter: 0  // no function allowed here
}

4. Verify the authentication

const authenticationParsed = await server.verifyAuthentication(authentication, credentialKey, expected)

Either this operation fails and throws an Error, or the verification is successful and returns the parsed authentication payload.

Please note that this parsed result authenticationParsed has no real use. It is solely returned for the sake of completeness. The verifyAuthentication already verifies the payload, including the signature.

Done 🎉

Congratulations! Your user is now registered and authenticated using a more secure method!

You can also play around with the various options in the playground https://webauthn.passwordless.id/demos/playground.html, for example to use an external device. One of these options is for example to be able to select an extern authenticator, like an usb security key, or delegate authentication to your phone while using your laptop.

Final words

Unlike traditional authentication systems, you must keep in mind that the credential key is device bound. (Well, this is partly true. Google, Microsoft and Apple plan to sync these "passkeys" just like they do with the passwords if you enable a setting like "synchronize device settings" or something similar.)

However, this requires you to think a bit differently about authentication. What if the user loses its device? How can a user register multiple devices? Can the user block a lost device?

Lastly, there might still be situations where the user's platform/browser combination does not properly support the webauthn protocol yet and requires fallback authentication mechanisms like plain old passwords or code links sent per e-mail / sms.

Therefore, this webauthn library solves part of the complexity by abstracting away all the low-level technical stuff. However the authentication system should be seen as a whole and there is still quite some complexity attached to it. Moreover, users would be annoyed to manage multiple profiles anyway. After all, why do I as a user, have to register a new account each time for every website / webapp? That is why Passwordless.ID is born (and is currently in development). It should provide a "Sign in with Passwordless.ID" button, which provides smoother user experience for the user, is super easy to user for developers and more secure for everyone as icing on the cake.

Thanks for reading, I'd love to hear your feedback!