These are some ideas and concepts we need to convey in the UI. Writing these out fully to make it clear. I will update as I come up with more, and maybe do some paper wireframes and add screenshots from other OS implementations.

Entrypoints

There are two main entrypoints: browsers and apps. Browsers and apps have different permissions prompts, but the UI for the authentication ceremony should be the same

Intro screen

Maybe the first time a user uses the credential portal, they should be introduced to it. Or maybe just for passkeys since they're new? Or maybe we just let the normal UI guide them.

e.g.

• "This is GNOME Credentials, here's what you can do," or
• "This is what a passkey is, click to continue"

UI modes

• Standard: a modal over the window of the app that called it.
• Ambient: a non-intrusive window (e.g. a notification) that can be activated by the user. This is useful for browsers if they want to sign in users if they have credentials, but otherwise let them keep browsing

Permissions

Cf. #184

This section is sort of out of scope of this particular project, since it involves the UX of various app distributors, but still good to get an idea of how we want to do this so we can all agree.

Permissions are based on web origins (think domain, like example.com). An application/browser can have different levels of permission per origin.

• privileged: no explicit permission prompt for the origin
• unprivileged: requires an explicit permission prompt for the origin

These privilege levels can be scoped to a particular origin or global (any origin).

Only browsers should be granted global, privileged access to credentials. They should be prompted the first time they try to use any origin with "ExampleBrowser wants to access credentials for all websites." This permission should also be clearly displayed before installing the app, but that's up to app distributors.

Other combinations are allowed:

• an app may be granted privileged, scoped access to its corresponding web origin(s), e.g., a Spotify app could be given privileged permissions to spotify.com to skip prompts.
• an app may be granted unprivileged, global access, for example, for an app that allows configuring self-hosted software. "FooApp wants to access foo.self-hosted.home". This will be prompted separately for each domain.
• an app may be granted unprivileged, scoped access to an origin. This is useful if the developer of a third-party app does not have the appropriate access to associate the origin with their app: they may have the user's machine prompt them "ThirdPartyApp wants to access credentials for acme.com"

These can also be mixed, e.g. if FooApp has a flagship instance of the service at fooapp.com, they could be given privileged, scoped access to that origin, but unprivileged, global

(On a technical note, these permissions are requested by the app developer via entitlements, and should be checked by the app distributors whether it is valid, which should help that last category of unprivileged, scoped access from becoming an unmitigated phishing vector.)

Permission persistence

Do we want to have the ability to grant permissions scoped by time? I.e., This time, Always, Not this time, Never?

Runtime vs. install time permission prompts

We need to decide whether prompting at runtime is necessary or just at install time. I lean toward being more explicit in this case and doing it both install time and runtime, since it might be a gap of time before they request credentials after installing.

Managing Permissions

We probably should have a way to list the origin permissions for each app. Does this belong in GNOME Settings?

Credential Selection

The credential selection screen should make a few things clear:

• whether a credential is being created or asserted/used
• the origin of the request (app ID, or browser + website domain), requested credential domain (e.g. WebAuthn RP ID for passkeys, or just a "service identifier" for passwords, etc.)
• if the request is "cross-origin", then notify the user "somehow".
  • an app using the global, unscoped permission can be considered cross origin, but there are only two IDs involved, the App ID and the requested origin.
  • A browser request can be considered cross-origin when it reports the "top origin" to be different than the request origin, e.g. if the request is coming from a bank.com iframe on a merchant.com webpage. In this case, there are two origins plus the browser that should be displayed.
• the credentials that are available for the request
• other credentials that don't match explicitly, but may nonetheless be applicable (e.g. if a password request for example.co.uk comes in, but the user has a credential example.com stored, but it's the same relying party using a different domains for different regions). This does not apply to passkeys, since origin binding is required.

The credentials available can be split along a few dimensions:

• credential types
• known vs. known
• device/authenticator transport

"Known" vs. "Potential" Credential sources

Some credentials are known to match the incoming request as soon as it starts. This includes:

• passkeys stored in the platform authenticator
• passkeys and passwords stored in a password manager that has pushed credential metadata to credentialsd
• linked CTAP2 hybrid devices (e.g. a smartphone that you have previously connected to this computer and opted to save a connection to)
• A plugged in USB authenticator with a CTAP2 PPUAT (essentially, a token with permission to view credential metadata on the USB device)

Potential credentials are all the other types of credentials that are not known to the service at request time, like

• USB (without that token support mentioned above), NFC, BLE authenticators
• credentials on other devices, accessed via CTAP2 hybrid QR code
• locked credential provider

The "known" credentials should probably be prioritized over the "potential" credentials. Some of the potential credentials require a click (like the locked credential provider), but others may be activated by the user in other ways to advance the ceremony (e.g. scanning the QR code, touching the USB key, tapping the NFC credential).

Credential Types

We intend to allow apps to request multiple credential types for logging in, like passkeys, passwords. (On creation, only one credential type is allowed.)

When apps request multiple credentials to authenticate with, we'll need to distinguish the type of request (and probably prioritize passkeys over passwords)

Credential transports

USB

When a USB credential is plugged in, it becomes immediately available as a credential source. The physical device itself begins blinking, and the user can touch it to select this credential.

One UI quirk that different desktop platforms do differently is around what to do when multiple USB credentials are plugged in. macOS requires you to touch the USB device (to select), enter the PIN, and then touch again to assert user presence. Windows skips the first touch and allows you to click on the USB device, skipping straight to PIN entry, and then one touch for user presence. (I think they may also automatically advance to the USB screen when it is plugged in and there is only one available.)

(The platform may also have a PPUAT that allows it to query the available credentials. Should we update the list of known credentials when this happens?)

• If the user plugs in their USB device, should we immediately switch to it, or should we still require a touch?

Assuming we're going with "touch to select," here's a general flow:

1. User plugs in device (or it was already plugged)
2. User touches device to select it.
3. Potentially, the authenticator transitions to requesting built-in UV (basically fingerprint on all known devices)
   1. The user UV attempt may fail (wrong finger, not quite right, device glitch). Atte
      • attempts left means total attempts left until the authenticator will no longer allow fingerprint auth, and the user must use a PIN. It doesn't mean authenticator reset, like on the PIN step below.
      • It also is global (e.g. lasts between power cycles, and there may be an internal per-power cycle limit that is not given to us)
   2. Step 1 may repeat, decrementing attempts left.
   3. The authenticator may decide to short-circuit the attempts left and jump to PIN auth.
      • this is unfortunate, since the user can become confused if there are 3 attempts left, but it jumps to PIN auth. Maybe we shouldn't show the number explicitly here.
4. Authenticator transitions to requesting PIN. UI shows PIN entry dialog
   • This may be skipped if no PIN is set up and user verification is not required by the RP.
   • This may also be skipped if a fingerprint was used for user verification.
5. Potentially, the user enters the wrong PIN. UI shows how many attempts left before total reset of the device occurs.
   • We should probably also make the user unplug and replug the device after a few attempts to slow them down from burning up all their attempts and perhaps remind them that they're using a different authenticator than they're expecting.
   • we should probably deduplicate PIN attempts and let the user know "you already tried that one" (technical point, we shouldn't store the actual PIN, just a cryptographic hash suitable for passwords of the PIN for comparison"
     • if we do that, I don't know whether we should store the PIN hash between power cycles
6. The user enters the correct PIN

Hybrid QR Code

1. The UI displays the hybrid QR code
   • we need to decide whether to always do this, or to require a click.
   • there may be some concern about shoulder surfing the QR code, but I'm not sure that's a wide enough concern to warrant hiding it by default.
2. User scans QR code. UI transitions to showing a "Connecting" state, giving instructions that the
   • This requires Bluetooth to be enabled on both devices. We probably will automatically enable Bluetooth for the user. (Maybe if Bluetooth is not enabled on the laptop, we would hide the QR code and require an explicit click to start the flow, with implicit consent to start Bluetooth) The user might need to be instructed to enable Bluetooth on their other device.
   • Android is going to start skipping the prompt to enable Bluetooth and just do it automatically when the QR code is scanned, and I think currently both Android and iOS prompt the user to enable Bluetooth if they scan and it's turned off. So this might be a responsibility of the mobile device platform, not ours. But other UIs, like Chrome, instruct the user to "keep the devices close together and have Bluetooth enabled."
3. User's device finishes connecting. UI transitions to showing a "Connected" state.
   • The user should be instructed to "follow the instructions on the mobile device"
4. Potentially, the user quits or there is a connection error
   • Return an authenticator error back to the UI
5. User selects credentials on their mobile device, and the credential is sent back to the laptop
6. ? User is prompted to store this device for later
   • As mentioned elsewhere, maybe this could be a notification that the user clicks since it's sort of out of band of the ceremony they're trying to accomplish
7. UI completes, credential is returned to calling application.

Credential Provider

If the user selects one of these, the credential provider will be notified to unlock the vault (if necessary) and collect user verification. The credential provider may defer to something like Polkit for user verification, which would mean that their app's window is never drawn, so they can go straight from clicking on the credential, to authenticating with Polkit, and back to the calling application with the successful credential.

TODO: expand on this

Linked Device

1. User clicks on linked device, transitions to "Connecting" state
2. User's mobile device gets a notification
3. Potentially, the user denies
   • Return an authenticator error back to the platform
4. The user accepts, UI transitions to Connected.
   • The following steps are the same as hybrid QR code flow above, with the omission of the device linked, since this one is linked already.
5. Potentially, the user quits or there is a connection error
   • Return an authenticator error back to the UI
6. User selects credentials on their mobile device, and the credential is sent back to the laptop
7. UI completes, credential is returned to calling application.

Platform authenticator

• if we do device-bound credentials, we should call out that they are not backed up, and the user should register multiple authenticators if the website allows it.
  • maybe this could be a low-priority notification sent after the assertion, if we detect that there are no other credentials (excludeCredentials is empty on the WebAuthn registration request)
  • We could also use WebAuthn signals on assertion, if signalAllAcceptedCredentials says that the only credential is the device-bound credential we just used, we could send a warning notification.

NFC

TODO

BLE

TODO

Other sorting

• Should we sort by last used credential per origin? Or just by longest matching origin, and then alphabetically by username? Or maybe both (promote last used credential on top, and then do origin/username sorting. I think Windows Hello does this)
• Apps have the ability to influence the portal UI via hints, e.g. if they know their user's credential is a security key, they can pass security-key as a hint so that we should show the security key option prominently so the user isn't confused. These are just hints, so we shouldn't remove the other options, only prioritize the hinted ones.

Other screens

These may or may not belong inline in the ceremony flow.

• Setting up a PIN on the selected CTAP2 authenticator if the RP requires UV and it is not set
• Setting up built-in UV, e.g. enroll fingerprint onto the device
• Linking a hybrid device, post ceremony
  • Maybe a notification they can click to store the connection to the device?
• Multiple credentials: sometimes a selected CTAP2 authenticator returns multiple matching credentials after doing user verification and user presence. One needs to be selected by the user. (Mostly applicable for physical keys, like USB, NFC, BLE)
• Sidenote: Users should probably be able to travel back and forth between different authenticators during the ceremony. E.g., if they try a USB credential, but it says there are none matching, they should be able to go back and try a different USB authenticator, without going all the way back to the app and retrying.
• Errors:
  • No matching credentials found on this authenticator
  • Matching credential already exists (on creation), don't need to create another one
  • general authenticator error
  • PIN not set