Verifiable Credentials integration - Solution Notes

Owned by Glib Glugovskiy
Last updated: Jun 09, 2023
12 min read

Status

The implementation of the Verifiable Credentials integration is in progress as part of .

Comments and questions about Verifiable Credentials are welcome.

Related Epic in credentials roadmap: https://github.com/openedx/credentials/issues/1731

ADRs: https://github.com/openedx/credentials/pull/1846

Open questions

 

Q: For what activities the credentials can be issued?
A: Get program certificate (for now), in the future get course certificate, get degree.

 

Q: Are there any arguments against storing the records about issued credentials in system DB?
A: To implement actual decentralization we may not need to store data about issued credentials in DB, except revocation list index, and relation to a Program certificate (course certificate support will be added latter)

 

Q: Using sign-and-verify node service or create a native python implementation of signing service.
A: Open edX and DCC would benefit from creating sign-and-verify functionality as a Python module. However, it may require a great effort to port underlying functionality to the Python module. Solution: discover python libraries identical to JS libraries for sign-and-verify functionality.
UPD: we decided to use python bindings to Rust based library DIDKit. The details can be found in the section #Signing Credential.

 

Q: Are there solutions to support multitenancy (multiple issuers on one installation), using sign-and-verify service?
A: It’s possible to sign VC with several signatures (unordered list), or with a chain of signatures. It’s required to add an additional implementation to DCC sign-and-verify, to support it.

 

Q: Using Status list 2021 instead of Revocation list 2020
A: The revocation List is built on the top of status list, it’s better to use Status List 2021 implementation for storing revoked credentials.

 

Q: DID for learners adding own DID

A: The issuing request will be coming directly from DC wallet, so we will use wallet DID for the subject, and then store it in DB for reuse. (we may have a mechanism to invalidate DID or enter custom DID). Dmitri Zagidulin: “My only suggestion is to consider /not/ storing the learner's DID for future use.”

Q: OpenBadges3.0 current status
A: Kerri Lemoie: “It should be released as a candidate in November. It will stay in candidate release status until two members of 1edtech have implemented it. The said, the DCC software does already understand OBv3 as of last June. The current status of the OBv3 spec is very close to where it was in June and what will launch in November. We’ll be making those minor updates this fall to accommodate pilots in the JFF & VC-EDU Plugfest #2 ( ) which is required to use OBv3. This is the most recent version of the OBv3 spec: ”

 

Q: What DID method suits better?
A: key + web; The DCC wallet creates did:key IDs for the user. Issuers are using did; key or did:web.

 

Q: Do we need to synchronize with several DID registries?
A: No, the did-method in DID URI, defines the registry for the DID resolver.

 

Q: Does the student select what he wants to include in assertion?
A: According to use cases – Yes, the student can select the accomplishments he wishes to include in the credential.

 

Q: How to link Subject DID with learner profile?
A: Subject DID must be provided by credentials wallet, but user can opt in registering DID in the system.

 

Q: Are there cases of issuing VC to more than one subject?
A: Out of scope for now.

 

Q: Credentials issued by both organizations multi-tenant envs
A: In VC protocol specified that there can be only one credential issuer, so it’s required to issue a credential twice from different issuers.

 

Q: What is the process for adding an issuer to DCC wallet and issuers registries?
A: DCC is currently working on governing around this and similar questions. Right now, it’s recommended to implement as the chain of signed credentials.

 

TL;DR

This work will extend the Open edX Credentials service to allow the sharing of verifiable credentials to external networks. The extension is proposed to be a new Django application in the Credentials service and to be general purpose so as to allow sharing to arbitrary networks in the future.

The focus for the first increment will be the OpenBadges v3 protocol, which is hot off the presses, but is where a lot of energy across W3C, 1EdTech seems to be converging. The first increment will target sharing the the DCC wallet mobile application developed by the Digital Credentials Consortium at MIT.

 

Table of Contents

Intro: Verifiable credentials scheme for education

In the document you will find a description of verifiable credentials concepts, lifecycle, and useful links to vc specifications.

Terminology

VC — Verifiable Credential, according to vc data model (https://www.w3.org/TR/vc-data-model/)

Credential — A set of one or more claims made by an issuer about a subject.

DCC — Digital Credentials Consortium https://digitalcredentials.mit.edu/

Digital Credentials Wallet — Digital wallet for storing verifiable credentials, for example, https://lcw.app/

EBSI — European Blockchain Services Infrastructure. It is a blockchain network of distributed nodes across Europe to support credentials applications. https://ec.europa.eu/digital-building-blocks/wikis/display/EBSI/What+is+ebsi

Existing Implementations

Repository with VC educational use cases – ⁣

Example of issuing HTTP API https://w3c-ccg.github.io/vc-api/#issuing

Libraries to work with VC

Verifiable Credentials in Education Cases

MIT xPRO and DC Wallet (DCC) integration details

https://openedx.atlassian.net/wiki/spaces/OEPM/pages/3539697812

Design Proposal

High-Level design

Overview: The main idea is to create a new Django application in the edX credentials service (). This application will be capable of transforming Open edX credentials, such as program and course certificates, into digital and verifiable credentials, as well as sending generated credentials to learners' credentials wallets or digital badge system accounts.

The global verifiable credentials sharing functionality can be enabled by edx_toggles.toggles e.g., WaffleSwitch or DjangoSetting based on OEP-17

The administrator should enable a VC issuing for an Open edX credential, in Django admin (CourseCertificate/ProgramCertificate configuration) addresses Use Case ID #admin-004

The solution can be divided into separate units:

  • Issuer configuration (including specifying the private keys and credentials)

  • Issuing VC

  • Forming verifiable credentials or digital credentials using the learners' data

  • Invalidating VC (changing status)

  • Issuing digital credentials (badges)

 

Requirements:
An application should:

  • Have a possibility to configure an issuer info

  • Transform data from DB into JSON-LD claim

  • Be able to get learners and issuers data from DB (via API)

  • Sign VC, using an internal or an external signing module

  • Form a QR code or a deep-link to pass request parameters to the digital wallet app

  • Be open for integration with Digital Credentials Wallets and Digital Badges Platforms

  • Allow administrators to restrict which claims can be asserted #admin-004

 

 

Solution diagram

https://structurizr.com/share/72212/diagrams#SystemContext

source:

 

 

Implementation details

Issuer configuration (including specifying the private keys and credentials)

The system should be configurable.
This implementation must cover some system administrators' use cases ​

Django admin configuration

A system administrator should be able to restrict which claims can be asserted by course, program, degree, or organization. This can be achieved either by managing VC availability on CourseCertificate/ProgramCertificate configuration level or by creating a separate model for configuring general issuing policies.

Issuing VC

Restriction issuing request must be initiated by a digital credentials wallet. Issuing is happening directly to the wallet. Every wallet may have its integration solution.

Restriction To Integrate with DCC mobile wallet, the issuer must be added to the application issuers registry: https://github.com/digitalcredentials/learner-credential-wallet/blob/main/app/data/issuerAuth.ts

Issue a credential to DC learner wallet sequence diagram

 

MFE wireframes

The main idea of the issuing UI is to show to a user a list of acquired certificates, allow user to select one or several of them, and include data about completions into VC.

Inspired by My Certificates from the profile MFE and MITxPRO implementation

ref.

Signing Credential

JSON-LD proof is selected as the main assertion format. Other rejected assertion formats can be found at the bottom of this page

As the signing library, we decided to use python bindings to Rust-based library DIDKit.

DIDKit implements VC-api for signing and verifying credentials and can be used as is. (https://www.spruceid.dev/quickstart#step-1-issue-and-verify-your-first-vc-using-a-did)

DIDKit can be used natively with python through the PyO3 bindings. Here’s the example of using it in the Django application:

 

Adding credentials to a digital wallet

There are many wallets. Every wallet may need its algorithm for adding credentials.
DCC learner wallet is an open-source implementation of the digital credential wallet, this application is used by MIT service MITxPRO.

MATTR Wallet is another good example of a digital credential wallet.

Mobile app:

The system generates and hands over request parameters to the digital wallet mobile app using deeplink or QR code.

QR code library

It’s recommended to use djnago-qr library with is based on Segno by https://github.com/spruceid/didkit-python.

The comparison of alternatives can be found in Rejected alternatives section.

MIT digitalcredentials library provides an utility function to generate deeplink and provide required parameters

 

Forming verifiable credentials or digital credentials using the learners' data

Verifiable credentials

Forming a verifiable credential means filling in credentialSubject data https://www.w3.org/TR/vc-data-model/#credential-subject.

credentialSubject.ID - the ID of the subject, who has received a credential. This is usually DID of the learner's wallet.

It is possible to express information related to multiple subjects in a verifiable credential, for example, https://www.w3.org/TR/vc-data-model/#example-specifying-multiple-subjects-in-a-verifiable-credential.

 

Implementation for the course and program certificates for MITxPRO project:

 

Table 1. VC to Course/Program certificates mapping.

? - There’s no corresponded value in the credentials service database

- - This field can be skipped for this type of VC

VC

Open edX Course Certificate class CourseCertificate

Open edX Program Certificate class ProgramCertificate

VC

Open edX Course Certificate class CourseCertificate

Open edX Program Certificate class ProgramCertificate

credentialSubject.hasCredential.name

course_run.title_override or course_run.course.title

program.title

credentialSubject.hasCredential.description

?

program_details

credentialSubject.hasCredential.awardedOnCompletionOf.identifier

-

program_uuid

credentialSubject.hasCredential.awardedOnCompletionOf.courseCode

course_id

-

credentialSubject.hasCredential.awardedOnCompletionOf.type

constant: ["Course", "Event"]

constant: "EducationalOccupationalProgram"

credentialSubject.hasCredential.awardedOnCompletionOf.name

course_run.title_override or course_run.course.title

program.title

credentialSubject.hasCredential.awardedOnCompletionOf.description

?

program_details

credentialSubject.hasCredential.awardedOnCompletionOf.numberOfCredits

?

?

credentialSubject.hasCredential.awardedOnCompletionOf.startDate

course_run.start_date

?

credentialSubject.hasCredential.awardedOnCompletionOf.endDate

course_run.end_date

?

Comments

It’s not clear what to set for the field credentialSubject.hasCredential.awardedOnCompletionOf.numberOfCredits.
In the EducationalOccupationalProgram schema, numberOfCredits corresponds to credit in education based on Carnegie Unit or similar. We have CreditPathways for programs, but don't track that actual number of credits for that institution for that pathway. Is that data that we might need to collect somehow?
I think we either can skip this field from the schema for MVP, consider integration with CreditPathways, or get the value from the field set by Course/Program Creators.

 

Support OpenBadges3.0

OBv3 are supported now by both LC wallet and didkit-python.

To provide credentials in the form of OBv3 we should change the credentialSubject object according to the specification - https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.1.json

 

Support EBSI

EBSI extends VC and adds Verifiable Attestation scheme to VC claim

https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/Data+Models+and+Schemas

The list of conformant wallets: https://ec.europa.eu/digital-building-blocks/wikis/display/EBSI/Conformant+wallets

All implements use case Diploma https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/Diploma+Functional+Scope

 

Invalidating VC (changing status)

The VC status list 2021 concept is the state of the art right now https://w3c-ccg.github.io/vc-status-list-2021/

Conceptual Framework (https://w3c-ccg.github.io/vc-status-list-2021/#conceptual-framework)

This section outlines the core concept utilized by the status list mechanism described in this document. At the most basic level, status information for all verifiable credentials issued by an issuer are expressed as simple binary values. The issuer keeps a bitstring list of all verifiable credentials it has issued. Each verifiable credential is associated with a position in the list. If the binary value of the position in the list is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked.

The example of the credentialStatus

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/vc/status-list/2021/v1" ], "id": "https://example.com/credentials/23894672394", "type": ["VerifiableCredential"], "issuer": "did:example:12345", "issued": "2021-04-05T14:27:42Z", "credentialStatus": { "id": "https://example.com/credentials/status/3#94567" "type": "StatusList2021Entry", "statusPurpose": "revocation", "statusListIndex": "94567", "statusListCredential": "https://example.com/credentials/status/3" }, "credentialSubject": { "id": "did:example:6789", "type": "Person" }, "proof": { ... } }

 

Implementation of the credentials status in DIDKit

The support for issuing credentials compliant with VC Status List 2021 was added to sign and verify services in https://github.com/digitalcredentials/sign-and-verify-core/pull/18

Implementation notes for Status List in Open edX

For the MVP, it was decided to implement status list as an API endpoint that is available out of the box. Deployers with Ops expertise can cache API responses regularly, and host it on CDN to address privacy concerns.

Issuing digital credentials (badges)

OpenBadgesv2.0

Current implementation of OpenBadges2.0 and badgr integtration:

We may move this application to credentials.

There are several dependencies on edx-platform:

 

Future possible enhancements

  1. Integrate VC verifier to use VC as course prerequisites. https://github.com/digitalcredentials/sign-and-verify#verify-presentation, https://w3c-ccg.github.io/vc-api/#verifying

  2. Integrate with other popular wallets

  3. Integrate with edX skills ecosystem and taxonomy connector.

  4. Provide credentials in different languages

  5. Registering ISSUER?

Issuer - can be represented as URI, DID, JWK or object with ID.

DCC issuer registry: https://github.com/digitalcredentials/docs/blob/main/identity/issuer_registry.md

Reference: https://www.w3.org/TR/did-spec-registries/#the-registration-process https://didproject.azurewebsites.net/docs/registration.html

Public keys sharing:

The verifier requires additional information about the issuer to trust. For example, an issuer can publish information containing the public keys it uses to digitally sign verifiable credentials that it issued.

The verificationMethod that included in the proof property is the identifier of the public key that can verify the signature (URI)

publish /.well-known/did.json without a public key

 

 

Rejected alternatives

 

Requirements:

Application should Store learners DIDs in DB.

As told by DCC member this is a bad practice.
Possible problems may be in case user changes the phone or reinstall the DCC wallet app. User’s DID is correspondent to specific wallet and might be changed over time.

 

Integrate with EDCI, xml protocol widely used in European universities.

XML/XSD model

Signing Credential

Assertion formats comparison:
JWT vs Linked data proofs – ⁣

ZKP solution from MATTR ⁣ – combination of the Linked Data Proofs with BBS+ signatures.

Selected solution: JSON-LD proof (different signing services may provide different signing methods.), rejected: JWT, ZKP, may be considered in the future.

 

 

Integrate sign-and-verify

DCC sign and verify service provides an API implementation for issuing credentials

Possible ways to integrate with Signing Service:

  1. Add independently deployed service to Open edX stack as sign and verify TypeScript REST API service from DCC

  2. Integrate only with other signing platforms as MATTR, Microsoft Entra Verified ID…

  3. Add RPC protocol to open-source JS app (as GRPC)

  4. Implement sign-and-verify library in pure python

Currently, the first and the fourth variants are considered the most likely.

 

  • DCC sign and verify service provides an API implementation for issuing credentials . However, sign-and-verify is a node service.

    The preferred way to integrate with Signing Service is to add independently deployed service to Open edX stack as sign and verify TypeScript REST API service from DCC. Rejected alternatives for integrating with sign-and-verify can be found at the bottom of this page

  • Another possible option is to implement a native python signing service to integrate with.

 

Static system configuration

The MIT library, digitalcredentials provides functionality to work with DCC service and DCC Learners Wallet

For now, it means we would be limited to only one ISSUER per Open edX installation.
DCC issuer registry:

library requires a static setup for the next variables:

Setting

Value

Notes

Setting

Value

Notes

DIGITAL_CREDENTIALS_DEEP_LINK_URL

dcwallet://deep_link

The deep link url to the digital credentials wallet app. This will typically involve a custom url scheme.

DIGITAL_CREDENTIALS_ISSUER_ID

-

The digital credentials issuer id to be included in the credential template. This value is determined by the digital credentials team.

DIGITAL_CREDENTIALS_VERIFICATION_METHOD

-

The digital credentials verification method to be included in the credential template. This value is determined by the digital credentials team.

MITOL_DIGITAL_CREDENTIALS_HMAC_SECRET

-

Any random string, MUST match the corresponding HMAC secret sign-and-verify is deployed with.

MITOL_DIGITAL_CREDENTIALS_VERIFY_SERVICE_BASE_URL

http://sign-and-verify.example.com:5678/

The addressable base url for the sign-and-verify service.

 

ref.

 

sign-and-verify service requires a static configuration for the following variables:

Setting

Value

Notes

Setting

Value

Notes

*AUTH_TYPE

 

the mechanism by which to authorize access to credential (required)
AUTH_TYPE accepts the following values:

  • oidc_token: retrieves email from userinfo endpoint using OIDC token and fetches matching credential

  • vp_challenge: fetches credential with matching VP challenge

*DID_SEED

 

a secret seed used to generate DID document for issuer (required)

OIDC_ISSUER_URL

 

OIDC issuer discovery URL (required)

ISSUER_MEMBERSHIP_REGISTRY_URL

https://digitalcredentials.github.io/issuer-registry/registry.json

location of registry used to confirm issuer's membership status in DCC (required)

DID_WEB_URL

undefined

the url used to generate did:web document and keys for issuer (optional, default: undefined)

PORT

5000

the port the web service will bind to (optional, default: 5000)

DIGEST_CHECK

false

set to true to enable Digest header verification (optional, default: false)

DIGEST_ALGORITHMS

sha256,sha512

a comma-delimited list of acceptable digest algorithms (optional, default: sha256,sha512)

HMAC_SECRET

null

set to the shared HMAC secret to require HMAC signing of the request via the Signature header (optional, default: null)

HMAC_REQUIRED_HEADERS

date,digest

a comma-delimited list of headers that are required to be in the HMAC signature (optional, default: date,digest)

MongoDB connection parameters

 

DB_USER: database client username (optional)

DB_PASS: database client password (optional)

DB_HOST: database client hostname (optional)

DB_NAME: database name (optional)

DB_COLLECTION: database credentials collection name (optional)

ref.

 

 

The issuer module is using provided parameters and generates public/private DID pair on application start-up ( ).

 

QR code library

There are listed other options to generate QR codes in python:

Based on small research, there are two popular libraries that provide QR code generation capabilities: Segno and python-qrcode.

According to comparison, Segno is faster and has no dependencies, unlike python-qrcode, which has a dependency on the Pillow library.

 

Wallets Integrations

To integrate with MATTR application, we need to use MATTR CORE platform as a signer, using REST API and secure DID messaging – ⁣​.

Adding credentials to a digital wallet

Web Wallet:

DCC has no integrations with web-based wallets for now.

https://tykn.tech/web-wallet/,

 

 

Draft Notes:

Q: Does it required to get additional data from SSO IdP about subject?

Relying on authority sso, verifying SSO linked credentials (organization-specific registry and params)

 

Integration with the edX Credentials codebase

VC/OpenBadges3.0/EBSI use case

edX Credentials entity

Comments

VC/OpenBadges3.0/EBSI use case

edX Credentials entity

Comments

Issue a credential

AbstractCredentialIssuer ​

To be extended

List user completions

CredentialViewSet ​

To be extended

Select completions to include in the credential

-

To be created

 

 

 

Repository with source files

https://github.com/raccoongang/verifiable-credentials-design