
A Guide to WebAuthn - simonpure
https://webauthn.guide/
======
combatentropy
This guide focuses on what WebAuthn looks like for the server. What does it
look like for the user?

As far as I can imagine, it boils down to relying on the possession of a
certain piece of hardware instead of knowing a certain password. That is, I
have to carry around some kind of USB device and plug it into every computer I
want to use. The device holds all my secret keys and does all the magic behind
the scenes. But if I lose my device, then I can't log in. And if someone
steals my device, then they can log in.

Maybe you can make it more convenient by using my phone instead of a
specialized USB device, since everybody is always carrying around their phone
everywhere they go anyway, right? But I just want to know that I understand
the entire landscape first, from the point of view of the user, at a broad
level. What are the user's options? What exactly does the user do? Is this
only for smart users? If I made a web app for the general public, and my only
method of authentication was WebAuthn, would the average user easily figure
out what to do, or would they give up and walk away?

Some have mentioned "software-based" tokens, but then how are those kept safe?
With a master password? Then we're back to passwords.

~~~
tialaramex
The most common use case today is 2FA, where WebAuthn is the standard way to
do something U2F defined only for 2FA.

In this scenario where it's only a second factor, yes, it relies on you
possessing a Security Key, and on the bad guys not possessing it. This matches
the threat model, which is typically that bad guys are not your flatmate or
your mother they live in another country and will never meet you.

WebAuthn (and U2F) were specifically designed to register multiple tokens, the
server-side stuff described explains how a site insists "Look I need to
register a _new_ token, not _these_ tokens which I already registered" while
also being open to whichever token you have on login, "Any of _these_ tokens
can log in, I don't mind which". So I have a token in my pocket, but if I got
mugged I have a backup token at home that can substitute. Well designed sites
let you nickname them during registration so you can go "I lost _green hulk_
token but I still have _Yubikey_ " later.

Yes, if you use the flows where both factors are handled by the FIDO token
then you're "back to passwords" but with a very important difference. Very,
very important:

Right now your password for news.ycombinator.com is known by the Y Combinator
servers. Now, I'm sure they take good care of it, using a modern salted and
pessimised hash for the purpose, but this creates many extra opportunities for
vulnerabilities and a bad guy only needs to find a crack in one place.

Whereas if I have a PIN for my FIDO token the PIN lives on the FIDO token. Not
on every web site I use WebAuthn with, not in a database that some poor new
sysadmin accidentally uploads to the Cloud, it's not sent over the wire to
some Java backend sevice that might accidentally log it, or whatever. The
device can _insist_ upon rate-limiting attempts because it's a piece of
hardware, like an iPhone.

~~~
ryukafalz
Unfortunately for the user experience, those tokens typically can’t be cloned
even upon initial setup. The practical result of this is that if you intend to
keep a second token as a backup, you need to remember to register the backup
token individually for each service you use your primary one for. This is
unlikely if you keep the backup at home, and it’s downright impractical if you
kept it in e.g. a safe deposit box.

I love FIDO tokens, but I’m not confident in my ability to keep myself from
getting locked out of a service I use infrequently, and I’m a fairly technical
user.

~~~
xur17
> Unfortunately for the user experience, those tokens typically can’t be
> cloned even upon initial setup. The practical result of this is that if you
> intend to keep a second token as a backup, you need to remember to register
> the backup token individually for each service you use your primary one for.
> This is unlikely if you keep the backup at home, and it’s downright
> impractical if you kept it in e.g. a safe deposit box.

This right here is what drives me crazy about most 2fa implementations (and
now apparently webauthn). I currently store 1 backup token offsite, and carry
one with me. The problem is - I have no good way to access the backup device
(so I can add it to my account) without having both in my possession, which
destroys its abilities as a backup token.

I would love to be able to somehow have 2 fido keys use the same key, but I'm
not sure how that's possible without exposing the private key externally,
destroying some of the device's security properties.

~~~
predakanga
You could have a single soft-U2F vault that contains all your accounts, and
secure that vault with your hardware tokens. Using something similar to LUKS
([http://clemens.endorphin.org/TKS1-draft.pdf](http://clemens.endorphin.org/TKS1-draft.pdf)),
you could allow multiple tokens to decrypt the vault without exposing the
master key. The downside is that there’s no way to revoke access to the vault
if a copy leaves your possession.

------
ecesena
I see a lot of comments of people interested to test it out.

If you have a hardware token with NFC, you can now test it everywhere: Mac,
Windows, Linux (), Android (all browser), iOS (Safari iOS 13.3+). This is a
big achievement as less than 1y ago the story was sooo much different.

If you do NOT have a hardware token, here are some options:

\- Windows with TPM or Hello

\- Mac with touchID sensor, you have to use Chrome

\- Android phone, Chrome mobile, should work with fingerprint and face
recognition

\- An Android phone itself can be used as a bluetooth hardware token, with
Chrome on your laptop.

Hope this list helps, please add if I forgot anything.

~~~
StavrosK
Chrome beta on mobile didn't work for me with either fingerprint or any other
method, the call to navigator.credentials.create just fails. Firefox half-
works.

~~~
JshWright
Firefox mobile works for me on [https://webauthn.io](https://webauthn.io)

Which half doesn't work?

~~~
StavrosK
For me, authentication, though I see it works on that site. Maybe I made a
mistake somewhere.

------
thayne
Why is the information that needs to be sent to the server so complicated?
Specifically you need to send the rawId (raw bytes), clientDataJson (json),
attestationObject (cbor) and the result of `getClientExtensionResults()` (js
object). And then the attestationObject further includes an `authData` field
which is itself a structure which contains another field which is CBOR
encoded.

Why not a single CBOR object?

~~~
adyavanapalli
Can you clarify whether you mean _only_ the `attestationObject` should be sent
to the server or that everything should be encoded as a _single_ CBOR object
and then sent to the server?

~~~
thayne
I mean why are ther multiple objects that have to be sent instead of a single
cbor object. And why is some of it cbor and some of it json?

~~~
arianvanp
Gets worse. Some of it is ASN.1 inside CBOR too. Some of it is custom binary
format containing CBOR

The answer is as far as I know:

Backwards compatibility with bad decisions made in U2F

Also; relying on base64url is odd as there are no built in functions in
JavaScript to encode and decode it.

~~~
tomashubelbauer
> Also; relying on base64url is odd as there are no built in functions in
> JavaScript to encode and decode it.

I'm probably missing something, but aren't window.atob and window.btoa just
that? It's not available in Node though.

~~~
thayne
btoa is base64 not base64url. And even if it was base64url, it takes a "binary
string", so using it on, say, a Uint8Array is non-trivial.

~~~
tomashubelbauer
Thank you, I didn't realize the URL safe variant of Base64 had a name and that
it was this!

------
trulyrandom
What's the story here regarding software tokens? As I understand it, the
WebAuthn standard doesn't preclude non-hardware tokens, but doesn't explicitly
define support for it either. In particular, I would like to use my phone and
its built-in Titan M chip for WebAuthn authentication over the internet,
instead of using a hardware token. Is that possible or on the horizon?

~~~
arianvanp
That will already work right now!

Go to [https://webauthn.io](https://webauthn.io) on your phone and it will ask
for your pin or fingerprint and then use the titan chip for the handshake! If
it doesn't work. Select "Platform authenticator" in the drop down

Will also work on iOS 13 beta.

If your computer has a TPM 2.0 chip then it will also work on Microsoft Edge
in Windows 10 (and maybe also other browsers. If they implement webauthb
Microsoft Hello API )

Website is implemented with the excellent [https://github.com/duo-
labs/webauthn](https://github.com/duo-labs/webauthn) library by the way

~~~
trulyrandom
Thanks for the info. This is not really 2FA anymore though, is it? Now
WebAuthn authentication is happening on the same device as the one I'm using
to log into the service. Is there a way to use my phone as a completely
separate factor for WebAuthn authentication?

~~~
arianvanp
Webauthn is not a 2fa API. It's an authentication API. One of its usecases is
to enhance password login (2fa) but can also be used as a single factor.

That is up to the implementor.

The implementor can ask the browser for certain security features of the
authentication device. E.g. is the authentication device the same device as
where the authentication flow is happening; is there a biometric check on the
device or a pin on the device (i.e. the second factor is there but device-
local) who is the manufacturer of the device (with consent of the user; given
this is privacy-sensirive info) etc. And the implementor can then make a
decision whether a device is 'strong' enough for single factor auth. All this
information is cryptographically attested by the device.

You can ignore all that and only use it as a second factor always though.
That's totally up to you and how you use the authentication primitives that
webauthn provides.

~~~
trulyrandom
Thanks again for the info. Sounds like I have some more reading up to do on
WebAuthn.

------
navaati
So, I went on the demo website ([https://webauthn.io/](https://webauthn.io/))
to try it with a recent desktop Firefox.

I enter a username, press "Register" and Firefox gives me a prompt to "login
[with a security key] and authorize", with only a "Cancel" button. And that's
all that happens.

Wait, so I can only use this stuff with a hardware token ? Bummer !

~~~
masklinn
Firefox lets you enable software tokens, and disable USB tokens: in
about:config, set

    
    
        security.webauth.webauthn_enable_softtoken=true
        security.webauth.webauthn_enable_usbtoken=false
    

then the registration will go through without needing a hardware token.

~~~
C14L
In other words, I can't use it in production (yet), because I'd need to ask
users to change browser settings for it to work. That's disappointing :(

~~~
thayne
You can use it in production for users who have hardware tokens (and it is
used in production by many sites for 2FA). But if you mean you can't
_exclusively_ use it in production, then yes that is probably true since not
all users will have authenticators (yet).

------
StavrosK
I am really excited about WebAuthn finally being the end of
usernames/passwords and credential leaks/thefts, so much so that I've
implemented a Django library for usernameless authentication with WebAuthn:

[https://pypi.org/project/django-webauthin/](https://pypi.org/project/django-
webauthin/)

It's live on some of my side projects, if you want to try it out:

[https://www.pastery.net](https://www.pastery.net)

[https://www.eternum.io](https://www.eternum.io)

[https://www.deadmansswitch.net](https://www.deadmansswitch.net)

~~~
latchkey
I love DMS! Thank you for implementing this on it. =)

~~~
StavrosK
Thanks, I'm glad you like it!

------
user738273
In the future, what will prevent some random border officer from pointing my
phone to my face and unlocking all my social media, google/Apple accounts,
mail, bank etc?

~~~
echeese
What's stopping them from doing that now?

~~~
user83628
My password, pin, whatever, is in my head

~~~
echeese
In that case you should probably not use this, or if you do, sign out of your
accounts. If you're worried about Face ID, you can actually temporarily
disable it easily (without even looking at your device) by holding down the
power button and volume up until it vibrates.

------
hamandcheese
> After the PublicKeyCredential has been obtained, it is sent to the server
> for validation. The WebAuthn specification describes a 19-point procedure to
> validate the registration data

19 points?! I haven’t dug too deep into the details, but so far everything
I’ve seen re: implementing WebAuthn seems so... over complicated? Compared to
implementing, say, TOTP based 2FA, which is very straightforward.

~~~
tialaramex
Complicated certainly. But over-complicated would imply that there's a
significantly simpler way to do it.

The nice thing about software is that it can be copied, so the complicated
part only needs to be done once by somebody suitably skilled in the art.

------
akubera
So this is like BrowserID/Persona but instead of including the third-party
email service to prove identification, the only credentials are on device/in-
browser, right?

I assume that if you only connect one computer (authenticator) and lose the
device, you're either SOL or the service has some workaround where you pre-
register an email address or a separate "Login With" service.

~~~
StavrosK
No, it's a new standard where the site securely negotiates the login with the
browser. What happens after that is the browser's job, all the site cares
about is that it sees a correct credential.

Eg your password manager could implement this so all you'd have to do is click
"log in" and you'd be in, without usernames or passwords to remember or steal.

~~~
combatentropy
So, how do you keep someone else from sitting down at your computer and
clicking Log In? Am I right in guessing that fundamentally you're back to
passwords, in the sense that when you are away you lock your computer screen
and have to enter a password to unlock it (or some other implementation that
still relies on passwords, like if your browser requires a master password to
use its password manager, etc.)

~~~
StavrosK
You use some method of authentication, of course. How do you keep someone who
has your unlocked password manager from using it? You just make sure nobody is
ever in that situation.

The big win is that, with WebAuthn, you don't need to also hide your
authentication from site operators, your OS, key loggers, phishers, etc etc.

~~~
combatentropy
Thanks. Like you said, this is safer, even if a password remains somewhere in
the chain, like a master password for your computer. An advantage is that
websites are not storing passwords (hashed or otherwise, because it's hard to
do well).

~~~
StavrosK
I use a Yubikey, so there's no password for me (just a PIN that wipes the key
if it's entered incorrectly a few times). You can also use a fingerprint
scanner, face ID, etc.

------
ak217
This is a great, highly accessible guide. The biggest value add is in the
description of the protocol, although the W3C standard
([https://www.w3.org/TR/webauthn/](https://www.w3.org/TR/webauthn/)) was also
expertly written and is a great, relatively accessible resource. Duo has done
good work in this space.

I've written an implementation of WebAuthn for Python-based webapps:
[https://github.com/pyauth/pywarp](https://github.com/pyauth/pywarp) that may
be useful to implementers.

------
gwillz
I really enjoy the server-client diagram [1].

I've always thought myself very able to explain technical things quite well to
non-technical people, but always struggled to explain the public/private key
exchange in a simple way. This is really neat.

1:
[https://webauthn.guide/#authentication](https://webauthn.guide/#authentication)

------
sebastien_b
I didn't read the whole thing, but the first few paragraphs make it sound
almost exactly like SQRL (ie. no secrets to keep).

~~~
fiatjaf
SQRL used to be a nice protocol, now it's a completely unusable monster with
more than 100 pages of technical documentation.

If you're interested in something similar that actually works and is very
simple, take a look at [https://github.com/btcontract/lnurl-
rfc/blob/master/spec.md#...](https://github.com/btcontract/lnurl-
rfc/blob/master/spec.md#2-lnurl-auth)

------
tarjei
What If I got multiple devices? Does the server have to store multiple keys
per user?

~~~
Rafert
Yes, that's what is recommended and most sites implement (AFAIK Twitter for
some reason only permitting one :-/)

~~~
zaroth
And how do you enroll the second device?

It would have to be something like;

1) Login on primary device

2) Generate a one-time code or link

3) Enter one-time code or click link on 2nd device

4) Click an “Enroll” button on the 2nd device which would generate a second
enrollment saved in the account.

You would have to do this for each and every service so that seems like a
total non-starter.

Alternatively, a way to share the private keys securely between the devices.
But I’m not sure if there are site-specific salts as part of the WebAuthN
signing process which would require additional state be sync’d between the
devices in order to authenticate to a new service on both devices?

~~~
nickray
There's an ascending signature counter that's intended to prevent cloned
devices (replay attacks are prevented seperately with server generated
challenge). One way around it is clone (backup key) having very high initial
signature counter set, so first use invalidates original (on loss). But yeah
it's a UX problem that hopefully will find a better/non-hacky solution than
"register multiple keys for each site".

~~~
xur17
> But yeah it's a UX problem that hopefully will find a better/non-hacky
> solution than "register multiple keys for each site".

This seems like a huge blocker for adoption. I currently run into this issue
with FIDO for 2fa - I store my backup key offsite, which means enrolling the
second device requires me to make a special trip to retrieve the device. My
current approach is to retrieve the backup token every few months and add it
to all of the new services I have enrolled in, but I don't have a good system
for remembering all of these services, so I inevitably forget one (despite
only using the key on a few services)...

~~~
tialaramex
Write the services down. You don't need to keep the fact that you have FIDO
tokens secret unless you're keeping them somewhere otherwise unsafe like under
a rock in your garden. So a list titled "Services I've enabled for FIDO" with
check columns for the tokens gets it done.

~~~
xur17
That's my current approach, but I'm not as disciplined about writing them down
as I should be.

------
TranquilMarmot
How are these private keys being stored? It seems to be implied that there is
a different public/private key pair for every website so are they stored in
the browser? (or at an OS-level?)

~~~
sam_lowry_
They are stored on hardware tokens. There does not seem to be a way to have
privately generated software keys, nothing like putty's pageant or
.ssh/authorized_keys.

WebAuthn seems to be designed by big businesses to take control of the
authentication ecosystem.

~~~
arianvanp
There are already open source hardware and software available by the people at
SoloKey. Both Nitrokey and SoloKey sell the tokens.

~~~
cr7pt0
If you are looking for a solution that supports FIDO2 and also functions as a
hardware password manager (lots of sites still don't even support security
keys) check out OnlyKey - [https://onlykey.io/](https://onlykey.io/)

OnlyKey is also open source here are some of the features: \- On device PIN \-
FIDO2 (15 Resident keys) \- TOTP (24 accounts) \- Static passwords (24
passwords up to 56 char long) \- OpenPGP

------
richbradshaw
If you have a Touch Bar MBP this works with Chrome and the Fingerprint Sensor
out of the box. On iOS 13 you need a hardware token currently. MacOS Safari
doesn't have support.

------
alexchamberlain
Is it fair to call this client side certificates 2.0?

------
toadi
This is about the same library:

[https://www.agwa.name/blog/post/always_review_your_dependenc...](https://www.agwa.name/blog/post/always_review_your_dependencies)

Claims there are it's written by people who don't understand Go that well.

------
beders
My spider-senses are tingling: Is this tracking I can't get rid of?

~~~
ficklepickle
I mean, if you are logged in, the service already knows who you are.

I guess your public key could get associated with your identity. But the pub
key is only sent when you register, I believe. So I can't see how this would
be used for tracking.

------
scanr
Anyone know if this will let sites use TouchID / FaceID on ios?

~~~
jrockway
When I last tried a couple weeks ago it looked like some basic support for
hardware tokens existed, but not for Face ID.

------
fiatjaf
Why is everybody acting as if this is some kind of solution to password-based
auth? Can you even imagine a world in which a big chunk of the population
carry these tokens around and never ever lose them?

------
pabs3
Can WebAuth work on websites that do not use JavaScript?

~~~
Freak_NL
No. The browser provides a client-side API that is exposed through JavaScript.

