Government-recognized digital credentials (e.g., driver’s licenses, passports) and other digital attestations are being increasingly utilized on the web. We propose a deliberate and flexible API to enable browsers to mediate both the presentation and issuance of these credentials, aiming to continuously improve the balance of benefits and risks for users and the entire online community.
Government-recognized documents play a big and constructive role in society (e.g., drivers licenses, passports, etc.). Increasingly, with the movement of government and financial services online, and regulation (e.g. eIDAS and various age verification regulations), these paper-based documents are gaining digital counterparts
Along with all of their potential from the physical world, the issuance and presentation of government-recognized digital credentials also brings their associated risks of abuse, such as the potential for an increase in surveillance, censorship, discrimination, and intrusion to the online world.
The most recent online presentation and issuance protocols (e.g., OpenID4VP, OpenID4CI) and regulations (e.g., eIDAS) were designed around a Web that lacked intentional support for such critical tasks, depending instead on general purpose primitives such as custom schemes. Similarly, the mechanisms by which users are issued these digital credentials often rely on custom schemes or app-specific integrations, lacking a standardized browser-mediated flow. Unfortunately, the use of custom schemes left us with two problems:
Because custom schemes can be largely opaque to user agents, they substantially limit the user agent’s ability to exercise its agency in reducing the risk of abuse. Users rely on their browser to help provide transparency and control over the use of their data. From the subtle, like providing UI cues as to the privacy and security risks of various operations. To the more severe, like warning about interacting with known phishing sites.
Even in highly-regulated and non-abusive use cases (e.g. eIDAS), custom schemes have security and privacy risks, as well as a series of suboptimal user experiences. We posit that these limitations can be addressed by a purpose-built browser API. While some have reasonably argued that these limitations will slow-down and limit the deployment (and so, the abuse) of such technology, it seems more advantageous to rely on intentional design choices to manage this tradeoff than such accidents.
In the pursuit of establishing a standard for web-based identity sharing, it's important to strive for ease of use while also exercising caution to uphold security and privacy standards. This may help mitigate risks like identity theft, so long as relying parties refrain from storing unencrypted credentials on their servers and take care to not needlessly render privacy-sensitive decrypted information on their websites. We believe that a DOM API offers a promising approach for digital credentials to be used on the Web.
First we must acknowledge, architecturally, that this is a rapidly evolving space with a large number of moving parts at various different levels of maturity. Users, regulations (e.g. eIDAS), wallets, verifiers, issuers, formats (e.g. ISO mDocs and W3C VCs, just to name a few) and protocols (e.g. OpenID4VP, OpenID4VCI, ISO REST’s API, VC API), operating systems and browsers (e.g. evolving mitigation strategies, for example) are all still in various stages of formation and need the space and autonomy to evolve efficiently.
So, to the extent that we can, it is important to leave levels of indirection that would allow us to extend the API without having to redesign it. Sometimes, extensibility, autonomy (eg. of different standards bodies) and the abilities/incentives of ecosystem adoption are in tension with other goals, such as the user’s privacy and security, so we often have to find a good and principled balance (e.g. more often than not, users first, developers second, and browser engines third, guides our choices at the W3C).
To balance this tension we propose an API with the following key properties:
- By separating the act of requesting or issuing credentials from the specific protocol, we can enable flexibility and adaptability in both the protocol and credential formats. This way, the pace of changes in browsers won't hinder progress or block new developments.
- Require request transparency, enabling user-agent inspection for risk analysis
- Assume response opacity (encrypted responses), enabling verifiers and holders to control where potentially sensitive PII is exposed
- Websites cannot access any information without user interaction. This API ensures that sites cannot silently query for or issue digital credentials or communicate with wallet providers without the user's active participation and confirmation of each action.
At its core, the API is designed for a website ("verifier") to request the selective disclosure of attributes from (issued) digital credentials that were provisioned, ahead of time, to wallets ("holders"), and for a website ("issuer") to initiate the issuance of new credentials to a user's wallet. The API aims to align with existing architectural choices, such as OpenID4VP integration, and is being developed with the goal of enabling user transparency.
For examples of how to use the API to request or issue a digital credential and a more detailed technical description, please refer to the specification draft.
Please see the requesting and issuing a digital credential across origins.
There are many alternatives that were considered, most notably:
- Do nothing and accept the risk (the intentional status quo in browsers for the past several years)
- Various different API proposals: an mDoc-specific API, extending the Credential Management API, extending the FedCM API and introducing navigator.identity
There are still many open questions, but a few big ones:
- To what extent does the browser introspect the request to wallets (for privacy and security reasons)? How much of that needs to interoperate between browsers, vs. be browser-specific points of differentiation in offering privacy features to users?
- Will existing protocols (example) adopt this API?
- Will regulation (example) adopt this API?
Please see Scope
- Real-world identity on the web - risks and mitigations, Rick Byers
- Concerns with custom schemes for identity presentment, Rick Byers
- Digital Credentials API Standards Position, Marcos Caceres
- User considerations for credential presentation on the Web, Nick Doty
- Privacy Principles, Jeffrey Yasskin and Robin Berjon
- Intent to deprecate forwarding of mdoc-scheme URLs as Android Intents, Adam Langley
- Wallets on the web - PING @TPAC, Rick Byers
- Chromium: RWI privacy risk mitigation design, Rick Byers