Credential Handler API/Polyfill

Work Item for the W3C Credentials Community Group

1

Credential Management API

• An existing API that currently enables getting and storing credentials
• Current support is limited to same origin credentials like passwords
• Extensibility requires updating the browser for every new type of credential (does not scale for our work)
• https://www.w3.org/TR/credential-management-1/

2

Credential Handler API

• New API defines an extensible credential type “WebCredential”
• Extension to Credential Management API that enables third party websites to handle WebCredential requests (for both retrieval and storage of credentials)
• WebCredentials can have more specific subtypes like “VerifiableProfile” with their own specifications that do not require browser code to be updated

3

Design - Credential Handler Installation

4

CredentialManager.requestPermission()

​

// if permission was granted...

registration = CredentialHandlers.register(

‘/credential-handler’)

registration.credentialManager.hints.set(

‘hintId’, {name: ‘Identity 1’, icons: [...]})

success/error

User visits a “Credential Wallet” website. The site installs a credential handler that registers “hints” with the browser they can select later.

(aka digital wallet)

A “hint” is associated with a particular “identity” belonging to the user.

Design - Storing credentials

5

promise = navigator.credentials.store(

new WebCredential(‘verifiableProfile’, …)

result = await promise

handler.addEventListener(

‘credentialstore’, event => { … })

event.respondWith(...)

User selects a credential repository via preregistered hints displayed on a browser UI

User visits a website that wants to give them credentials...

User stores credentials via their digital wallet’s UI

(aka digital wallet)

Design - Requesting credentials

6

promise = navigator.credentials.get(...)

result = await promise

// result contains a signed VerifiableProfile

handler.addEventListener(

‘credentialrequest’, event => { … })

event.respondWith(...)

// repository sends VerifiableProfile

User selects a credential repository via preregistered hints displayed on a browser UI

User visits a website that requires

credentials for some action...

User composes a VerifiableProfile of credentials via their digital wallet’s UI

(aka digital wallet)

Current Work

• https://github.com/digitalbazaar/credential-handler-polyfill
• https://github.com/digitalbazaar/credential-mediator-polyfill
• https://credential-repository.demo.digitalbazaar.com
• https://credential-issuer.demo.digitalbazaar.com
• https://credential-verifier.demo.digitalbazaar.com

7

Issues

• A signed “VerifiableProfile” is returned when credentials are requested; which software component is responsible for signing it? (https://github.com/w3c-ccg/credential-handler-api/issues/1)
• See other issues: https://github.com/w3c-ccg/credential-handler-api/issues

8

Example of Registering a Credential Repo/Digital Wallet

const registration = await CredentialHandlers.register(

'/credential-handler');

// add a hint for the user to select the credential handler

await registration.credentialManager.hints.set(

'e686ebe5-2e0f-4f42-b997-9eb520a50ab3', {

name: 'My personal identity #4',

icons: [...]

});

9

Example of Storing a Credential

// store a WebCredential containing a VerifiableProfile

navigator.credentials.store(new WebCredential(

'verifiableProfile', {

'@context': 'https://w3id.org/credentials/v1',

id: 'did:ex1:1234-1234-1234-1234',

credential: [...]

}));

10

Example of Sharing a Credential

const credential = await navigator.credentials.get({

web: {

verifiableProfile: {

name: true

}

}

});

// credential.data is a VerifiableProfile

11