mDocs remote (online) verification detailed workflow
mDocs are digital credentials based on the ISO/IEC 18013-5 standard and 18013-7 technical specification, designed to be stored on a holder’s mobile device and support either in-person or remote (online) verification workflows.
The purpose of this page is to describe the end-to-end online verification workflow.
Prerequisites
We recommend you make yourself familiar with the following concepts to support your understanding of the implementation described in this page:
- What is Credential verification?
- What are mDocs?
- What are online verification workflows?
Overview
Online verification of mDocs is based on ISO/IEC 18013-7 and OpenID4VP. Let’s use a simple example to illustrate how such a workflow might look like:
-
A relying party uses the Verifier Web SDK to embed an online verification workflow into an existing web application.
For example, a bank embeds online verification as part of the workflow for opening a new bank account on their online portal.
-
When a user interacts with the web application, their digital wallet is invoked to request sharing information held in an mDoc.
In our example, the user attempts to open a new bank account in the bank’s online portal, and is requested to provide a supporting identity document, such as a Mobile Drivers License (mDL).
-
The user uses their digital wallet and consents to sharing the requested information.
In our example, the user has already claimed an mDL as an mDoc into their digital wallet in a previous interaction, and can now share that credential to prove their address.
-
The user’s digital wallet shares the matching mDoc with the MATTR VII tenant configured by the Verifier Web SDK to perform the verification workflow.
-
The MATTR VII tenant performs the required checks and returns the verification results via the Verifier Web SDK to the web application.
-
The user journey continues based on the verification results and the relying party business logic built into the web application.
In our example, pending successful verification of the mDoc, the user can proceed to opening a new bank account.
Detailed workflow
Let’s take a closer look at the end-to-end workflow and explain the role of each component:
The user triggers the workflow
The workflow is triggered when the user interacts with a web application that requires presenting information stored in an mDoc.
For example, the user is attempting to open a bank account and is required to provide a supporting identity document, which can be provided by presenting an mDoc stored in their digital wallet.
In a same-device workflow, the user must begin the interaction in their default web browser.
The Verifier Web SDK starts a presentation-based verification session
The web application uses the Verifier Web SDK to send a request to a MATTR VII verifier tenant to start an online, presentation-based verification session.
This request is based on the Verifier Web SDK configuration that defines:
- The credential query:
- What credentials are required
- What specific claims are required from these credentials
- What MATTR VII tenant to interact with.
On the MATTR VII side, the tenant is configured to determine:
- What domains would it accept requests from.
- What online verification workflows it supports (e.g. same-device and/or cross-device).
The MATTR VII verifier tenant responds with a link to invoke a matching digital wallet
The MATTR VII will respond with a URI to invoke a matching digital wallet. As per OpenID4VP, this can be achieved in one of the following methods:
-
HTTP link: This link directly launches a matching digital wallet app. HTTP links can be either a Universal link (iOS) or an App link (Android).
HTTP links are considered more secure and are also recommended by the OID4VP specification. That is because prior to launching the app, these links are verified against the domain owner. This means that the relying party must own the app and host an association file to declare the app is associated with a specific domain.
It is recommended to host a webpage that corresponds to this HTTP link and enables the user to continue the interaction when the HTTP link has not invoked the wallet. For example, the user might not have the wallet app installed. In this case, the page should include a link to enable them to download the app.
-
Custom URI: This link opens a dialogue box on the holder’s mobile device, prompting them to launch a matching digital wallet app. Unlike HTTP links, custom URIs are not verified against the domain, and can be used to invoke any resource.
These links are created based the tenant verifier configuration that defines:
- What wallet applications can the tenant interact with.
- What Custom URI/HTTP link is used to invoke each wallet.
When no links are configured, the MATTR VII tenant will attempt to invoke any wallet with the
default URI defined by the OID4VP specification (mdoc-openid4vp://
).
The link is used to invoke a compliant digital wallet
The link is used by the Verifier Web SDK to invoke a compliant digital wallet based on the workflow type:
- Same-device flow: The link is used to redirect the user to a compliant wallet application on the same device. When using a Custom URI a dialogue box appears on the mobile device, prompting them to launch a matching digital wallet app (this dialogue box is not displayed for HTTP links).
- Cross-device flow: The link is rendered as a QR code and displayed in an embedded iframe. The user must then use a different mobile device to scan the QR code and invoke a compliant digital wallet.
The wallet makes a request to retrieve a request object
The invoked wallet can now use the link to retrieve the request object from the MATTR VII verifier tenant. This is a presentation request that defines what information is requested by the verifier and for what purpose.
In OAuth 2.0 terminology this is referred to as an Authorization request, made by the MATTR VII verifier tenant which acts as a Client. The request is sent to the wallet which acts as an Authorization server, as it controls access to protected resources, in this case stored credentials.
The MATTR VII tenant returns the request object
The MATTR VII verifier tenant generates the request object, signs it with its verifier certificate and sends it as a response to the wallet’s request.
The wallet will handle the received request object and perform the following:
- Establish trust with the relying party in one of the following methods:
- Certificate trust model: The wallet compares the certificate used to sign the request
object against its list of trusted verifiers. This would be the
certificatePem
element of the MATTR VII Verifier configuration, and must be provided by the verifier to the holder out of band. - Domain trust model: The wallet retrieves the relying party metadata by making a request
to the
/.well-known/oauth-client
endpoint of the domain the request object is coming from. By default this would be the verifier’stenant_url
. When using a Custom domain, you must configure a redirect for that path from your custom domain to your MATTR VII verifier tenant.
- Certificate trust model: The wallet compares the certificate used to sign the request
object against its list of trusted verifiers. This would be the
- Gather credentials matching the information provided in the request object.
- Display this information to the holder and ask for consent to sharing it with the relying party.
The wallet sends an authorization response
Once the user consents to sharing the information, the wallet generates an authorization response,
which includes a signed verifiable presentation of matching credentials contained in a vp_token
parameter. The authorization response is encrypted and sent to the MATTR VII verifier tenant.
Upon receiving the authorization response, the MATTR VII verifier tenant would decrypt it and verify the contained verifiable presentation.
This can include checking whether the certificate used to sign the credential matches an existing Issuer in the MATTR VII tenant trusted issuers list.
The MATTR VII verifier tenant returns the verification results
The MATTR VII tenant returns the verification results based on the verification workflow:
-
Same-device flow: the MATTR VII tenant responds with a redirect URI which is used by the wallet to redirect the user back to continue the interaction with the web application. This redirect opens a new tab in the user’s mobile browser, leaving the original tab (where the interaction began) still open.
- The redirect URI will be handled by the device default web browser. This means that the user must start their journey in their default web browser as well, otherwise it will be recognized as a different session and result in a failure.
- It is recommended to advice users to refrain from starting the workflow in private/incognito mode, as browser limitations might lead to unexpected behavior and possible failures.
-
Cross-device flow: The Verifier Web SDK continuously checks for verification results. Once they are received they are passed to the web application and the cross-device workflow modal is closed.
When the web application has a backend, the MATTR VII verifier tenant can be configured to only send the results to the backend rather than to the frontend directly. This enhances security as described in the following flow:
- The backend creates a unique challenge when the session is established.
- The web application passes the unique challenge with the request to start a presentation session.
- The web application is notified when the MATTR VII tenant had completed verification.
- The web application passes the session ID to the backend.
- The backend makes a request to MATTR VII to retrieve the verification results for that session.
- The MATTR VII tenant responds with the verification result and the unique challenge.
- The backend compares the original and the received challenge to ensure the response can be trusted.
The web application surfaces verification results
The user journey can now proceed based on the web application business logic.
In our example, if the presented mDoc was verified the user can proceed to opening a bank account, whereas if verification failed they will receive an error message.