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

Jump to bottom

WIP: More explicitly document use cases. #1300

Closed
wants to merge 1 commit into from
Closed

WIP: More explicitly document use cases. #1300

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
124 changes: 87 additions & 37 deletions index.bs
View file
Open in desktop
Expand Up @@ -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?


### Registration ### {#sctn-usecase-registration}
Issue: credProtect is not currently discussed.

- On a phone:
* User navigates to example.com in a browser and signs in to an existing account using whatever method they have been using
(possibly a legacy method such as a password), or creates a new account.
* The phone prompts, "Do you want to register this device with example.com?"
* User agrees.
* The phone prompts the user for a previously configured [=authorization gesture=] (PIN, biometric, etc.); the user
provides this.
* Website shows message, "Registration complete."
Issue: “tap-and-go” uses are not currently discussed.

Issue: “passwordless” (where a username is entered and the RP requests an assertion with UV for a list of registered credentials) is not discussed. This term is sometimes confused with “typing-free”.

### Authentication ### {#sctn-usecase-authentication}
Issue: if the WG decides to require user-gesture prior to operations, that should be included in the descriptions of the flows. See [#1293](https://github.com/w3c/webauthn/issues/1293).

- On a laptop or desktop:
* User pairs their phone with the laptop or desktop via Bluetooth.
* User navigates to example.com in a browser and initiates signing in.
* User gets a message from the browser, "Please complete this action on your phone."
### Second factor ### {#sctn-second-factor}

- Next, on their phone:
* User sees a discrete prompt or notification, "Sign in to example.com."
* User selects this prompt / notification.
* User is shown a list of their example.com identities, e.g., "Sign in as Alice / Sign in as Bob."
* User picks an identity, is prompted for an [=authorization gesture=] (PIN, biometric, etc.) and provides this.
In this pattern, an authenticator is used to augment an existing authentication flow by providing phishing resistance. Once logged in, users can register one or more authenticators with their account. At future logins, after entering a username and password, users are prompted to touch their authenticator to complete the login.

- Now, back on the laptop:
* Web page shows that the selected user is signed in, and navigates to the signed-in page.
At [=registration=] time, the distinctive options of {{PublicKeyCredentialCreationOptions}} are that:

1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{authenticatorAttachment}} is set to {{AuthenticatorAttachment/cross-platform}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{requireResidentKey}} is not set.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{residentKey}} is set to {{ResidentKeyRequirement/discouraged}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{userVerification}} is set to {{UserVerificationRequirement/discouraged}}.
1. {{PublicKeyCredentialCreationOptions/excludeCredentials}} is set to the list of credentials registered for the purpose of providing a first or second factor.

Issue: a Relying Party may wish to register credentials in such a way as to ease the transition to a multi-factor pattern in the future. This section should discuss that alternative.

Issue: opinions vary about whether {{AuthenticatorAttachment/cross-platform}} or no value is the correct attachment here.

At [=authentication=] time, the distinctive options of {{PublicKeyCredentialRequestOptions}} are that:

1. {{PublicKeyCredentialRequestOptions/allowCredentials}} is set to the list of registered credentials.
1. {{PublicKeyCredentialRequestOptions/userVerification}} is set to {{UserVerificationRequirement/discouraged}}.


### User re-authentication ### {#sctn-reauth}

Re-authentication describes the situation when a user is logged into a Relying Party, but the Relying Party wishes to confirm that the correct person is still in control of the browser. This may be because a significant amount of time has elapsed since the user last authenticated, or perhaps because the user is requesting to perform a sensitive action such as changing their password or transferring monies.

To ease this, a Relying Party may call isUserVerifyingPlatformAuthenticatorAvailable and, if that returns positively, prompt a user to register their current device. The device may implement user verification by performing a biometric check or perhaps, as a fallback, by prompting the user for a local password or PIN.

At [=registration=] time, the distinctive options of {{PublicKeyCredentialCreationOptions}} are that:

1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{authenticatorAttachment}} is set to {{AuthenticatorAttachment/platform}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{requireResidentKey}} is not set.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{residentKey}} is set to {{ResidentKeyRequirement/discouraged}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{userVerification}} is set to {{UserVerificationRequirement/required}}.
1. {{PublicKeyCredentialCreationOptions/excludeCredentials}} is set to the list of credentials registered for the purpose re-authentication.

### New Device Registration ### {#sctn-usecase-new-device-registration}
At [=authentication=] time, the distinctive options of {{PublicKeyCredentialRequestOptions}} are that:

This use case scenario illustrates how a [=[RP]=] can leverage a combination of a [=roaming authenticator=] (e.g., a USB security
key fob) and a [=platform authenticator=] (e.g., a built-in fingerprint sensor) such that the user has:
1. {{PublicKeyCredentialRequestOptions/allowCredentials}} is set to the list of credentials that were registered for the purposes of re-authentication.
1. {{PublicKeyCredentialRequestOptions/userVerification}} is set to {{UserVerificationRequirement/required}}.
1. Optionally, in some cases, the [=[RP]=] may have knowledge that the authenticator supports transaction authorization and thus can make use of the [txAuthSimple](#sctn-simple-txauth-extension) or [txAuthGeneric](#sctn-generic-txauth-extension) extensions.

Note: it is especially beneficial to ensure that {{AuthenticatorTransport}}s are correctly stored from the registration and provided at authentication time as it allows the browser to discard inapplicable credentials immediately. Otherwise the browser may, for example, prompt the user to insert USB devices.

The following user experience example shows how second-factor and re-authentication flows can be combined by leveraging a combination of a [=roaming authenticator=] (e.g., a USB security key fob) and a [=platform authenticator=] (e.g., a built-in fingerprint sensor) such that the user has:

- a "primary" [=roaming authenticator=] that they use to authenticate on new-to-them [=client devices=] (e.g., laptops,
desktops) or on such [=client devices=] that lack a [=platform authenticator=], and
Expand Down Expand Up @@ -404,26 +423,57 @@ Note: This approach of registering multiple [=authenticators=] for an account is
* User signs out.

- Later, again on their laptop:
* User navigates to example.com in a browser and initiates signing in.
* Website shows message, "Please follow your computer's prompts to complete sign in."
* User navigates to example.com in a browser and initiates a sensitive action, such as changing a password.
* Website shows message, "Please follow your computer's prompts to confirm your identity."
* Laptop prompts the user for an [=authorization gesture=] (PIN, biometric, etc.); the user provides this.
* Website shows that the user is signed in, and navigates to the signed-in page.
* Website complates the sensitive action.


### Typing-free ### {#sctn-typing-free}

Issue: there are multiple names for this user experience and we don't have widespread agreement on one yet.

In this pattern, the authenticator provides the identity of the user and two authentication factors in a single operation. The user clicks a single button to trigger a login and is prompted to activate an authenticator. If the authenticator has a screen, it may prompt the user to select an identity to use. Otherwise, the browser may show the selection. The user enters a PIN or uses biometric authentication and is then logged in.

### Other Use Cases and Configurations ### {#sctn-other-configurations}
At [=registration=] time, the distinctive options of {{PublicKeyCredentialCreationOptions}} are that:

A variety of additional use cases and configurations are also possible, including (but not limited to):
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{authenticatorAttachment}} is set to {{AuthenticatorAttachment/cross-platform}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{requireResidentKey}} is set to true.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{residentKey}} is set to {{ResidentKeyRequirement/required}}.
1. {{PublicKeyCredentialCreationOptions/authenticatorSelection}}.{{userVerification}} is set to {{UserVerificationRequirement/required}}.
1. {{PublicKeyCredentialCreationOptions/excludeCredentials}} is set to the list of credentials registered for the purpose of providing typing-free flows.

- A user navigates to example.com on their laptop, is guided through a flow to create and register a credential on their phone.
At [=authentication=] time, the distinctive options of {{PublicKeyCredentialRequestOptions}} are that:

- A user obtains a discrete, [=roaming authenticator=], such as a "fob" with USB or USB+NFC/BLE connectivity options, loads
example.com in their browser on a laptop or phone, and is guided though a flow to create and register a credential on the
fob.
1. {{PublicKeyCredentialRequestOptions/allowCredentials}} is empty.
1. {{PublicKeyCredentialRequestOptions/userVerification}} is set to {{UserVerificationRequirement/required}}.

- A [=[RP]=] prompts the user for their [=authorization gesture=] in order to authorize a single transaction, such as a payment
or other financial transaction.
Issue: opinions vary about whether {{AuthenticatorAttachment/cross-platform}} or no value is the correct attachment here.

Here is a user experience example of how a typing-less flow could work in practice with a specific (and arbitrary) type of authenticator:

- User registers on a phone:
* User navigates to example.com in a browser and signs in to an existing account using whatever method they have been using
(possibly a legacy method such as a password), or creates a new account.
* The phone prompts, "Do you want to register this device with example.com?"
* User agrees.
* The phone prompts the user for a previously configured [=authorization gesture=] (PIN, biometric, etc.); the user
provides this.
* Website shows message, "Registration complete."

- Later, on a laptop or desktop:
* User pairs their phone with the laptop or desktop via Bluetooth.
* User navigates to example.com in a browser and initiates signing in.
* User gets a message from the browser, "Please complete this action on your phone."

- Next, on their phone:
* User sees a discrete prompt or notification, "Sign in to example.com."
* User selects this prompt / notification.
* User is shown a list of their example.com identities, e.g., "Sign in as Alice / Sign in as Bob."
* User picks an identity, is prompted for an [=authorization gesture=] (PIN, biometric, etc.) and provides this.

- Now, back on the laptop:
* Web page shows that the selected user is signed in, and navigates to the signed-in page.


## Sample API Usage Scenarios ## {#sctn-sample-scenarios}
Expand Down