mDocs remote (online) verification detailed workflow

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 an application on their mobile device.

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 application

The MATTR VII verifier tenant responds with a URI, referred to as the Authorization endpoint in OID4VP. This endpoint is configured as part of the walletProviders array of the MATTR VII tenant verifier configuration, which defines the URI to invoke an application with based on its unique identifier.

As per OID4VP, the Authorization endpoint can be one of the following:

• HTTP link: This URI directly launches a matching application and can be either a Universal link (iOS) or an App link (Android).

  HTTP links are recommended by the OID4VP specification as they are more secure. These URIs are verified against the domain owner before launching the application, as the domain must host an association file declaring the app’s link. This ensures the provider owns both the app and the domain.

  Additionally, it is recommended to host a webpage for this URI to allow the user to continue the interaction if the HTTP link fails to invoke the intended application. For example, the user might not have the application installed and in this case the page should include a link to enable them to download the app.

• Custom URI: This URI prompts the holder’s device to open a dialogue box, allowing them to launch an installed app configured to handle the custom URI. Custom URIs are less secure than HTTP links as they are not domain-verified and can invoke any resource.

  The OID4VP specification defines a default Custom URI (mdoc-openid4vp://) that verifiers can use to accept credentials from any compatible app.

  Another limitation of using a custom URI occurs when a user has multiple applications configured to handle the same URI. On Android devices, users can manually select which application to use to open the URI—assuming they know which application contains the required credential. However, on iOS, the system automatically selects a matching application, preventing the user from choosing a specific one.

The verifier’s website can include a UI element to allow users to select the app they want to use for presenting credentials. Based on this selection, the Verifier Web SDK will identify the application and send the corresponding identifier to the MATTR VII verifier tenant. The tenant will then return the associated URI (Authorization endpoint).

For a live demonstration, see the MATTR Labs Maggie’s grocery demo.

The link is used to invoke a compliant application

The link is used by the Verifier Web SDK to invoke a compliant mobile application based on the workflow type:

• Same-device flow: The link is used to redirect the user to a compliant application on the same device. When using a Custom URI a dialogue box appears on the mobile device, prompting them to launch a matching application (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 mobile application.

The mobile application makes a request to retrieve a request object

The invoked mobile application 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 mobile application 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 mobile application’s request.

The mobile application 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 mobile application 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 mobile application 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’s tenant_url. When using a Custom domain, you must configure a redirect for that path from your custom domain to your MATTR VII verifier tenant.
• 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 mobile application sends an authorization response

Once the user consents to sharing the information, the mobile application 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 mobile application 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:

1. The backend creates a unique challenge when the session is established.
2. The web application passes the unique challenge with the request to start a presentation session.
3. The web application is notified when the MATTR VII tenant had completed verification.
4. The web application passes the session ID to the backend.
5. The backend makes a request to MATTR VII to retrieve the verification results for that session.
6. The MATTR VII tenant responds with the verification result and the unique challenge.
7. 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.