developers

Verifiable Credentials with Auth0 and MATTR

How to issue Verifiable Credentials from Auth0 user data using MATTR's Auth0 Marketplace Integration

Damian Schenkelman

VP R&D (Auth0Lab)

Jun 16, 2021 • 29 min read

TL;DR: This blog post illustrates how to implement verifiable credentials using MATTR's Auth0 Marketplace integration. Our example features a fictitious university that issues digital credentials for students to use at various retail and hospitality locations—the university benefits by reducing the cost to produce and maintain physical ID cards. Students minimize PII (personally identifiable information) exposure with third-party organizations and the university (i.e., where their credentials are presented).

The Target Scenario

ACME University, a (fictitious) prestigious educational institution, has been an Auth0 customer since late 2016. ACME uses Auth0 to store data about all its students and faculty and allow them to access many university applications. This includes the website that students use to enroll in courses at the beginning of the semester and the mobile app faculty.

image1

ACME University has been issuing physical student cards since the 1980s so campus security can grant access to buildings and restricted parts of campus. Over the years, due to the university's strong community presence, many local retail outlets started accepting student cards to prove someone is a university student and give discounts. For example, some local coffee shops and bars offer discounts to university students but require a student card to get the deal.

But not all places that offer student discounts are retail outlets. Many medical facilities offer discounts to university students, especially for doctor and therapist visits.

After conducting research about student access to technology, the university decided to phase out physical cards by the end of 2023 and instead issue Digital Student Credentials. ACME University believes this will help achieve the following benefits:

  • Reduce costs - eliminate the need to print physical copies.
  • Improve security - Digitally verifiable and expirable credentials reduce the possibility of being able to use fake or stolen physical credentials.
  • Improve branding - The university believes students will prefer Digital Student Credentials as it modernizes campus life.

The team leading the effort has come up with the following requirements:

  1. The university wants to issue Digital Student Credentials to its students, who will store those credentials on their phones. The Digital Student Credentials will be issued with student data stored in Auth0 and will contain:
    a. First, middle and last name(s).
    b. Date of birth
    c. Degrees they are pursuing.
    d. Picture
    e. Date student began studying at the university.
    f. Issuance date
  2. Digital Student Credentials should no longer be valid when students are no longer enrolled at the university, for whatever reason (e.g., graduation, transfer, etc.).
  3. As is the case today, students should be able to present the Digital Student Credential when physically present at various retail outlets and other establishments, but also when using a website or mobile application.
  4. These establishments want to ensure Digital Student Credentials are valid. For example, access to papers on certain academic platforms might be allowed only if someone is an ACME University student. Physical credentials typically have markings (seals, barcodes, etc.) for whoever looks at them to verify that the appropriate entity issued the credential. A similar mechanism should be available to verify these Digital Student Credentials are issued by ACME University.
  5. The university should not know where or when students present Digital Student Credentials. For example, a student's medical situation should be kept private from the university.
  6. As new shops and establishments in town are set up, Digital Student Credentials should not need to be reissued. For example, if a new coffee place opens in town, then all existing Digital Student Credentials should be valid.
  7. To protect its students' privacy, the university wants to make it, so students have a choice to present some of the student data in a Digital Student Credential at shops, but not all of it. For example, a coffee shop only is interested in knowing the student is a university student to provide a discount, but not the student's name.
  8. If students lose or have their phone stolen, they should report the fact to the university's IT department so they can mark the Digital Student Credential as invalid and issue a new one.

A Potential Solution

ACME University assessed how to implement the requirements just using their Auth0 tenant and noticed some shortcomings, for example:

  • Auth0 issues signed assertions (e.g., Open ID Connect (OIDC) ID Tokens) that have an audience. This means the university would know where and when students want to present their digital credentials.
  • While Auth0 allows customization of ID Token claims, in order to present a specific subset of claims, students would need to get a specific ID Token from Auth0 to present at establishments. This means the university's system needs to be up and running for students to present their digital credentials if these credentials were ID Tokens.

Thanks to Auth0 Marketplace, the university found a potential solution using MATTR's integration with Auth0: MATTR's OIDC Bridge and MATTR's mobile Wallet app.

The MATTR OIDC Bridge allows ACME University to issue digitally signed credentials based on Auth0 user data and binding those credentials to a specific phone.

Students store physical credentials like their driver's license or physical student cards in their physical wallets. Whenever they are at an establishment that requests them, they take them out of their wallet. The MATTR mobile Wallet app performs the same functions but in the digital world. It stores these Digital Student Credentials in student's phones and can present the Digital Student Credentials (or a subset of their data) at shops and other establishments.

image Relation between the different solution components

This solution means that in addition to having an Auth0 subscription, ACME University would need to get a MATTR subscription with support for the OIDC Bridge.

The Flows

Let's go through the three major flows from the previous picture in more detail:

  1. Issuing student credentials as the university
  2. Requesting credentials from students as an establishment
  3. Presenting credentials (or a subset of its claims) as a student

Issuing student credentials as the University

The university team leading the development of the solution has come up with the following flow:

  1. When a user account is created, the university sends an email to the student. The email will instruct the student to download the MATTR wallet app from the app store and will include:
    a. A QR code to be scanned with their phone in case the user is opening the email on another device (e.g., a laptop)
    b. A deep-link in case the user is opening the email on their phone
Note:

Because the deep-link/QR code is the same for all ACME students (there is no unique link per student to accept the credential), the university can also hang banners on campus with the QR code for students to scan with their phones.

  1. The student downloads the MATTR wallet app from the app store.
  2. The student either clicks the link from the email or scans the QR code with the MATTR wallet app.
  3. The MATTR wallet app prompts the student to accept the credential.
    Credential offerCredential offer details

    Credential offer

    Credential offer details


  4. (Not visible to students) The MATTR Wallet app creates a Subject ID for the student and associates a public/private key pair to it, and stores the private key on the student's phone. The MATTR Wallet app initiates a transaction to receive a Digital Student Credential and ensures the credential is issued with the Subject ID it just created.
  5. The MATTR Wallet app redirects the user to the ACME University login (hosted by Auth0) using the phone's browser.
    Browser confirmationAuth0 hosted login page

    Browser confirmation

    Auth0 hosted login page


  6. The student authenticates using the mechanism defined by ACME University admins. In this case, aiming for an easy-to-follow example, they enter their username and password.
  7. (Not visible to students) Auth0 issues an ID Token and sends it to the MATTR OIDC Bridge.
  8. (This is not visible to students) The MATTR OIDC Bridge receives the ID token and issues (signs) a credential with the student's claims, and sends it to the wallet app.
    a. The Digital Student Credential is signed using ACME University's private key (it can then be verified using the public key) and includes ACME University's ID as the issuer.
    b. The Digital Student Credential specifies that the Subject ID is the one created in step #5. This means that in the future, the private key stored in the phone can be used to prove the student is the rightful holder of the Digital Student Credential.
  9. The MATTR wallet app stores the Digital Student Credential on the phone.
MATTR wallet logCredential detailsCredential list

MATTR wallet log

Credential details

Credential list


Note:

At the time of writing, MATTR offers a mobile application for both iOS and Android. The MATTR team has future plans to create a wallet SDK so their customers can embed the wallet in other applications or build a version with their own brand.

The following sequence diagram depicts the previous flow with more detail:

Flow Diagram

Requesting credentials from students and presenting credentials as students

When a student wants to buy coffee from a coffee shop through the shop's mobile app, they can specify that they are ACME University students to get a discount. The app will then request proof and validate it.

We need a mechanism for the coffee shop app to request a Digital Student Credential (or a subset of its claims) from the MATTR Wallet App. We will call this mechanism a Presentation Request. A Presentation Request needs to convey "the coffee shop is asking for proof that you are an ACME University student."

We say "Presentation Request" and not a "Credential Request" because the coffee shop does not need all data from the student's credential, like the student's name. Instead, the coffee shop is just interested in knowing that the phone's holder is an ACME University student. The MATTR Wallet App needs to be able to take the original Digital Student Credential and issue a "derived assertion" that only shares the data requested by the Coffee Shop. We'll call this derived assertion a "Verifiable Presentation". It is "verifiable" because the coffee shop will be able to cryptographically verify that it was actually issued from a Student Credential issued by ACME University.

This section describes how that could be done in the ACME University solution:

  1. Student opens the coffee shop mobile app.
  2. Students start an order in the app: they pick the product(s), select the shop where they want to pick up the coffee from, and specify they are a university student through a "discounts dropdown", and confirm their order.
  3. (Not visible to students) The coffee shop mobile app calls the coffee shop web server, which:
    a. Creates a pending order in the coffee shop web server
    b. Creates a presentation request. The coffee shop Web Server should create the Presentation Request with a unique identifier (e.g., a UUID).
    c. Associates the Presentation Request to the order using their unique identifiers. We do this so that when the Verifiable Presentation is presented and verified, the web server knows which order to approve.
    d. Returns the presentation request to the coffee shop app.
  4. Using a deep link, the app brings the MATTR wallet app to the foreground.
  5. The MATTR wallet app asks the student if they want to present proof that they are an ACME University student. In this case, only the student's ID will be shared as no other claims are required.
Presentation Request PromptPresentation Request DetailsPrivacy enhancing credential help

Presentation Request Prompt

Presentation Request Details

Privacy enhancing credential help


Note:

At the time of writing, there is no way to avoid the MATTR wallet app from sharing the subject ID from the Student Digital Credential or using a pseudonymous ID for the presentation.

  1. (Not visible to Students) The MATTR wallet app creates a Verifiable Presentation from the credential, including only the student's ID, and sends it to the coffee shop web server. The Verifiable Presentation preserves the ability to prove ACME university is the issuer and also prove that the Presentation was created by the original Digital Student Credential student's phone.
  2. (Not visible to Students) The coffee shop's web server verifies the Verifiable Presentation.
  3. The coffee shop's web server sends a push notification to the student's phone confirming the order with an "order number".
  4. The student goes to the shop and hears their "order number" called out.
  5. The student picks up their coffee cup (has their "order number" on it).

Flow Diagram

Let's review some of the details of what is going on in Callout 1: VP Issuance and Callout 2: VP Verification.

Callout 1: VP Issuance

Issuing a Verifiable Presentation from a Digital Student Credential on the phone with the MATTR Wallet App involves:

  1. Interpreting the Presentation Request from the coffee shop and picking the claims to present from the Digital Student Credential and their proof. In this case, the claims are the student's Subject ID, the ACME University ID, and the credential's revocation claim (more details that ahead the Revocation lists section).
  2. Using the Student's private key on their phone to sign the Verifiable Presentation. This signature will be used to prove that the student's phone actually created the Verifiable Presentation. The student's private key was stored on the Student's phone by the MATTR Wallet App in step #5 of the Issuing student credentials as the University section.
  3. Using the coffee shop Web Server Public Key to encrypt the signed Verifiable Presentation. The Presentation Request includes the necessary information for the MATTR Wallet App to fetch the coffee shop web Server's Public Key.
  4. Sending the encrypted, signed Verifiable Presentation to the coffee shop web server.

Callout 2: VP Verification

Verifying a Verifiable Presentation issued from a Student Digital Credential involves:

  1. Decrypting the Verifiable Presentation with the coffee shop web server's private key. It was encrypted in step #3 of Callout 1: VP Issuance.
  2. Verifying that the Verifiable Presentation was signed by the Student, using the student's public key. The student's Subject ID in the Verifiable Presentation includes the necessary information for the coffee shop web server to fetch the subject's public key.
  3. Verify that the original Digital Student Credential (used to generate the Verifiable Presentation) was issued by ACME University. The ACME University ID in the Verifiable Presentation includes the necessary information for the coffee Shop Web Server to fetch ACME University's Public Key.
  4. Verifying the credential was not revoked. The Verifiable Presentation includes the necessary information for the coffee shop web server to fetch a credential revocation list from ACME MATTR Tenant. Each revocation list contains revocation status from over 130000 student credentials, and the coffee shop web server only needs to verify the original Digital Student Credential belonging to the specific student in question was not revoked.
Note:

We go a bit deeper into the details for Callout #1 and #2 in the Implementation Details section.



How Are Requirements Satisfied?

Let's go over the requirements one by one to see how they are satisfied:

Requirement

How it's satisfied

  1. The University wants to issue Digital Student Credentials to its students, who will store those credentials on their phone. The Digital Student Credentials will be issued with student data stored in Auth0 and will contain:

  1. First, middle and last name(s).
  2. Date of birth
  3. Degrees they are pursuing
  4. Picture
  5. Date student began studying at University
  6. Issuance date

Students can get a Digital Student Credentials and store it on their phone using the MATTR wallet app.

  1. Digital Student Credentials should no longer be valid when students are no longer enrolled at the university, for whatever reason (e.g. graduation, transfer, etc.).

When the IT department marks a student as graduated and/or transferred, the University's software needs to call the MATTR API to mark a Digital Student Credential as revoked.


Establishments' systems, such as the coffee shop's, need to check if the Digital Student Credential is not revoked when validating it (or Verifiable Presentations). This happens in step #7 in the Requesting credentials from students and presenting credentials as students section.

  1. As is the case today, students should be able to present the Digital Student Credential when physically present at various retail outlets and other establishments, but also when using a website or mobile application.

Digital Student Credentials

are digital and stored on student's phones through the MATTR Wallet app. 


The MATTR Wallet app can present Digital Student Credentials after receiving a presentation request.


Presentation Requests can be initiated by either scanning a QR code at a retail store, clicking on a link on the student's phone or through a push notification deep link.

  1. These establishments want to ensure Digital Student Credentials are valid. For example, access to papers on certain academic platforms might be allowed only if someone is an ACME University student. Physical credentials typically have markings (seals, barcodes, etc.) for whoever looks at them to verify that the appropriate entity issued the credential. A similar mechanism should be available to verify these Digital Student Credentials are issued by ACME University.

Digital Student Credentials

are cryptographically signed using ACME's University private key. Establishments need to explicitly trust the university's public key, and will use that key to verify the credential was actually issued by ACME University.


Digital Student Credentials

are also bound to the student's phone. This means that if the Digital Student Credential is stolen by a Man in the Middle attack (e.g. somehow intercepting secure communications between the phone and an establishment system), then it will not be possible to present it without the phone.

  1. The university should not know where or when students present Digital Student Credentials. For example, a student's medical situation should be kept private from the university.

Digital Student Credentials

do not specify where they can be presented. They can be presented at any establishment that accepts ACME University Student digital credentials. As new establishments appear, students can automatically present their credentials there without needing to request a new credential from the university and without establishments needing to “phone home” to contact issuers, thereby informing them of how and when credentials are being used.

As we explained in step #7 of section Requesting credentials from students and presenting credentials as students, establishment systems (verifiers) check revocation lists that hold revocation status for 130,000 credentials. This makes it impossible for the University (or MATTR) to know where and/or how a credential was presented.

  1. As new shops and establishments in town are set up, Digital Student Credentials should not need to be reissued. For example, if a new coffee place opens in town then all existing Digital Student Credentials should be valid.

Digital Student Credentials

do not specify where they can be presented. Because the credentials are based on the implementation of open standards via Auth0, they can be presented at any establishment that accepts ACME University Digital Student Credentials. As new establishments appear, students can continue to present their existing Digital Student Credential there without needing to request a new Digital Student Credential from the university.

  1. To protect its students' privacy, the university wants to make it so students have a choice to present some of the student data in a Digital Student Credential at shops, but not all of it. For example, a coffee shop only is interested in knowing the student is a university student to provide a discount, but not the student's name.

The coffee shop app can choose to only ask for a subset of the Digital Student Credential's claims. In the aforementioned example, the coffee shop only requested proof the user was a student at ACME university and the student's ID was shared. However, the student's name and birthdate were not shared.

Students get prompted for what data the establishment app requests and can decide whether to present it or not. The MATTR wallet app only shares the approved data with the coffee shop.

  1. If students lose or have their phone stolen, they should report the fact to the university's IT department so they can mark the Digital Student Credential as invalid and issue a new one.

The university's IT department can revoke Digital Student Credentials, by having the university software call the MATTR API to revoke the credential.

Implementation Details

In our scenario, we described Digital Student Credentials as credentials that:

  • Contain a student's (a subject's) information, information about ACME University (the issuer), the type of credential it is (a "student" credential as opposed to a "faculty" credential), information specific to the students and university relationship (e.g., Date student began studying at university).
  • Are digitally signed by ACME University so establishments can verify their authenticity
  • Allow for the creation of Verifiable Presentations from a subset of its attributes.

There's a term in the literature for credentials with those characteristics: Verifiable Credentials. In fact, Verifiable Credentials are so relevant that there is a W3C standard for the definition and standardization of the concept of Verifiable Credentials.

Note:

Verifiable Credentials (and their specification) are a key component in Decentralized Identity. Decentralized Identity is a trust framework that aims to enable secure, privacy-preserving transactions that involve users and their identities.

Physical credentials, like passports or student cards, store data about subjects. They have markings (seals, barcodes, etc.) for whoever looks at them to verify that the appropriate entity issued the credential. Sometimes their markings' format is standardized to make them verifiable globally.

Verifiable Credentials are digital credentials that contain a subject's data and are digitally signed to prove their validity. An example credential for a student card might look like this:

Example Student Card Verifiable Credential

{
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://schema.org"
   ],
   "type": [
     "VerifiableCredential",
     "Student"
   ],
   "issuer": {
     "id": "did:key:zaaaadAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
     "name": "ACME University"
   },
   "issuanceDate": "2021-04-09T20:24:54.876Z",
   "credentialSubject": {
     "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
     "firstName": "Anne",
     "lastName": "Smith",
     "picture": "{base64encodedpicture}",
     "birthDate": "2000-10-07",
     "startDate": "2018-09-01",
     "degrees": [ "Electrical Engineering", "Business Management"],
   },
   "credentialStatus":{
"id":"https://auth0-damian-sandbox.vii.mattr.global/core/v1/revocation-lists/c63b8be9-b71f-4519-b722-8d05c127e099#1",
    "type":"RevocationList2020Status",
    "revocationListIndex":"1",
"revocationListCredential":"https://auth0-damian-sandbox.vii.mattr.global/core/v1/revocation-lists/c63b8be9-b71f-4519-b722-8d05c127e099"
   },
   "proof": {
     "type": "BbsBlsSignature2020 ",
     "created": "2021-04-09T20:24:54.876Z",
     "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..BSHdalZrYml0slwgAXFVF5uAcg2DbPMfwatturKs8TnuxBxylQDnS3JkORORVmO73Ruh7h8KJvVvHO4pE5NsCQ",
     "proofPurpose": "assertionMethod",
     "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
   }}

The previous credential includes:

Note:

From the W3C specification

Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies. In contrast to typical, federated identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID, the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject.



This means ACME University has an identifier (DID), and a related public/private key pair. The private key is used to sign Digital Student Credentials, and the public key can be used by establishments to validate that the Digital Student Credential they get was actually issued by ACME University.

  • subject.id: A way to identify the student, also a DID. In steps 5 and 9b of the Issuing student credentials as the University section, the student Subject ID is a DID.
  • Claims: Data about the student, such as firstName, lastName, etc.
  • proof: Data required to cryptographically prove both that
    • ACME university actually issued the credential
    • Possession of the students' phone (which stores the Student's private key)

Our scenario requires a MATTR tenant with access to the OIDC Bridge to issue credentials from Auth0 issued ID Tokens and the MATTR wallet app. The MATTR wallet app:

  1. Stores Verifiable Credentials and private keys to prove ownership of those credentials
  2. Knows how to interpret presentation requests and can create and present Verifiable Presentations using Zero-Knowledge Proofs.
Note:

Zero-knowledge proofs are a mechanism that allows one party (A) to prove to another party (B) a certain fact without disclosing the fact itself.


In this case, we are cryptographic Zero-knowledge proofs so the wallet (party A) can selectively disclose the claims in a Digital Student Credential to an establishment (party B).


You can learn more about how this works with MATTR in these two videos:


Going back to our Coffee Shop establishment example, this is the Presentation Request the Coffee Shop Web Server would generate to ask for an ACME University Student Credential without asking for any specific claims:

Example Student Card Verifiable Presentation Request

{
  "id": "8289b5d0-6175-4d1c-9b56-8a62e697c948",
  "type": "https://mattr.global/schemas/verifiable-presentation/request/QueryByFrame",
  "from": "did:key:z6MknujgW5MmMCP9GArkWB55QpimbyUovvh2VwUvuZacgacE",
  "created_time": 1619631734369,
  "expires_time": 1635183734369,
  "reply_url": "{URL_THAT_WILL_VERIFY_PRESENTATION}",
  "reply_to": [
    "did:key:z6MknujgW5MmMCP9GArkWB55QpimbyUovvh2VwUvuZacgacE#..."
  ],
  "body": {
    "id": "8aa04062-9863-4d39-baa7-bbea12ca2290",
    "name": "zkp_course_credential_request",
    "domain": "auth0-damian-sandbox.vii.mattr.global",
    "query": [
      {
        "type": "QueryByFrame",
        "credentialQuery": [
          {
            "reason": "Please provide proof you are a student @ ACME University",
            "frame": {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
                "https://w3id.org/vc-revocation-list-2020/v1",
                "https://schema.org"
              ],
              "type":["VerifiableCredential", "Student"],
              "credentialSubject": {
                "@explicit": true
              }
            },
            "trustedIssuer": [
              {
                "issuer": "did:key:zUC74bmTisfo4ijagZEgMQhpj9Ewmx1ezJ425L4SYp5NLA4sCL17jyG1RxLv8FEvaCFrPcx5bUvsbgRYDfwXbHiRjH5TtNz9EdRhsrCikytFDs1R11bsh4vTFvgtapwHRYTFCo9",
                "required": true
              }
            ],
            "required": true
          }
        ]
      }
    ],
    "challenge": "GW8FGpP6jhFrl37yQZIM6w"
  }

The presentation request includes:

  • id: The request's unique identifier.
  • from: Aa way to identify the verifier, e.g., the coffee shop web server
  • reply_url: Aa URL where the Verifiable Presentation will be sent for it to be verified.
  • reply_to: A way to specify the key to use to encrypt the Verifiable Presentation to send to the server.
  • body.query: Specifies the type of credential to accept claims from and what claims are required. In this case
    • body.query.credentialQuery.trustedIssuer.issuer is the University's identifier as an issuer.
    • body.query.credentialQuery.type is the type of credential to check for. In this case, a "Student" credential. This is useful because ACME University could issue many types of credentials, such as Alumni credentials and faculty credentials.
    • body.query.credentialQuery.credentialSubject includes no claims, so only subject.id is presented.

The protocol used for Verifiable Presentation requests is not a standard at the time of writing (it is at a group draft stage), but establishments can request and validate presentations from the MATTR wallet without depending on the MATTR platform. The lack of a standard does mean that if establishments are interested in operating with other wallets, they might need to implement support for different protocols, which increases their implementation and maintenance cost and reduces their interoperability.

Trade-offs

So far, we've gone over how to design a solution with Auth0 and MATTR that meets the ACME University team's needs.

This section's goal is to help readers understand the implications of implementing the team's requirements and design as described. For that, we'll compare the approach used for the Digital Student Credentials to the approach used when authenticating to the ACME University Enrollment Web App. As a reminder: the Enrollment Web App used Auth0 without MATTR. When users log in, they use the OIDC protocol.



Digital Student Credentials (Verifiable Credentials)

Enrollment Web App (OIDC)
Digital Student Credentials (Verifiable Credentials)Enrollment Web App (OIDC)

As we will perform some comparisons to just using Auth0 (without MATTR), this section assumes some familiarity with Auth0 and/or OIDC.

Overview

If you look at the contents of the example student Verifiable Credential, you might notice some similarities with an ID Token. An example ID Token issued to ACME University students for their Enrollment Web App could look like this (note that we are showing the decoded JSON payload but leaving the JWT header and signature untouched):

Example ID Token Payload for ACME University Enrollment Web App

{JWT_HEADER}.{
  "iss": "https://auth.acmeuniversity.edu",
  "sub": "auth0|2219939022",
  "aud": "https://insccriptions.acmeuniversity.edu",
  "iat": 1516239022,
  "exp": 1516539022,
  "given_name": "Anne",
  "family_name": "Smith",
  "picture": "{URL}",
  "http://claims.acmeuniversity.edu/birthDate": "2000-10-07",
  "http://claims.acmeuniversity.edu/startDate": "2018-09-01",
  "http://claims.acmeuniversity.edu/degrees": [ "Electrical Engineering", "Business Management"],
}.{JWT_SIGNATURE}

Let's now compare the ID Token and Verifiable Credential side-by-side:

ID Token

{JWT_HEADER}.{
  "iss": "https://auth.acmeuniversity.edu",
  "sub": "auth0|2219939022",
  "aud": "https://insccriptions.acmeuniversity.edu",
  "iat": 1516239022,
  "exp": 1516539022,
  "given_name": "Anne",
  "family_name": "Smith",
  "picture": "{URL}",
  "http://claims.acmeuniversity.edu/birthDate": "2000-10-07",
  "http://claims.acmeuniversity.edu/startDate": "2018-09-01",
  "http://claims.acmeuniversity.edu/degrees": [ "Electrical Engineering", "Business Management"],
}.{JWT_SIGNATURE}

Verifiable Credential

{
 "id": "aaaaaaaa-eb18-11ea-a057-530317397ea3",
 "credential": {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://schema.org"
   ],
   "type": [
     "VerifiableCredential",
     "Student"
   ],
   "issuer": {
     "id": "did:key:zaaaadAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
     "name": "ACME University"
   },
   "issuanceDate": "2021-04-09T20:24:54.876Z",
   "credentialSubject": {
     "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
     "firstName": "Anne",
     "lastName": "Smith",
     "picture": "{base64encodedpicture}",
     "birthDate": "2000-10-07",
     "startDate": "2018-09-01",
     "degrees": [ "Electrical Engineering", "Business Management"],
   },
   "proof": {
     "type": "Ed25519Signature2018",
     "created": "2021-04-09T20:24:54.876Z",
     "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..BSHdalZrYml0slwgAXFVF5uAcg2DbPMfwatturKs8TnuxBxylQDnS3JkORORVmO73Ruh7h8KJvVvHO4pE5NsCQ",
     "proofPurpose": "assertionMethod",
     "verificationMethod": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj#z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj"
   }
 }
}

They both have:

There are some differences, however, between the two that introduce some tradeoffs. It is important to highlight that these tradeoffs are not inherent to Verifiable Credentials but instead inherent to our solution requirements.

No audience

A credential audience (aud) identifies recipients for the credential. The university's design involves issuing credentials that don't have an audience. That allows them to avoid reissuing credentials whenever new partner establishments are created and also prevents the university from knowing where their students will present their credentials.

Note:

Not having an audience also means that if an attacker steals a student's phone and has access to the MATTR wallet app (so that the attacker has access to both the Digital Student Credentials and the student Subject ID private key on the Student's phone), there are no restrictions to where it can be presented.

Revocation lists

Using a revocation list approach for revocation means that when verifying Verifiable Presentations, verifiers have to check if the credential is revoked or not. This could mean an HTTP request on each credential verification. Alternatively, caching could be used to avoid HTTP requests (and their related latency). Cache duration will depend on the delay verifiers are willing to accept to detect credentials as revoked after they have been revoked.

Each student Verifiable Credential has a credentialStatus claim, and its value is an object with the following properties:

credentialStatus Object:

"credentialStatus":{
"id":"https://auth0-damian-sandbox.vii.mattr.global/core/v1/revocation-lists/c63b8be9-b71f-4519-b722-8d05c127e099#1",
    "type":"RevocationList2020Status",
    "revocationListIndex":"1",
"revocationListCredential":"https://auth0-damian-sandbox.vii.mattr.global/core/v1/revocation-lists/c63b8be9-b71f-4519-b722-8d05c127e099"
   },
  • revocationListCredential: The URL from where the revocation list for the credential should be retrieved.
  • revocationListIndex: The revocation list is expressed as a 0-indexed bit array. If the bit at position revocationListIndex is 0, the credential is not revoked; if the bit is 1, the credential is revoked.
  • type: The type of revocation list. In this case, it is a verifiable credential specified under this draft.
  • id: anchors the revocationListIndex within the revocationListCredential URL specified in the w3c draft.

The revocation list includes 130,000 entries, so the University cannot tell which credential an establishment is trying to check revocation for. The revocation list in credentials of type RevocationList2020Status is encoded and compressed following this w3c draft.

An alternative revocation approach could be having the verifier send the credential to the ACME University MATTR tenant to see if it is revoked. That would allow issuers to know where the credential is being presented and still requires an HTTP request. The downside is that ACME University would know where students presented their Verifiable Credentials, which is one thing we are trying to avoid in the requirements.

Conclusion

The goal of this blog post is to help you understand the type of use cases you can address with the MATTR's Auth0 Marketplace integration, how you can issue Verifiable Credentials from Auth0 user data, and how you can store and present those credentials.

If you are interested in learning more, you can check out this video from MATTR that walks you through the steps required to issue Verifiable Credentials with the OIDC Bridge and Auth0.

I would also like to thank Vittorio Bertocci for patiently providing invaluable feedback for writing this article. Thank you!

About Auth0

Auth0 by Okta takes a modern approach to customer identity and enables organizations to provide secure access to any application, for any user. Auth0 is a highly customizable platform that is as simple as development teams want, and as flexible as they need. Safeguarding billions of login transactions each month, Auth0 delivers convenience, privacy, and security so customers can focus on innovation. For more information, visit https://auth0.com.