Skip to content

Latest commit

 

History

History
137 lines (91 loc) · 12.2 KB

explainer.md

File metadata and controls

137 lines (91 loc) · 12.2 KB
Raw

Digital Credentials API

Government recognized digital credentials (e.g. driver’s licenses) are being increasingly utilized on the web. We propose a deliberate and flexible API to enable browsers to continuously improve the balance of benefits and risks for users and the entire online community.

Why?

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 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 protocols (e.g. OpenID4VP) and regulations (e.g. eIDAS) were designed around a Web that lacked the intentional support for such a critical task; depending instead on general purpose primitives such as custom schemes. 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 is paramount that we not only strive for ease of use but also exercise utmost caution to uphold high standards of security and privacy. This is essential to safeguard users from potential identity theft and ensure they are fully informed about the implications of online identity sharing before providing their consent. We firmly believe that relying on a browser API and the mobile platform is the most reliable approach for identity digital credentials to be shared securely online.

What?

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, 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 indirections that would allow us to extend the API without having to redesign it. Sometimes, extensibility, autonomy (eg. of different standards bodies) and the ability/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 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 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 transparently request the selective disclosure of attributes from (issued) digital credentials that were provisioned - ahead of time - to wallets ("holders"), in a manner that is seamlessly compatible with existing architectural choices (such as OpenID4VP integration).

Here is an example of how the  the API might be used in practice:

The API needs to be initiated through a user gesture, such as a button click:

<button onclick="requestCredential()">Request Driver's license<button>
async function requestCredential() {

  // Check for Digital Credentials API support
  if (typeof window.DigitalCredential !== 'undefined') {
    
    try {
      
      // These parameters are typically fetched from the backend.
      // Statically defined here for protocol extensibility illustration purposes.
      const oid4vp = {
        protocol: "oid4vp", // An example of an OpenID4VP request to wallets. // Based on https://github.com/openid/OpenID4VP/issues/125
        data: {
          nonce: "n-0S6_WzA2Mj",
          presentation_definition: {
          //Presentation Exchange request, omitted for brevity
          },
        },
      };

      // create an Abort Controller
      const controller = new AbortController();

      // Call the Digital Credentials API using the presentation request from the backend
      let dcResponse = await navigator.credentials.get({
        signal: controller.signal,
        mediation: "required",
        digital: {
          requests: [ oid4vp ]
        }
      });

      // Send the encrypted response to the backend for decryption and verification
      // Ommitted for brevity

    } catch (error) {
      console.error('Error:', error);
    }
  } else {
    
    // fallback scenario, illustrative only
    alert("The Digital Credentials API is not supported in this browser.")
  }
};

Example from: https://digitalcredentials.dev/docs/verifier-site/requesting-cred

You can read a more detailed and technical description of the API in the specification draft.

Using the API from another origin

The specification allows usage of the API from a remote/third-party origin via the "digital-credentials-get" Permissions Policy. This is useful for scenarios where a website wants to request digital credentials from a wallet provider that is hosted on a different origin. The Permissions Policy can be set on an iframe that embeds the website that wants to use the API. Here is an example of how the Permissions Policy can be set on an iframe:

<iframe allow="digital-credentials-get"></iframe>

Horizontal reviews

Alternatives Considered

There are many alternatives that were considered, most notably:

Open Questions

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?

Out of Scope

The following topics are currently out of scope for the API:

  • A website (issuer) requesting the issuance of a digital credential to a digital wallet
  • A website (verifier) explicitly requesting multiple digital credentials from multiple wallets in the same request

Related Work