Learn how to build an application that can present an mDoc via a proximity workflow
Introduction
In this tutorial you will use the mDocs Holder SDKs to build an application that can present a claimed mDoc to a verifier that supports proximity verification as per ISO/IEC 18013-5 .
- The user launches the wallet application and generates a QR code.
- The verifier scans the QR code, connects with the wallet and requests an mDoc for verification.
- The wallet displays matching credentials to the user and asks for consent to share them with the verifier.
- The verifier receives the wallet’s response and verifies the provided credential.
The result will look something like this:
Prerequisites
Before you get started, let’s make sure you have everything you need.
Prior knowledge
-
The verification workflow described in this tutorial is based on the ISO/IEC 18013-5 standard. If you are unfamiliar with this standard, refer to our Docs section for more information:
- What are mDocs?
- What is credential verification?
- Breakdown of the proximity presentation workflow.
-
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
Prerequisite tutorial
- You must complete the Claim a credential tutorial and claim the mDoc provided in the tutorial.
- This application is used as the base for the current tutorial.
Testing devices
As this tutorial implements a proximity presentation workflow, you will need two separate physical devices to test the end-to-end result:
Got everything? Let’s get going!
Tutorial steps
To enable a user to present a stored mDoc to a verifier via a proximity presentation workflow, you will build the following capabilities into your wallet application:
- Create a QR code for the verifier to scan and establish a secure connection.
- Receive and handle a presentation request from the verifier.
- Send a matching mDoc presentation to the verifier.
Step 1: Create a QR code for the verifier to scan
The first capability you need to build is to establish a secure communication channel between the verifier and holder devices. As defined in ISO/IEC 18130-5:2021, a proximity presentation workflow is always initiated by the holder (wallet user), who must create a QR code for the verifier to scan in order to initiate the device engagement phase.
To achieve this, your wallet application needs a UI element for the user to interact with and
trigger device engagement by calling the SDK’s createProximityPresentationSession method.
Step 2: Handle the presentation request
The createProximityPresentationSession function can handle three types of events:
onConnected: When a secure connection is established.onSessionTerminated: When a secure connection is terminated for whatever reason.onRequestReceived: When a presentation request is received from the verifier.
onConnected and onSessionTerminated are optional events and will not be implemented in this
tutorial. You can find more information about these events in the reference documentation for
the
iOS ,
Android
and React
Native
SDKs.
When the SDK receives a presentation request from a verifier, an onRequestReceived event is
triggered. The SDK then checks its credential storage for any credentials that match the information
defined in this request.
The application then needs to:
- Present these matching credentials to the user.
- Present what claims will be shared with the verifier.
- Provide a UI element for the user to consent sharing this information with the verifier.
Step 3: Send a response
The next (and final!) capability you need to build is for the wallet application to send a presentation response upon receiving consent from the user to share information with the verifier.
Once the user provides this consent by selecting the Send Response button, the wallet
application should call the SDK’s sendResponse method to share the selected credentials with the
verifier as a presentation response.
Step 4: Test the application
-
Run the app.
-
Select the Present Credentials button.
-
Use your testing verifier app to scan the presented QR code and send a presentation request.
-
Back on the holder device, select the matching credential to share and select the Send Response button.
You should see a result similar to the following:
As the user selects the credential to share, the verifier app will receive the presentation response, verify any incoming credentials and display the verification results.
Congratulations, you have now completed this tutorial, and should have a working wallet application that can claim an mDoc using an OID4VCI workflow, and present it to a verifier via a proximity presentation workflow.
Summary
You have just used the mDocs Holder SDKs to built an application that can present a claimed mDoc via a proximity presentation workflow as per ISO/IEC 18013-5:2021 .
This was achieved by building the following capabilities into the application:
- Generating a QR code for the verifier to scan and establish a secure communication channel.
- Receive and handle a presentation request from the verifier.
- Display matching credentials to the user and ask for consent to share them with the verifier.
- Send matching credentials to the verifier as a presentation response.
What’s next?
- You can build additional capabilities into your new application:
- Present a claimed mDoc for verification via an online presentation workflow into your new application.
- You can check out the SDKs reference documentation for more details on the available functions and classes: