Add a hints element for both create and get.

[agl]

As discussed at the face-to-face meeting of the working group on 2023-04-21, this change adds a hints element to both sets of options in order to allow sites to guide user agents in how best to complete the request.

---

Preview | Diff

[Kieun]

Why not leveraging authenticatorSelection with authenticatorAttachment?
Adding hints for the request by the RPs might offer better UX, but still the UX would be different per the browser and OS combination and the UX is not deterministic which still makes some users' confusion.

The authenticatorAttachement has such modality option for RPs to specify the authenticator.
With current enum, the security key cannot be expressed explicitly since the smart phone could be cross-platform authenticator as well. If this is the case, why not introducing additional enum value?

[agl]

Why not leveraging authenticatorSelection with authenticatorAttachment?

Adding a new attachment would break existing user-agents. We could work around that with a feature-detection system but then we would still have the issue that authenticatorSelection only exists for create(). For discoverable get() there wouldn't be any corresponding mechanism.

[Firstyear]

Why not leveraging authenticatorSelection with authenticatorAttachment?

Adding a new attachment would break existing user-agents. We could work around that with a feature-detection system but then we would still have the issue that authenticatorSelection only exists for create(). For discoverable get() there wouldn't be any corresponding mechanism.

That would be a bug in that user-agent then, because any rp could fill them with unknown values today and cause issues. So I think authenticator attachment still seems like a better place for this.

It's a bit of a concern that we are adding a third area for authentication selection, given that we already have transports and attachament selectors. So I think the bigger risk is for there to be inconsistent and odd behaviours if you specify multiple or combinations of these parameters.

[Kieun]

There is a open issue (#1267) related to the authenticator selection for get operation.
We still have been suffering those issue after introducing passkey and webauthn to our customers.
I agree with @Firstyear's comments.

[denniskniep]

I like the idea to have a property where a rp can put generic hints for the user interface. And not limit it in any way to selection of the authenticator.

I would vote for two additional hints:

• mechanism-selection: Indicates that the rp should show as "landing page" the list of all options
• cable-qrcode: Indicates that the rp should show as "landing page" the QR Code to initialize cable

Furthermore it would be nice as browser to have the ability to specify custom hints which are not defined (yet) in the spec. That would provide the opportunity to adopt quickly and later (if it makes sense) integrate them into the spec. As far as I know same mechanism is used in CSS specification. Then it is necessary to specify a pattern for browser specific prefixes (e.g. -<browsername>-<hintname>)

[timcappalli]

I would vote for two additional hints:

• mechanism-selection: Indicates that the rp should show as "landing page" the list of all options
• cable-qrcode: Indicates that the rp should show as "landing page" the QR Code to initialize cable

Both of these are already accommodated with a combination of the two options in this PR and authenticator attachment

[agl]

That would be a bug in that user-agent then, because any rp could fill them with unknown values today and cause issues. So I think authenticator attachment still seems like a better place for this.

A WebAuthn level one implementation can reject any unknown values for authenticatorAttachment. A level two implementation should ignore unknown values. But my point is that, as an RP, you can't start using new values of authenticatorAttachment without knowing that the user-agent supports them, lest your attachment preference becomes completely ignored.

That's one of the things that this proposal is trying to address: by having a list of strings we can define new hints in the future without RPs needing to worry that adding them will break older user agents.

It's a bit of a concern that we are adding a third area for authentication selection, given that we already have transports and attachament selectors. So I think the bigger risk is for there to be inconsistent and odd behaviours if you specify multiple or combinations of these parameters.

I agree, but I think the direction that we should head in is to move away from the current authenticatorSelection and transport hints.

The platform/cross-platform values were intended to express whether a credential was desired for local reauth or for signing in. And the transport hints were intended to guide the UI between prompting for a security key or not. But both are getting quite awkward:

People took "cross-platform" to mean "security key", but now it means phones too and doesn't even mean "not platform" any more: if the platform authenticator is syncing to a phone then it's a candidate for attachment=cross-platform. Likewise, attachment=platform can get you a credential that you can use on another machine (e.g. making a credential on a hybrid-capable phone).

Transports are stressed by the fact that authenticators can gain transports now—they're not fixed-function. Lots of credentials with transports=["internal"] became effectively ["internal", "hybrid"] when we updated Android, but of course weren't actually updated.

So, overall, my thoughts are that:

• A list of strings is more future proof than single values.
• This mechanism isn't just about attachment, it should be the mechanism for any number of things in the future.
• authenticatorAttachment and transports are increasingly inapplicable.

[Kieun]

So, overall, my thoughts are that:
A list of strings is more future proof than single values.
This mechanism isn't just about attachment, it should be the mechanism for any number of things in the future.
authenticatorAttachment and transports are increasingly inapplicable.

@agl You mean that at some point the authenticatorAttachment and transport hints are retired?
If so, the RP expects and requires the platform authenticator with internal transport to register the credential with non-security-key hint, but the client still offers hybrid registration UX which is not expected.

Is it better to define more specific hints? e.g., platform, security-key, hybrid

[agl]

I would vote for two additional hints:

mechanism-selection: Indicates that the rp should show as "landing page" the list of all options.

Does that apply to both create() and get() in your mind? I ask because we're rethinking that UI in Chrome for the get() case. (And I assume that you've some familiarity since you're using the Chromium terminology.)

cable-qrcode: Indicates that the rp should show as "landing page" the QR Code to initialize cable

Are you thinking that this always shows a QR code, even if the user has a linked phone? Or is it more generally suggesting using a phone? The latter is what I was getting at with non-security-key. I don't like that name, but I hesitated to call it anything too specific. Maybe "smartphone" is a good answer?

[agl]

You mean that at some point the authenticatorAttachment and transport hints are retired?

Potentially. Or at least sites often stop populating them. (Many sites have never supported transport hints.)

Is it better to define more specific hints? e.g., platform, security-key, hybrid

I was aiming at defining the general interface first but perhaps that's just obscuring things. Have added these in the latest update.

[denniskniep]

@agl

Does that apply to both create() and get() in your mind? I ask because we're rethinking that UI in Chrome for the get() case. (And I assume that you've some familiarity since you're using the Chromium terminology.)

I would see this feature definitely in create(). get() is working fine if it uses the last used option (if possible and makes sense). No need to start always at the very beginning with the selection. It should be as quick as possible, because we use get() a lot more than create().
Indeed, I recognized these terms in the chromium code base while I was searching what was changed that now the QR Code is the first screen (for Cross-Plattform + RK + WithoutRegisteredPhone)

Are you thinking that this always shows a QR code, even if the user has a linked phone? Or is it more generally suggesting using a phone? The latter is what I was getting at with non-security-key. I don't like that name, but I hesitated to call it anything too specific. Maybe "smartphone" is a good answer?

I like the "smartphone" approach (technically the enum value could maybe more generic like DeviceWithBLEAndCamera?). An reasonable implementation could be that the UI shows the list of registered devices (phones, tablets, ...) and offers a button "Use different phone or tablet".

[Firstyear]

People took "cross-platform" to mean "security key", but now it means phones too and doesn't even mean "not platform" any more: if the platform authenticator is syncing to a phone then it's a candidate for attachment=cross-platform. Likewise, attachment=platform can get you a credential that you can use on another machine (e.g. making a credential on a hybrid-capable phone).

Yeah, I'd certainly agree here - as an enterprise it's currently impossible to really filter authenticators ahead of time with registration with the current fields. And as you correctly note, the lines are certainly becoming blurred with cable and phones as platform authenticators, that also can be cross platform.

If we are proceeding in this way, would it also be worth future consideration to deprecate the "transports/attachment" parameters or to add elements in the spec since they are quite confusing and often not always correct?

[MasterKale]

For the record, in general we've been fine with how browsers handle authentication when we return transports during auth. Thus I'm evaluating this all through the lens of "how can we guide users to successful registration."

My higher-level requirement has been centered around the desire to individually trigger browsers' "security key" and "hybrid" flows so that we could show corresponding verbiage shown beforehand. The verbiage would help users understand what the browser will ask of them since some aspects of passkeys registration are still relatively new.

If I'm understanding this correctly, the intent of hints would be that an RP like me adds the new property to our registration options to "suggest" to the browser that it only show the hybrid flow?

{
  // ...
  authenticatorSelection: {
    authenticatorAttachment: 'cross-platform'
  },
  hints: ['non-security-key'],
}

Maybe "smartphone" is a good answer?

What about "other-device" or external-device? It leaves the door open for other form factors to participate (e.g. someone could use an iPad, which doesn't really fit into the idea of "smartphone")

[Firstyear]

If I'm understanding this correctly, the intent of hints would be that an RP like me adds the new property to our registration options to "suggest" to the browser that it only show the hybrid flow?

{
  // ...
  authenticatorSelection: {
    authenticatorAttachment: 'cross-platform'
  },
  hints: ['non-security-key'],
}

Maybe "smartphone" is a good answer?

What about "other-device" or external-device? It leaves the door open for other form factors to participate (e.g. someone could use an iPad, which doesn't really fit into the idea of "smartphone")

For enterprise, we'll need the opposite - to completely deny smartphones and hybrid due to the fact these platforms are unattested and third party backed. We'll need a way to limit to only tpm's and fido2 security key devices (generally, things that have aaguids). This is why in the past we've requested that during registration we can send a list of aaguids as a filter for "these are the only devices acceptable under our policy, so only proceed with them".

[Kieun]

As far as I understand, the hints are not requirements. If so, the clients might not respect RP's preference and intention and the same request from the RP might be handled by clients differently.

[Firstyear]

Yes, I know they are hints, but they are still hints that would improve enterprise workflows in most cases by not proceeding with devices that are unable to succeed.

[MasterKale]

Thinking out loud about potential string values for hints:

security-key
platform-local
platform-roaming

🤔

[agl]

(Notes from the call of 2023-05-17: I should update to include three values: security-key, local-device, and hybrid. Should document expected values of attachment for those cases and define that attachment (and transports?) are ignored when hints are given.)

[MasterKale]

...users will satisfy this request with a [=platform authenticator=]

I think this would benefit from something explicitly tying this option to the "locally available" platform authenticator, the same device as the device the user is logging into. For me the ambiguity comes from the fact that hybrid implies use of a platform authenticator, but of course on a separate device than the access device the user is actually using.

[Firstyear]

hybrid doesn't preclude security key on a remote device over cable though. We already have this working via webauthn-rs. hybrid just means "caBLE" here.

I'd say platform authenticator is reasonable here since to me it implies "same device" but perhaps "device bound authenticator" is clearer.

[MasterKale]

...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.

[agl]

client-device, not local device.

[MasterKale]

Approved pending the replacement of "local-device" with "client-device"

[MasterKale]

As per the WAWG meeting on 7/12 this is okay to be merged before the next meeting when it's ready.

[agl]

From call of 2023-07-12: ok to land if Akshay and Emil are happy.

[emlun]

LGTM! Just one minor, optional nit.

[agl]

From call of 2023-08-16: good to merge.