WIP: More explicitly document use cases.

[agl]

The aims of this PR (which is currently incomplete) are, firstly, to provide more specific guidance for RPs about how to configure the several options in WebAuthns and, secondly, to provide a reserve mapping of options back to intents.

On the first motive: the feedback that we're getting from several RPs is that the WebAuthn spec is dauntingly complex. They go into it with a certain user experience in mind but the translation of that intent to concrete options is extremely challenging. While third-party documentation can also help address this, the spec should stand alone.

On the second motive: #1292 contains a request from a browser to add an extra option to translate the other options into a higher-level motive. The hope is that, in defining a mapping fro high-level intent to specific options, we also implicitly define the reverse mapping and so browsers can also extract the intent from the options.

It is unlikely that the reverse mapping will be total, rather some combinations of options will not map to any higher-level intent. Considering that set is hoped to be useful.

This PR is not yet complete and is being submitted in its current form ahead of TPAC to help inform the discussion around #1292.

Fixes #1389

---

Preview | Diff

[agl]

Here's a table that Steven (who'll be at TPAC) draw up that can be helpful to think about these things:

	User Presence	User Verification	Resident Key
RP knows which account is logged in	anti-exfiltration	reauthentication
User is unknown	two-factor auth	passwordless	typing-free

Also, I sketched up https://gist.github.com/agl/d4b7a646ec7474eec1071ebc9be77e79 to see about explicitly defining the map from registration options to high-level intent. (Take a look, you might think I'm crazy.) I've ignored all residentKey=preferred as something for the future. The combinations that remain undefined are:

(NoAttachment,RKNotSpecified,UVPreferred)
(NoAttachment,RKDiscouraged,UVPreferred)
(Platform,RKNotSpecified,UVDiscouraged)
(Platform,RKNotSpecified,UVPreferred)
(Platform,RKDiscouraged,UVDiscouraged)
(Platform,RKDiscouraged,UVPreferred)
(Platform,RKRequired,UVRequired)
(CrossPlatform,RKNotSpecified,UVPreferred)
(CrossPlatform,RKDiscouraged,UVPreferred)

If we take out those that are UV=preferred (which does not seem to make a lot of sense to me as an option) we are left with

(Platform,RKNotSpecified,UVDiscouraged)
(Platform,RKDiscouraged,UVDiscouraged)
(Platform,RKRequired,UVRequired)

The first two fall into Steven's “anti-exfiltration” bucket, i.e. you're checking for a credential that malware cannot have extracted from the machine and you're checking that there's a physical human at the machine. Perhaps this should be a documented use case.

The last is a typing-free situation, but with an odd platform attachment. Still, the intent can likely be categorised the same as other typing-free cases, leaving only uv=preferred and the flow around rk=preferred as undefined.

[balfanz]

Thanks for putting this together. It seems to me, though, that there are even more variations of parameters to consider, which map to more and/or other use cases. For example:

• What kind of attestation is requested (none vs indirect vs direct) may affect whether the RP can "inventory" their authenticators (i.e., imagine an RP that wants to ensure users use authenticators from a defined inventory).

• Whether or not the RP uses the hmacCreateSecret extension affects whether the credential/authenticator can be used to unlock devices.

• Whether or not the RP uses the credProtect extension, and which of its possible six values it selects, affects whether the authenticator can be used in certain tap-to-sign-in scenarios.

These are just off the top of my head - there might be more parameters or other extensions that also induce separate use cases that RPs may want to consider.

[equalsJeffH]

I have an overall comment before diving into contributing to this...

[equalsJeffH]

rather than jumping directly into API options settings and named flows with little real-world context, I am thinking that we might largely retain the present Use Cases section, though appropriately edit it (move the passwordless/Bluetooth example to end, add a distinct 2nd factor scenario(?)), and incorporate links to further sections that describe the options settings yielding said use case scenarios. WDYT?