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.

Sign up for GitHub

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

Add a hints element for both create and get. #1884

Merged
merged 8 commits into from
Aug 25, 2023
Merged

Add a hints element for both create and get. #1884

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ef8630c
Add a `hints` element for both `create` and `get`.
agl May 1, 2023
44e5b9f
Apply suggestions from code review
agl May 3, 2023
c2a7fe4
Various updates
agl May 3, 2023
cd4bded
Update hints PR to reflect WG discussions.
Jun 12, 2023
c5064ef
Clarify that the platform authenticator must be local.
Jul 12, 2023
5e60df6
"client device" -> "local device"
Jul 12, 2023
eaa9227
Apply emlun's suggestion.
agl Aug 16, 2023
424e917
Merge branch 'main' into hints
Aug 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1903,6 +1903,8 @@ a numbered step. If outdented, it (today) is rendered as a bullet in the midst o
[=authenticators=] can be <a href="https://en.wikipedia.org/w/index.php?title=Hot_plug">hot-plugged</a> into (e.g., via USB)
or discovered (e.g., via NFC or Bluetooth) by the [=client=] by various mechanisms, or permanently built into the [=client=].

1. Consider the value of {{PublicKeyCredentialCreationOptions/hints}} and craft the user interface accordingly, as the user-agent sees fit.

1. Start |lifetimeTimer|.

<!-- Note: this next step is actually a top-level step, but bikeshed wanted it indented this much in order to render it as
Expand Down Expand Up @@ -2372,6 +2374,8 @@ When this method is invoked, the user agent MUST execute the following algorithm

1. Let |silentlyDiscoveredCredentials| be a new [=map=] whose [=map/entry|entries=] are of the form: [=DiscoverableCredentialMetadata=] → [=authenticator=].

1. Consider the value of {{PublicKeyCredentialRequestOptions/hints}} and craft the user interface accordingly, as the user-agent sees fit.

1. Start |lifetimeTimer|.

1. [=While=] |lifetimeTimer| has not expired, perform the following actions depending upon |lifetimeTimer|,
Expand Down Expand Up @@ -2845,6 +2849,7 @@ value and terminate the operation.
unsigned long timeout;
sequence<PublicKeyCredentialDescriptorJSON> excludeCredentials = [];
AuthenticatorSelectionCriteria authenticatorSelection;
sequence<DOMString> hints = [];
DOMString attestation = "none";
sequence<DOMString> attestationFormats = [];
AuthenticationExtensionsClientInputsJSON extensions;
Expand Down Expand Up @@ -2902,6 +2907,7 @@ value and terminate the operation.
DOMString rpId;
sequence<PublicKeyCredentialDescriptorJSON> allowCredentials = [];
DOMString userVerification = "preferred";
sequence<DOMString> hints = [];
DOMString attestation = "none";
sequence<DOMString> attestationFormats = [];
AuthenticationExtensionsClientInputsJSON extensions;
Expand Down Expand Up @@ -3072,6 +3078,7 @@ optionally evidence of [=user consent=] to a specific transaction.
unsigned long timeout;
sequence<PublicKeyCredentialDescriptor> excludeCredentials = [];
AuthenticatorSelectionCriteria authenticatorSelection;
sequence<DOMString> hints = [];
DOMString attestation = "none";
sequence<DOMString> attestationFormats = [];
AuthenticationExtensionsClientInputs extensions;
Expand Down Expand Up @@ -3141,6 +3148,9 @@ optionally evidence of [=user consent=] to a specific transaction.
that the [=authenticator=] MUST or SHOULD satisfy to participate in the {{CredentialsContainer/create()}} operation.
See [[#dictionary-authenticatorSelection]].

: <dfn>hints</dfn>
:: This OPTIONAL member contains zero or more elements from {{PublicKeyCredentialHints}} to guide the user agent in interacting with the user. Note that the elements have type `DOMString` despite being taken from that enumeration. See [[#sct-domstring-backwards-compatibility]].

: <dfn>attestation</dfn>
:: The [=[RP]=] MAY use this OPTIONAL member to specify a preference regarding [=attestation conveyance=].
Its value SHOULD be a member of {{AttestationConveyancePreference}}.
Expand Down Expand Up @@ -3461,6 +3471,7 @@ an assertion. Its {{PublicKeyCredentialRequestOptions/challenge}} member MUST be
USVString rpId;
sequence<PublicKeyCredentialDescriptor> allowCredentials = [];
DOMString userVerification = "preferred";
sequence<DOMString> hints = [];
DOMString attestation = "none";
sequence<DOMString> attestationFormats = [];
AuthenticationExtensionsClientInputs extensions;
Expand Down Expand Up @@ -3524,6 +3535,9 @@ an assertion. Its {{PublicKeyCredentialRequestOptions/challenge}} member MUST be

See {{UserVerificationRequirement}} for the description of {{AuthenticatorSelectionCriteria/userVerification}}'s values and semantics.

: <dfn>hints</dfn>
:: This OPTIONAL member contains zero or more elements from {{PublicKeyCredentialHints}} to guide the user agent in interacting with the user. Note that the elements have type `DOMString` despite being taken from that enumeration. See [[#sct-domstring-backwards-compatibility]].

: <dfn>attestation</dfn>
:: The [=[RP]=] MAY use this OPTIONAL member to specify a preference regarding [=attestation conveyance=].
Its value SHOULD be a member of {{AttestationConveyancePreference}}.
Expand Down Expand Up @@ -3980,6 +3994,41 @@ Note: The {{UserVerificationRequirement}} enumeration is deliberately not refere
</div>


### User-agent Hints Enumeration (enum <dfn enum>PublicKeyCredentialHints</dfn>) ### {#enum-hints}

<xmp class="idl">
enum PublicKeyCredentialHints {
"security-key",
"client-device",
"hybrid",
};
</xmp>

Note: The {{PublicKeyCredentialHints}} enumeration is deliberately not referenced, see [[#sct-domstring-backwards-compatibility]].

<div dfn-type="enum-value" dfn-for="PublicKeyCredentialHints">
[=[WRPS]=] may use this enumeration to communicate hints to the user-agent about how a request may be best completed. These hints are not requirements, and do not bind the user-agent, but may guide it in providing the best experience by using contextual information that the [=[RP]=] has about the request. Hints are provided in order of decreasing preference so, if two hints are contradictory, the first one controls. Hints may also overlap: if a more-specific hint is defined a [=[RP]=] may still wish to send less specific ones for user-agents that may not recognise the more specific one. In this case the most specific hint should be sent before the less-specific ones.

Hints MAY contradict information contained in credential {{PublicKeyCredentialDescriptor/transports}} and {{AuthenticatorSelectionCriteria/authenticatorAttachment}}. When this occurs, the hints take precedence. (Note that {{PublicKeyCredentialDescriptor/transports}} values are not provided when using [=discoverable credentials=], leaving hints as the only avenue for expressing some aspects of such a request.)
Copy link
Contributor

Choose a reason for hiding this comment

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

...Note that {{PublicKeyCredentialDescriptor/transports}} values are not provided when using [=discoverable credentials=]

Might this statement need a qualification that we're talking about usernameless authentication here, with an empty allowCredentials? Because passwordless authentication, that identifies the user beforehand (e.g. SSO account discovery precluding WebAuthn use) can definitely use discoverable credentials with transports by populating allowCredentials like normal.


: <dfn>security-key</dfn>
:: Indicates that the [=[RP]=] believes that users will satisfy this request with a physical security key. For example, an enterprise [=[RP]=] may set this hint if they have issued security keys to their employees and will only accept those [=authenticators=] for [=registration ceremony|registration=] and [=authentication ceremony|authentication=].

For compatibility with older user agents, when this hint is used in {{PublicKeyCredentialCreationOptions}}, the {{AuthenticatorSelectionCriteria/authenticatorAttachment}} SHOULD be set to {{AuthenticatorAttachment/cross-platform}}.

: <dfn>client-device</dfn>
:: Indicates that the [=[RP]=] believes that users will satisfy this request with a [=platform authenticator=] attached to the [=client device=].

For compatibility with older user agents, when this hint is used in {{PublicKeyCredentialCreationOptions}}, the {{AuthenticatorSelectionCriteria/authenticatorAttachment}} SHOULD be set to {{AuthenticatorAttachment/platform}}.

: <dfn>hybrid</dfn>
:: Indicates that the [=[RP]=] believes that users will satisfy this request with general-purpose [=authenticators=] such as smartphones. For example, a consumer [=[RP]=] may believe that only a small fraction of their customers possesses dedicated security keys. This option also implies that the local [=platform authenticator=] should not be promoted in the UI.

For compatibility with older user agents, when this hint is used in {{PublicKeyCredentialCreationOptions}}, the {{AuthenticatorSelectionCriteria/authenticatorAttachment}} SHOULD be set to {{AuthenticatorAttachment/cross-platform}}.

</div>


## Permissions Policy integration ## {#sctn-permissions-policy}

This specification defines two [=policy-controlled features=] identified by
Expand Down
Loading