Skip to Content
GuidesTutorialsClaim a credential

Learn how to build an application that can claim an mDoc via OID4VCI

Introduction

In this tutorial you will use the mDocs Holder SDKs to build an application that can claim an mDoc issued via an OID4VCI Authorization Code flow :

OID4VCI Authorization Code Tutorial Workflow

  1. The user launches the application and scans a QR code received from an issuer.
  2. The application displays what credential is being offered to the user and by what issuer.
  3. The user agrees to claiming the offered credential.
  4. The user is redirected to complete authentication.
  5. Upon successful authentication, the credential is issued to the user’s application, where they can now store, view and present it.

The result will look something like this:

Prerequisites

Before you get started, let’s make sure you have everything you need.

Prior knowledge

  • The issuance workflow described in this tutorial is based on the OID4VCI  specification. If you are unfamiliar with this specification, refer to our Docs section for more information:

  • We assume you have experience developing applications in the relevant programming languages and frameworks (Swift for iOS, Kotlin for Android and TypeScript for React Native).

If you need to get a holding solution up and running quickly with minimal development resources and in-house domain expertise, talk to us  about our white-label MATTR GO Hold app  which might be a good fit for you.

Assets

Development environment

Testing device

Got everything? Let’s get going!

Environment setup

Perform the following steps to setup and configure your development environment:

Nice work, your application is now all set to begin using the SDK!

Claiming a credential

In this part of the tutorial you will build the capabilities for an application user to interact with an OID4VCI Authorization Code flow credential offer and claim an mDoc.

To achieve this, you will break this capability down into the following steps:

  1. Initialize the SDK.
  2. Interact with a Credential offer.
  3. Retrieve offer details and present them to the Holder.
  4. Obtain user consent and initiate Credential issuance.

Step 1: Initialize the SDK

Step 2: Interact with a Credential offer

Interact with Credential offer

Users can receive OID4VCI Credential offers as deep-links or QR codes. In this tutorial you will use the following QR code, which is a MATTR Labs example of an OID4VCI Credential offer:

QR Code

Creating your own Credential offer is not within the scope of the current tutorial. You can follow the OID4VCI guide that will walk you through creating one.

Your application needs to let users interact with Credential offers. Since this tutorial uses a QR code to deliver the offer, your application must be able to scan and process QR codes.

Step 3: Retrieve offer details and present them to the user

Present offer details

Next, you’ll add the ability to display the details of the Credential offer to the user before they decide to claim any credentials. This process, known as credential discovery, allows your wallet application to retrieve and present the offer details, including:

  • What Issuer is offering the credentials?
  • What credentials are being offered, in what format and what claims do they include?

Present offer details

The next (and final!) step is to build the capability for the user to accept the credential offer. This should then trigger issuing the credential and storing it in the application storage.

Let’s test the end-to-end flow of claiming a credential using the application you had just built.

Step 5: Test the application

  1. Run the application.
  2. Select the Scan Credential Offer button.
  3. Scan the following QR code:
QR Code
  1. Select the Consent and retrieve Credential(s) button.

You should see a result similar to the following:

As the user scans the QR code, the wallet retrieves and displays the offer details. The user then provides consent to retrieving the credentials, and the wallet responds by initiating the issuance workflow and displaying the retrieved credentials to the user.

This tutorial uses a demo MATTR Labs Credential offer to issue the credential. This offer uses a workflow that doesn’t actually authenticate the user before issuing a credential, but redirects them to select the credential they wish to issue. In production implementations this must be replaced by a proper Authentication provider to comply with the ISO/IEC 18013-5:2021 standard and the OID4VCI specification.

Credential claimed

Congratulations! Your application can now interact with an OID4VCI Credential offer to claim mDocs!

Summary

You have just used the mDocs Holder SDKs to build an application that can claim an mDoc issued via an OID4VCI  workflow:

OID4VCI Tutorial Workflow

This was achieved by building the following capabilities into the application:

  1. Initialize the SDK so the application can use its functions and classes.
  2. Interact with a Credential offer formatted as a QR code.
  3. Retrieve the offer details and present them to the user.
  4. Obtain user consent and initiate the credential issuance workflow.

What’s next?

Last updated on
TutorialsOnline presentation