We need to define a permissions model and recommendations for app distributor and platform policies.
Definitions
Credential types
Right now, we have only implemented passkeys, but eventually we intend this portal to accept credential types password,public-key, digital,and identity, corresponding to types in the W3C Credential Management API. For clarification digital credentials refer to Verifiable Digital Credentials, which may represent mobile driver's licenses, passports and various other highly sensitive documents. identity credentials refer to FedCM credentials, which is essentially a way to integrate with federated identity providers with a structured JavaScript API. These are not "identity documents," like digital conveys.
Recommended policies
First, some baseline recommendations:
App distributors
- All unscoped apps should be manually reviewed, as those create universal phishing vectors, regardless of whether the origin is explicitly prompted
- For scoped apps, where automated review is allowed, the distributor may cretae a stricter policy requiring manual review, for example, initiating manual review if there is a long list of origins specified (more than 3?), or if particularly sensitive domains are listed (sites associated with government, financial, cryptocurrency services)
- Distributors should reject apps with origins on the Public Suffix List (this is enforced by the portal for passkeys, but can't be enforced for passwords or TOTPs)
- Passkeys (
type: public-key) are origin-bound and are much less sensitive than passwords, TOTPs, and digital credentials
- Distributors should do due diligence to ensure that clients adhere to the "Privacy considerations for clients" section of the WebAuthn specification.
digital credentials often represent some sort of human identity, like driver's licenses, passports, work credentials, employee badges, etc. Since these inherently contain highly sensitive PII, these credentials should be prompted for separately from credentials that merely attest to an online account. (Note that these online accounts may grant access to PII, so should also be handled carefully, but digital credentials are.)
Platforms
- If there is no site attestation, then there should be explicit prompts for each origin requested
- Users should be prompted for credential types separately from origins. That is, an app should request specific permission from the user to use
passkeys at all separately from using passkeys for. Platforms can design consent screens to elide the app-specific credential type permission + origin-specific request permission into one screen where applicable. Credential types can be grouped into categories based on sensitivity, for example "online" credentials (password,totp, public-key, identity) can be consented together all at once, while digital credentials are separate
- As mentioned above,
digital credentials are highly sensitive, so special consent screens should be display when the app requests them. Regardless of origin, digital credentials should be treated as special, as they typically convey highly sensitive PII that cannot be scoped to an origin.
Permissions Model
Here is a truth table representing the possible states from most sensitive to least sensitive. Here is an explanation of the columns:
- Scoped: The set of origins that an app can request is limited to at static set determined at build time and perhaps reviewed by the app distributor.
- Site-attested: the site listed in the origin
- Manual Review: Whether the app distributor reviews the permissions for the app manually
- Origin Prompt: Whether the platform shows a permission prompt for every new origin that the app requests credentials for. ("App A wants to access credentials for example.com")
(Note that we can't do site-attestation right now, but we should leave room for it in the permissions model to be able to do later.)
| Scoped |
Site-attested |
Manual Review |
Origin Prompt |
|
Purpose/Notes |
| N |
N |
N |
- |
X |
All unscoped apps should be manually reviewed |
| N |
N |
Y |
N |
✅ |
Browsers only |
| N |
N |
Y |
Y |
✅ |
Self-hosted apps |
| N |
Y |
N |
- |
X |
All unscoped apps should be manually reviewed |
| N |
Y |
Y |
N |
✅ |
Apps for self-hosted services with manifests configured |
| N |
Y |
Y |
Y |
X |
If the site attests to the app and it is manually reviewed, I don't see why we can't skip the origin prompt |
| Y |
N |
N |
- |
X |
Scoped, but unattested apps should be manually reviewed |
| Y |
N |
Y |
N |
X |
If the app is not attested, we must do origin prompts |
| Y |
N |
Y |
Y |
✅ |
If the app is not attested, we must do origin prompts |
| Y |
Y |
N |
N |
✅ |
If the site attests the app, then seems fine to skip origin checks. Review can be automated too, as long as the list of origins is not long |
| Y |
Y |
N |
Y |
X |
If the site attests the app, seems fine to skip origin checks |
| Y |
Y |
Y |
N |
✅ |
The app review could be skipped, but also could be manual per distributor policy |
| Y |
Y |
Y |
Y |
X |
If the site attests the app, seems fine to skip origin checks |
So ignoring the ones that require site attestation, there are 4 levels of permissions that I would like to support (and a two more that we can target later with site attestation1):
- unscoped, silent client: a client that can request credentials from any origin, and does not need permission prompts requesting credentials for a particular origin. This should be reserved for web browsers.
- unscoped, explicit client: a client that can request credentials from any origin, but requires a new permission prompt for each new origin requested. This is useful for apps that do not know what origin the user might use, but will be a small set of origins in typical use. For example, for an app that works with self-hosted software.
- scoped, explicit client: a client that can only request credentials for a specific set of origins
- no-privileged client: And of course, a client that has no permission to request any credentials for apps that don't need it, like a calculator app.
Entitlement Design
So all that being said, we can accomplish this with entitlements. We should iterate on the design of the entitlements to make sure that the above permission model can be easily expressed, understood and parsed by both developers and app distributors/reviewers.
Here is a concrete strawman for the sake of discussion:
[Policy entitlements]
grant=org.freedesktop.portal.Credential
# A client must either declare PrivilegedClient or ScopedClient
# Privileged clients can request any origin, but may or may not require permission prompts for each origin they request credentials from. Their credential types are still restricted and should be prompted for at least at the app level.
[Policy org.freedesktop.portal.Credential.PrivilegedClient]
# Privileged clients still must declare their credential types
types=public-key,password,totp,digital,identity
# Whether the app must obtain consent from the user for each origin.
# `implicit` should be considered highly sensitive and reserved for browsers only.
origin-consent=<implicit,explicit>
# Map of allowed credential types per-origin, along with the location of the attestation URL.
[Policy org.freedesktop.portal.Credential.ScopedClient]
# attestation-url is optional. If specified, the attestation URL's hostname must be from the same origin, and will be checked by the distributor, and by the platform at install time and request time.
# If the check is successful, then origin prompts will be skipped by the platform.
# If the check is not successful, the platform may decide to reject the request, or to display a prompt. A future edition of this entitlement may require the platform to reject the request if the check fails.
https://acme.com=types:public-key,password,digital;attestation-url:https://acme.com/.well-known/manifest.json
https://acme.org=types:public-key,password,digital;attestation-url:https://acme.org/.well-known/manifest.json
TODO
We need to define a permissions model and recommendations for app distributor and platform policies.
Definitions
Credential types
Right now, we have only implemented passkeys, but eventually we intend this portal to accept credential types
password,public-key,digital,andidentity, corresponding to types in the W3C Credential Management API. For clarificationdigitalcredentials refer to Verifiable Digital Credentials, which may represent mobile driver's licenses, passports and various other highly sensitive documents.identitycredentials refer to FedCM credentials, which is essentially a way to integrate with federated identity providers with a structured JavaScript API. These are not "identity documents," likedigitalconveys.Recommended policies
First, some baseline recommendations:
App distributors
type: public-key) are origin-bound and are much less sensitive than passwords, TOTPs, and digital credentialsdigitalcredentials often represent some sort of human identity, like driver's licenses, passports, work credentials, employee badges, etc. Since these inherently contain highly sensitive PII, these credentials should be prompted for separately from credentials that merely attest to an online account. (Note that these online accounts may grant access to PII, so should also be handled carefully, but digital credentials are.)Platforms
passkeysat all separately from usingpasskeysfor. Platforms can design consent screens to elide the app-specific credential type permission + origin-specific request permission into one screen where applicable. Credential types can be grouped into categories based on sensitivity, for example "online" credentials (password,totp,public-key,identity) can be consented together all at once, whiledigitalcredentials are separatedigitalcredentials are highly sensitive, so special consent screens should be display when the app requests them. Regardless of origin, digital credentials should be treated as special, as they typically convey highly sensitive PII that cannot be scoped to an origin.Permissions Model
Here is a truth table representing the possible states from most sensitive to least sensitive. Here is an explanation of the columns:
(Note that we can't do site-attestation right now, but we should leave room for it in the permissions model to be able to do later.)
So ignoring the ones that require site attestation, there are 4 levels of permissions that I would like to support (and a two more that we can target later with site attestation1):
Entitlement Design
So all that being said, we can accomplish this with entitlements. We should iterate on the design of the entitlements to make sure that the above permission model can be easily expressed, understood and parsed by both developers and app distributors/reviewers.
Here is a concrete strawman for the sake of discussion:
TODO
Footnotes
Eventually, I'd like to add the ability to express a scoped, silent client, where the set of origins is not only determined by the app developer, but also attested by the origin's site via some manifest referring to the app. That could enable automatic app store approvals and skipping permission prompts (because the permission is verified outside of the control of the local machine). But that requires other ecosystem updates outside of the control of this project and can be done later. ↩