Intent to Ship: WebAuthentication API: ResidentKeyRequirement and credProps extension

301 views
Skip to first unread message

Martin Kreichgauer

unread,
Nov 5, 2020, 6:57:13 PM11/5/20
to blin...@chromium.org

Contact emails

mart...@google.comnsat...@chromium.orga...@chromium.org

Explainer


https://github.com/w3c/webauthn/issues/991

Specification

https://w3c.github.io/webauthn/#dom-authenticatorselectioncriteria-residentkey

API spec

Yes

Design docs


https://github.com/w3c/webauthn/pull/1191

Summary

Adds support for the AuthenticatorSelectionCriteria.residentKey property to specify during Web Authentication API (WebAuthn) credential registration whether a client-side discoverable credential should be created. Also adds support for the WebAuthn "credProps" extension, which indicates to the Relying Party whether a created credential is client-side discoverable.



Blink component

Blink>WebAuthentication

TAG review

N/A (minor API change)

TAG review status

Not applicable

Risks



Interoperability and Compatibility

Support on Windows >= 1903 depends on Microsoft implementing it in Windows. Support on Android depends on Android's WebAuthn library supporting it. Android WebView does not support WebAuthn.



Gecko: No signal

WebKit: No signal

Web developers: No signals


Debuggability

This feature will be supported by Chrome's Virtual Authenticator API implementation.



Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

No

Support on Windows >= 1903 depends on Microsoft implementing it in Windows. Support on Android depends on Android's WebAuthn library supporting it. Android WebView does not support WebAuthn.



Is this feature fully tested by web-platform-tests?

Yes. (Pending CL:2508878)

Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=1117630

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5701094648840192

Links to previous Intent discussions

Intent to prototype: https://groups.google.com/a/chromium.org/g/blink-dev/c/hHV_nrVc-To/m/fjcfKB7zBwAJ


This intent message was generated by Chrome Platform Status.

Yoav Weiss

unread,
Nov 8, 2020, 3:07:50 AM11/8/20
to Martin Kreichgauer, blink-dev
On Fri, Nov 6, 2020 at 12:57 AM 'Martin Kreichgauer' via blink-dev <blin...@chromium.org> wrote:

That's not an explainer. I'm sure I can get all that information from reading through the dozens of comments on the issue and the PR, but it'd be extremely helpful to me and other reviewers (as well as the general public) if you could sum up what this change is supposed to be doing, what are its implications on the API shape and how are developers supposed to be using it.
If writing it up in an explainer is too much overhead for some reason and would be relatively short, an inline explanation would work as well.



Specification

https://w3c.github.io/webauthn/#dom-authenticatorselectioncriteria-residentkey

API spec

Yes

Design docs


https://github.com/w3c/webauthn/pull/1191

Summary

Adds support for the AuthenticatorSelectionCriteria.residentKey property to specify during Web Authentication API (WebAuthn) credential registration whether a client-side discoverable credential should be created. Also adds support for the WebAuthn "credProps" extension, which indicates to the Relying Party whether a created credential is client-side discoverable.



Blink component

Blink>WebAuthentication

TAG review

N/A (minor API change)

That's not typically a valid reason to skip TAG review.
Was the change reviewed by someone? (e.g. in a WG) 



TAG review status

Not applicable

Risks



Interoperability and Compatibility

Support on Windows >= 1903 depends on Microsoft implementing it in Windows. Support on Android depends on Android's WebAuthn library supporting it. Android WebView does not support WebAuthn.



Gecko: No signal

WebKit: No signal

Could you ask for signals?  


Web developers: No signals

Do we have reason to believe users of the API actually need this change and will use it once shipped?
 


Debuggability

This feature will be supported by Chrome's Virtual Authenticator API implementation.



Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

No

Support on Windows >= 1903 depends on Microsoft implementing it in Windows. Support on Android depends on Android's WebAuthn library supporting it. Android WebView does not support WebAuthn.



Is this feature fully tested by web-platform-tests?

Yes. (Pending CL:2508878)

Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=1117630

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5701094648840192

Links to previous Intent discussions

Intent to prototype: https://groups.google.com/a/chromium.org/g/blink-dev/c/hHV_nrVc-To/m/fjcfKB7zBwAJ


This intent message was generated by Chrome Platform Status.

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAB%3DfcEa135x9a5h8oeNdqjD_%3D8uYC_EmL0Mnar4ncoUWO0pJKg%40mail.gmail.com.

Joe Medley

unread,
Nov 9, 2020, 2:45:31 PM11/9/20
to Martin Kreichgauer, blink-dev
Martin,

Are you wanting to ship this in 88 or 89?
Joe Medley | Technical Writer, Chrome DevRel | jme...@google.com | 816-678-7195
If an API's not documented it doesn't exist.


--

Martin Kreichgauer

unread,
Nov 9, 2020, 6:15:00 PM11/9/20
to Yoav Weiss, blink-dev
On Sun, Nov 8, 2020 at 12:07 AM Yoav Weiss <yo...@yoav.ws> wrote:


On Fri, Nov 6, 2020 at 12:57 AM 'Martin Kreichgauer' via blink-dev <blin...@chromium.org> wrote:

That's not an explainer. I'm sure I can get all that information from reading through the dozens of comments on the issue and the PR, but it'd be extremely helpful to me and other reviewers (as well as the general public) if you could sum up what this change is supposed to be doing, what are its implications on the API shape and how are developers supposed to be using it.
If writing it up in an explainer is too much overhead for some reason and would be relatively short, an inline explanation would work as well.

This is a small API tweak that originated from discussions in the WebAuthn WG. It is motivated by the fact that users on the web may have security keys with different capabilities (e.g. U2F vs FIDO2 keys), and so a given WebAuthn request can't always be fulfilled by the authenticator the user has at hand. In particular, a website can't know in advance whether a user's security key supports client-side discoverable credentials (which are necessary for password-less login), or only non-discoverable credentials (which are regular 2FA sign-in credentials). Websites that want to  support both types of credentials would have to present the user with two separate security key enrollment flows, of which one could potentially fail. With this API tweak however, a website is able to request either a password-less login credential or a second-factor credential; and the browser decides which type to create based on what type of security key the user presents. 

I also have a short explanation in the "Motivation" section of the ChromeStatus entry. I'll paste that here. Happy to expand more or spin it off into a standalone document somewhere if you think that would be helpful!

Motivation
"Client-side discoverable credentials" are a type of WebAuthn credential that can be challenged by a Relying Party (RP) without needing to provide the credential ID in the WebAuthn API request. Browsers display a list of all discoverable credentials from a given authenticator (external security key or built-in) and let the user choose one to sign in with.

Chrome already supports registration of client-side discoverable WebAuthn credentials via the boolean AuthenticatorSelection.requireResidentKey property. The WebAuthn Level 2 spec adds an alternative, enum-valued residentKey property. Two values of that enum, "discouraged" and "required", correspond exactly to the boolean values of requireResidentKey. The third, middle value ("preferred") lets the RP express that the browser should try to create a client-side discoverable credential, but that it may fall back to a non-discoverable credential if the authenticator presented by the user doesn't support it (e.g. a U2F/CTAP1 security key).

The credProps extension (https://w3c.github.io/webauthn/#credprops) can be used to report at registration time whether the newly created credential is client-side discoverable or not. This is useful for the RP in the "preferred" case.
 



Specification

https://w3c.github.io/webauthn/#dom-authenticatorselectioncriteria-residentkey

API spec

Yes

Design docs


https://github.com/w3c/webauthn /pull/1191

Summary

Adds support for the AuthenticatorSelectionCriteria.residentKey property to specify during Web Authentication API (WebAuthn) credential registration whether a client-side discoverable credential should be created. Also adds support for the WebAuthn "credProps" extension, which indicates to the Relying Party whether a created credential is client-side discoverable.



Blink component

Blink>WebAuthentication

TAG review

N/A (minor API change)

That's not typically a valid reason to skip TAG review.
Was the change reviewed by someone? (e.g. in a WG) 

Yes, it was reviewed in the WebAuthn WG. It got published in WebAuthn Level 2, which is currently in Working Draft stage: https://www.w3.org/TR/webauthn-2/
 



TAG review status

Not applicable

Risks



Interoperability and Compatibility

Support on Windows >= 1903 depends on Microsoft implementing it in Windows. Support on Android depends on Android's WebAuthn library supporting it. Android WebView does not support WebAuthn.



Gecko: No signal

WebKit: No signal

Could you ask for signals?  

I reached out to folks from those organizations and will update the thread if there are indeed signals.
 


Web developers: No signals

Do we have reason to believe users of the API actually need this change and will use it once shipped?

Yes. The FIDO Alliance recently published a best practices document for building authentication systems using security keys and the WebAuthn API. One of the use cases described there explicitly requires the residentKey=preferred option. Based on discussions

Martin Kreichgauer

unread,
Nov 9, 2020, 6:17:59 PM11/9/20
to Yoav Weiss, blink-dev
(Hit send to early here.) Based on discussions within the Working Group, I believe participants that also use WebAuthn for sign-in on their sites find this feature useful.

Martin Kreichgauer

unread,
Nov 9, 2020, 6:19:36 PM11/9/20
to Joe Medley, blink-dev
Hi Joe,

I marked it 88 for now, but depends on the timeline of this approval.

Cheers,
Martin

Akshay Kumar

unread,
Nov 10, 2020, 1:28:31 PM11/10/20
to blink-dev, Martin Kreichgauer, blink-dev, Joe Medley, aksh...@microsoft.com
We, at Microsoft, supports this change and are in process of implementing it for our next Windows release. 

Thanks
Akshay
Microsoft

Daniel Bratell

unread,
Nov 12, 2020, 2:11:40 PM11/12/20
to Akshay Kumar, blink-dev, Martin Kreichgauer, Joe Medley, aksh...@microsoft.com

Mike West

unread,
Nov 12, 2020, 2:44:42 PM11/12/20
to Daniel Bratell, Akshay Kumar, blink-dev, Martin Kreichgauer, Joe Medley, aksh...@microsoft.com
LGTM2.

This mechanism seems like a reasonable way of giving developers control over the kinds of credentials they accept, while not unnecessarily revealing information about the devices a user has available (as the implementation continues to be user-mediated).

-mike


Yoav Weiss

unread,
Nov 12, 2020, 3:52:01 PM11/12/20
to Mike West, Daniel Bratell, Akshay Kumar, blink-dev, Martin Kreichgauer, Joe Medley, aksh...@microsoft.com
Alex's reasoning on TAG reviews seems to apply here as well. Could y'all ask for a TAG review?

Martin Kreichgauer

unread,
Nov 12, 2020, 4:47:54 PM11/12/20
to Yoav Weiss, Mike West, Daniel Bratell, Akshay Kumar, blink-dev, Joe Medley, aksh...@microsoft.com
On Thu, Nov 12, 2020 at 12:51 PM Yoav Weiss <yo...@yoav.ws> wrote:
Alex's reasoning on TAG reviews seems to apply here as well. Could y'all ask for a TAG review?

In that case, I would prefer to hold off until that exception process is clarified. It is not clear to me that getting through a TAG review would be any quicker, and in any case we don't have any hard milestone requirement/deadline for this.


  

Alex Russell

unread,
Nov 19, 2020, 8:25:57 PM11/19/20
to blink-dev, Martin Kreichgauer, Mike West, Daniel Bratell, Akshay Kumar, blink-dev, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, Alice Boxhall
Thanks Martin.

IIRC the TAG may have discussed an FYI process this week (I need to sync up with Alice to find out how that went), but we've anticipated that any exception process would still require filing an FYI which the TAG could skim and pull into a full review if they deem it worthwhile so it seems valuable to perhaps file one now regardless. If the FYI process ends up the way we hope, we can "downgrade" the request shortly.

Regards

Martin Kreichgauer

unread,
Nov 19, 2020, 8:33:08 PM11/19/20
to Alex Russell, blink-dev, Mike West, Daniel Bratell, Akshay Kumar, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, Alice Boxhall
We circled back with the WebAuthn WG and we're now planning to submit WebAuthn Level 2 as a whole to TAG on behalf of the WG. Then we'll reference the "main" TAG review in the individual Intent-To-* emails as we launch Level 2 features. Level 2 as a whole is probably incremental enough that I would label it FYI if that were an option.

(More generally, I wonder if as a WG, we should have submitted L2 to TAG earlier. Probably something to keep in mind for the future.)

Cheers,
Martin

Martin Kreichgauer

unread,
Nov 25, 2020, 5:39:04 PM11/25/20
to Alex Russell, blink-dev, Mike West, Daniel Bratell, Akshay Kumar, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, Alice Boxhall

Alex Russell

unread,
Dec 17, 2020, 3:15:50 PM12/17/20
to blink-dev, Martin Kreichgauer, blink-dev, Mike West, Daniel Bratell, Akshay Kumar, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, A Boxhall, Alex Russell
The API OWNERs discussed again and would like to see the TAG thread updated with the resolution in issue #1302. 

Pending that LGTM1, and expect OWNERS will likely approve for 89 when we meet again in January. Does that match your expected timeline?

Regards

Alex Russell

unread,
Dec 17, 2020, 3:28:11 PM12/17/20
to blink-dev, Alex Russell, Martin Kreichgauer, blink-dev, Mike West, Daniel Bratell, Akshay Kumar, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, A Boxhall
Thanks to Martin for correcting me and noting that this is, indeed, LGTM3.

Martin Kreichgauer

unread,
Dec 17, 2020, 3:32:35 PM12/17/20
to Alex Russell, blink-dev, Mike West, Daniel Bratell, Akshay Kumar, Joe Medley, aksh...@microsoft.com, yo...@yoav.ws, A Boxhall
Thanks. Yes, approval for 89 would be great.
Reply all
Reply to author
Forward
0 new messages