Add clearer definition of API use cases to the spec

[AngeloKai]

see also issue #1389
potentially addressed by PR #1300
@christiaanbrand's #334 (comment) is a build on the original post below:

The current use case section of the API has two main sections: registration and authentication. However, in reality, the API can be used for a number of means and uncertainty has led to confusion among developers we talked to. A clear definition would help us in guiding our work and give developers clear idea of what the API can do. I think the list below seems like a good starting point:

• Two factor - first login (bootstrap)

  • Description:
    • The API can be used when a user logs in to a new machine for the first time. Typically a site requires the user to provide extra info to verify and then the user can use password. USB devices can be used to provide the extra info to verify the user’s identity.
  • Attributes of the authenticator devices used in this case:
    • The device must be portable*.
    • The device doesn’t need to be positively identifiable**.

• Two factor - always

  • Description:
    • The API can be used when a user logs in to a site that always requires password and second factor.
    • For example, after a user opts in to use U2F devices at Github.com, s/he is always required to type in password as well as plugs in a U2F device whenever s/he logs in.
  • Attributes of the authenticator devices used in this case:
    • The device must be positivity identifiable.
    • The device can be portable or built-in.

• Password-less Re-auth

  • Description:
    • User created a account along with a password saved on the server. However, the user doesn’t like having to type in password every time and opts to use an authenticator.
  • Attributes of the authenticator devices used in this case:
    • The device must be able to positively identify the user.
    • The device can be either portable or built-in, though built-in authenticator likely most useful here, such as fingerprint reader, facial recognition.

• Password-free accounts, first login (bootstrap)

  • Description:
    • Unlike the case above, the user never has a password saved on the server in this case. When a user signs up, s/he used an authenticator and never used password to log in before.
  • Attributes of the authenticator devices used in this case:
    • The deice must be able to positively identify.
    • The device must be portable

• Sign in without user name

  • Description:
    • User never created even a username in this case. The user is given a device at some point and is told to always use this device to log in.
    • For example, a IT or retail employee uses NFC to login to site to punches in and out, record sick days, etc.
    • The above example assumes the device is only used within a organization. However, this is not to say the case can only exist within enterprise scenarios. It is possible user ends up always use an authenticator to logs in. Then this leads to the problem of whether we want capabilities to the API in case a device’s memory is full.
  • Attributes of the authenticator devices used in this case:
    • The device must be portable
    • The device must be able to produce assertion without user name, only RPID

*: An example of a portable device would be a use key or a phone that the user can carry around and use to logs in to any place. An example of a built-in authenticator would be Windows Hello or Android fingerprint scanner. This is not to say they are always going to be entirely different devices.
**: There seems to be two category of devices: devices that can identify users through biometric means, such as fingerprint scanner, and devices that can’t, such as a number of Yubikeys that use the click of a physical button as confirmation of user intent without additional identification means. For now, I call devices of the former category as devices that are positively identifiable and the latter as devices that aren’t.

[nadalin]

There is the case where Web Authentication will be used as the second factor, case for AWS SIGV2 where the user has logged in with SIGV2 and this SIGV2 authentication token needs to be bound to the second factor FIDO authentication, this is much like how PKI may be bound to Web Authentication

[rlin1]

Terminology.

At this time positively identify user and device doesn't need to be positively identifyable are both used.
a) The device must be able to positively identify the user
b) The device doesn’t need to be positively identifiable

I think we should always use a) as the authenticator positively identifies the user (or positively identifying authenticator). It is not that the device is not positively identifiable in some cases (so b is misleading IMHO).

[equalsJeffH]

further terminology issues:

We already have a term, roaming authenticator, for "portable" authnr.

We already have a term, user verification, for what the above is terming (in @rlin1's parlance) "the authenticator positively identifies the user", i.e., we should say "the authenticator performs user verification".

[rlin1]

It seems to be: The RP can call getAssertion without CredentialID, but in makeCredential the RP cannot filter the authenticators to the ones suporting it.
So some form of authenticator selection policy.

[rlin1]

Seems to be 3 canonical characteristics:

1. Positively Identify the user
2. Roaming vs Bound authenticator
3. Being able to produce an assertion without receiving a credentialID from the RP

for 1 only a limited memory space is required (e.g. store a PIN). For 3 the authenticator needs such.

[christiaanbrand]

Let me also add some thoughts on user journeys as we're approaching the AMS plenary (where I'm hoping we can chat more about all of this):

Re-Authentication
a) Strict built-in, gesture-based (biometric) re-auth (post bootstrap)
This use case typically applies to financial services companies who want to give their mass market audience a way to re-authenticate on the same device using a fingerprint. It is critical that these users should not be confused with any messaging about external authenticators (during re-auth, especially since they might very well have required an external authenticator during bootstrapping) and, if there’s any doubt whether the fingerprint scan will work, users should fall back to whatever method for authentication is required during bootstrapping (mostly password).

During credential creation, the RP will explicitly ask for a UV=true, X-Plat=false authenticator, but note that the platform may, at its discretion, return an authenticator which is built-in, but also accessible from other devices.

For this use case to work properly, RPs should tag the specific session on this device with the credentialId, so that only the valid, local credentialId is passed in on subsequent get requests.

Bootstrapping
b) Using platform authenticator (passwordless bootstrap)
This user journey builds on (a): When an RP creates a credential, and gets a list of transports that indicate that the credential can be reached remotely (USB/NFC/BLE), the RP can remember this.
The next time a user tries to bootstrap their account from a new device, the RP can, after username entry:
Cross-Platform aka "X-Plat" in cbrand-lingo
Send all credentialIds it has on file for a specific user to the user-agent. This will either result in a local match (if the user cleared their cookies, or is trying to sign in from another app type, but a credential is available in a local authenticator), or, it will result in a dialog box asking the user to use one of their roaming authenticators to solve the challenge. The user can also dismiss the dialog in order to bootstrap normally.

Strictly non-Cross-Platform
Only send credentialIds that have “internal” in their transport type to the user-agent. If the credential has more than one transport, other transports should be cleared prior to sending it to the user-agent. This use case is specific to RPs who don’t want to deal with roaming authenticators and only wants the user to be able to sign in using credentials that was previously registered on this machine. This use case applies to a user clearing their cookies, or, signing in with a different browser, or, moving from the browser to an app or vice versa.

c) Using removable authenticator cross-platform (bootstrap)
This is the standard “U2F” use case where a user uses their security key as a second factor. Technically, (b) can also satisfy this use case if the credential was created using a phishing-resistant challenge.
To create a key that will only be used for this use case, X-Plat=true and UV=false should be set when creating the credential.

Note that when creating this credential as X-Plat=true, it might still be physically built in to a platform. It should just also be accessible remotely and will be indicated as such in the transports.

d) Typeless bootstrapping
This use case is the only one that requires resident credentials and is meant to allow a user to bootstrap an account onto a new device without the need for a username or password. The user would typically arrive at the login page of the RP, insert their security key, authenticate (locally) to the key (using a PIN or fingerprint), and then a list of all available credentials for that RP will be rendered by their browser. Once they select the credential they’d like to sign in with, the signature is released to the RP.

To create this type of credential, X-Plat=true and UV=true is sent during credential creation.

This flow today is restricted to wired authenticators: we’re not sure how to do this yet for wireless (without requiring system pairing).
Token Exfiltration Protection
This use case is very similar to (c), but instead of registering a removable security key, this is about registering a security key that’s built into the platform, and it doesn’t need to identify the user. This is what Googlers are using on a daily basis to prove that long lived credentials (cookies, OAUTH tokens, etc) is still being sent from a “trusted” machine. To create this type of credential, X-Plat=false and UV=false is sent.

Summary
Improving UX
It is my belief that by far the most prominent use for FIDO2 will be around use case (a): built-in, gesture based re-authentication. As this should also, relatively easily, enable (b): passwordless bootstrap, I think that RPs will start moving here fairly soon too. Depending on how (a) was bootstrapped, (b) might provide a security benefit, but this is mostly about improving UX.

Improving security
In order to improve security, we need users to bootstrap their devices with an unphishable challenge. To register one of these credentials, an RP could either re-use a key they created in (a) if that session was bootstrapped unphishably, but RPs could also, independent of the re-auth key, create a specific keypair that’ll be used during bootstrapping, in conjunction with a username and password, on a roaming authenticator by setting X-Plat=true and UV=false. If such a call is made on Android, we should give the user the choice to use a built-in authenticator (Citadel+physical button on Pixel3), or a discrete authenticator.
If this call is made on a desktop device I think we can only reliably offer the user a discrete authenticator right now as we don’t plan (as far as I know) to make Android act as a “paired” BLE authenticator.

[nadalin]

@christiaanbrand Please review, if no longer needed we will close

[equalsJeffH]

see also pr #956

[christiaanbrand]

Just to be clear: I don't quite care whether this goes into the main spec, or into an accompanying "implementation considerations" (editorial) doc. I actually think the latter might be better, as it could evolve more rapidly.

[equalsJeffH]

see also the closed PR #1300
this is a nice-to-have and puntable to a later spec version -- doing this properly is not "hard", but will take effort. I envison something like revamping along the lines of pr#1300, but also citing https://github.com/fido-alliance/how-to-fido/blob/master/HowToFIDO.md for "the full details"

[equalsJeffH]

this is superseded by issue #1389 and (closed) PR #1300.