@mattrglobal/verifier-sdk-web

verifier-sdk-web

Table of Contents

• General
  • Licensing
  • Overview
  • Features
• Getting started
  • How to get access to the MATTR Pi Verifier Web SDK
  • Installation
    • Web project with an existing bundler set up
    • Loading directly from script tag
• Usage
  • Initialize the SDK
  • Prepare a credential query
  • Generate challenge
  • Determine supported presentation flows
  • Define wallet identifiers
  • Configure redirectUri
• Request credentials examples
  • Request credentials with automatic flow selection
  • Request credentials with explicit same-device flow
  • Request credentials with explicit cross-device flow
• Error Handling

General

Licensing

Request or download the MATTR Pi SDK Trial License Agreement and the MATTR Customer Agreement and review these terms carefully.

Overview

The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web applications. It enables secure and efficient verification of mDocs, supporting both same-device and cross-device verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.

Features

• Simple integration into web applications.
• Supports both same-device and cross-device presentation flows.
• Secure handling of mDocs requests and responses.
• Compliant with ISO/IEC DTS 18013-7.

In this SDK mDocs are referred to as Mobile Credentials.

Getting started

How to get access to the MATTR Pi Verifier Web SDK

Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.

Please reach out if you need any assistance.

Installation

Web project with an existing bundler set up

• Install dependencies via yarn:

yarn add @mattrglobal/verifier-sdk-web

• Import the sdk module in your code:

import * as MATTRVerifierSDK from "@mattrglobal/verifier-sdk-web";

MATTRVerifierSDK.initialize(...);

Loading directly from script tag

• Load the following script tag from your web page:

<script src="https://cdn.mattr.global/js/verifier-sdk-web/{VERSION}/verifier-js.production.js"></script>

This script will automatically pick up any SDK patch updates. You can lock your implementation to a specific patch version by replacing 1.0 with the specific version (e.g. https://cdn.mattr.global/js/verifier-sdk-web/1.0.1/verifier-js.production.js).

• Access SDK functions via global MATTRVerifierSDK object.

<script> 
   MATTRVerifierSDK.initialize(...);
</script> 

Usage

The SDK can make a request to create a presentation session with a configured MATTR VII verifier tenant. This requires the following configurations and settings:

• Initialize the SDK with the URL of the MATTR VII tenant that will handle the verification request.
• Prepare a credential query that defines what claims are required for verification.
• Generate a unique challenge for the presentation session.
• Determine what presentation flows are supported in the session.
• Define what wallets can be used to respond to the verification request.
• Configure the URI the user will be redirected to when the verification workflow is completed (only required for same-device flows).

Initialize the SDK

You must initialize the SDK before you can use any of its functions and methods:

MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });

• apiBaseUrl (required): URL of the MATTR VII verifier tenant.
• applicationId (required): Unique identifier of the verifier application. This must match the id parameter in the response returned when creating a Verifier application configuration on the MATTR VII verifier tenant.

Prepare a credential query

The following example credential query will request the given_name, family_name, birth_date and portrait claims from a mobile credential profile with org.iso.18013.5.1.mDL as a docType:

const credentialQuery = [
  {
    "profile": "mobile",
    "docType": "org.iso.18013.5.1.mDL",
    "nameSpaces": {
      "org.iso.18013.5.1": {
        "given_name": {
          "intentToRetain": false
        },
        "family_name": {
          "intentToRetain": false
        },
        "birth_date": {
          "intentToRetain": false
        },
        "portrait": {
          "intentToRetain": false
        },
        "resident_postal_code": {
          "intentToRetain": false
        }
      },
    }
  }
];

• profile: Credential format of the credential that will be verified. Currently only mobile (mDocs) is supported.
• docType: the mDL’s type. Confirm with the certificate issuer for what docType they are issuing. Some common examples include:
  • Mobile Driver License (org.iso.18013.5.1.mDL).
  • PhotoID (org.iso.23220.photoid.1).
  • Mobile Vehicle Registration Card (org.iso.7367.1.mVRC).
  • Health certificate (org.micov.vtr.1).
• nameSpaces: Each namespace corresponds to a group of claims included in the credential. These can be claims that are part of a specific standard, jurisdiction or any other reference. The namespace would usually correspond to the requested docType.
  • intentToRetain (Optional): When set to true, the holder will be indicated that the verifier intends to retain this claim beyond the verification workflow. Defaults to false when not specified.

The API supports including multiple query objects in the credentialQuery array in a single request. For simplicity, this example only includes a single query object.

In this example the credentialQuery query will request for the birthdate, portrait and resident_postal_code claims from any credentials whose profile is mobile and docType is org.iso.18013.5.1.mDL.

It also sets intentToRetain as false for all claims, indicating to the holder that the verifier will not retain any of these claims.

While intentToRetain defaults to false, it is explicitly set to false in the example above for clarity purposes. If there is no intention to retain a claim, it is sufficient to simply exclude intentToRetain from the query.

Generate challenge

The Verifier Web SDK passes a unique challenge to the MATTR VII verifier tenant with every request to create a new presentation session. The purpose of the challenge is to ensure the security and integrity of the credential verification process by preventing replay attacks and verifying the authenticity of each request and response. You can either:

• Generate this challenge by your backend and pass it to the SDK.
• Generate it using the SDK built-in method.

When the challenge is generated by your backend, you should use it to validate the verification results received from the MATTR VII verifier tenant.

Determine supported presentation flows

The same-device flow involves the user completing all steps on a single device, such as their smartphone. They initiate the credential request on the verifier's web app, are redirected to their wallet app to consent and present credentials, and then return to the verifier's web app with the results.

In contrast, the cross-device flow starts on one device, like a laptop. When the user initiates the request, the web app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to present matching credentials, and the results are sent back to the verifier's web app.

The main difference is that the same-device flow uses only one device for the entire process, while the cross-device flow uses two devices for added flexibility.

By default, the Verifier Web SDK automatically selects a flow based on the browser's user agent:

• Same-device flows are used when the agent is a mobile device.
• Cross-device flows are used in all other cases.

This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the examples below.

Define wallet identifiers

You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier defined by the SDK in the credential request must match one of the identifiers defined in the walletProviders array of the MATTR VII tenant's verifier configuration.

• If an identifier is provided and matches the id of one of the objects in the walletProviders array, the verifier tenant will invoke that specific wallet using its corresponding authorizationEndpoint.
• If an identifier is provided and does not match the id of any of the objects in the walletProviders array, the request will fail.
• If an identifier is not provided, the verifier tenant will use mdoc-openid4vp:// (default OID4VP scheme) to invoke any wallet.

Configure redirectUri

When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of the values defined in the redirectUris array in the MATTR VII tenant's verifier configuration.

Request credentials examples

Request credentials with automatic flow selection

MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId }); // Initialize the SDK
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery], // Define what credential query to use
  challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
  openid4vpConfiguration: {
      walletProviderId, // Define the wallet identifier
      redirectUri, // Define the redirect URI (not required for cross-device only requests)
  }
});

if (result.isErr()) {
  console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
} else {
  console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
}

• apiBaseUrl : Replace with the tenant_url of your MATTR VII verifier tenant.
• credentialQuery: The credential query to be used in the request.
• challenge: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge generated by your backend system.
• walletProviderId: Replace with a wallet identifier that matches one of the values in the walletProviders array of the MATTR VII tenant's verifier configuration.
• mode: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to undefined in the example for clarity).
• redirectUri Replace with a URI that matches one of the values in the redirectUris array in the MATTR VII tenant's verifier application configuration.

Request credentials with explicit same-device flow

MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  openid4vpConfiguration: {
      redirectUri,
      walletProviderId,
      mode: "sameDevice",
  }
});

// result can be retrieved on redirect uri page. for example
window.addEventListener("load", async () => {
  MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
  const result = await MATTRVerifierSDK.handleRedirectCallback();
});

• mode: When set to sameDevice, the SDK will only support same-device flow in this verification workflow.
• Note that in this case you must define a redirectUri.
• This example shows how you can redirect the user to page that will retrieve and display the verification results.

Request credentials with explicit cross-device flow

MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  openid4vpConfiguration: {
      walletProviderId,
      mode: "crossDevice",
  }
});

if (result.isErr()) {
  console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
} else {
  console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
}

• mode: When set to crossDevice, the SDK will only support cross-device flow in this verification workflow.
• Note that in this case you must define how to handle verification completion and failure.

Error Handling

The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks provide detailed error information to help diagnose and remedy issues.