mDocs online verification

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.

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. MATTR VII tenants can be used to configure these associations when it is used as a backend for a wallet application.

• 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.
• 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 Authorisation request, made by the MATTR VII verifier tenant which acts as a Client. The request is sent to the wallet which acts as an Authorisation 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’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 wallet sends an authorisation response

Once the user consents to sharing the information, the wallet generates an authorisation response, which includes a signed verifiable presentation of matching credentials contained in a vp_token parameter. The authorisation response is encrypted and sent to the MATTR VII verifier tenant.

Upon receiving the authorisation 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 the web application. Note that this link will be opened 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 recognised as a different session and result in a failure.
• 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.