Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: More explicitly document use cases. #1300

Closed
wants to merge 1 commit into from
Closed

Conversation

agl
Copy link
Contributor

@agl agl commented Sep 12, 2019

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

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: w3c#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 w3c#1292.
@agl
Copy link
Contributor Author

agl commented Sep 12, 2019

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.

@equalsJeffH equalsJeffH changed the title More explicitly document use cases. WIP: More explicitly document use cases. Sep 13, 2019
@equalsJeffH equalsJeffH added type:editorial stat:Discuss subtype:RP-impl-cons subtype:UX Things affecting the user experience in registration and authn ceremonies labels Sep 13, 2019
@equalsJeffH equalsJeffH self-requested a review September 14, 2019 18:47
@nadalin nadalin added this to the L2-WD-03 milestone Oct 1, 2019
@balfanz
Copy link
Contributor

balfanz commented Nov 19, 2019

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.

Copy link
Contributor

@equalsJeffH equalsJeffH left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@@ -338,42 +338,61 @@ refer to [[WebAuthnAPIGuide]] for an overall tutorial.

## Use Cases ## {#sctn-use-cases}

The below use case scenarios illustrate use of two very different types of [=authenticators=], as well as outline further
scenarios. Additional scenarios, including sample code, are given later in [[#sctn-sample-scenarios]].
Several user experiences can be crafted using this specification. This section enumerates the most common and specifies the values for the numerous options in {{PublicKeyCredentialCreationOptions}} and {{PublicKeyCredentialRequestOptions}} that will invoke them. By implementing one of these patterns, a Relying Party should find that users suffer less confusion as the structure of the interaction should be more familiar to them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@equalsJeffH equalsJeffH self-assigned this Jan 22, 2020
@agl agl closed this Jun 3, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
stat:Discuss subtype:RP-impl-cons subtype:UX Things affecting the user experience in registration and authn ceremonies type:editorial
Projects
None yet
Development

Successfully merging this pull request may close these issues.

More explicitly document use cases
4 participants