@mattrglobal/verifier-sdk-web

verifier-sdk-web

Table of Contents

• Licensing
• Overview
• Features
• Getting started
  • How to get access to the MATTR Pi Verifier Web SDK
  • Installation
    • For web project with an existing bundler set up
    • Loading directly from script tag
• Usage
  • Initialise the SDK
  • Prepare the credential query
  • Select walletProviderId
  • Generate challenge
  • Determine presentation flow
    • Request credentials to support both same device and cross device
    • Request credentials with explicit same device mode
    • Request credentials with explicit cross device mode
• Error Handling

Licensing

Request or download the MATTR Pi SDK Trial Licence 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 Mobile Credentials, 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 credential requests and responses.
• Compliant with ISO/IEC DTS 18013-7.

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

1. Install dependencies via yarn:

yarn add @mattrglobal/verifier-sdk-web

2. Import the sdk module in your code:

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

MATTRVerifierSDK.initialise(...);

Loading directly from script tag

1. Load the following script tag from your web page:

<script src="https://cdn.mattr.global/js/verifier-sdk-web/1.0/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).

2. Access SDK functions via global MATTRVerifierSDK object.

<script> 
   MATTRVerifierSDK.initialise(...);
</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:

• Initialise 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).

Initialise the SDK

You must initialise the SDK before you can use any of its functions and methods.

When initialising the SDK, you must provide the URL of the MATTR VII verifier tenant.

Prepare a credential query

The following example credential query will request the birthdate 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": {
      "birthdate": {
        "intentToRetain": false
      },
      "portrait": {},
      "resident_postal_code": {
        "intentToRetain": false
      }
    },
  }
};

The API supports multiple queries in one request. For simplicity, this example only includes a single 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.

Usage examples

Request credentials with automatic flow selection

MATTRVerifierSDK.initialise({ apiBaseUrl }); // Initialise the SDK
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery], // Define what credential query to use
  challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
  walletProviderId, // Define the wallet identifier
  redirectUri, // Define the redirect URI (not required for cross-device only requests)
  crossDeviceCallback: { // Define how to handle completion/failure of cross-device flows (not required for same-device only requests)
    onComplete: (result) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
    },
    onFailure: (error) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
    },
  },
});

• 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 configuration.
• crossDeviceCallback: Defines how to handle completion (onComplete) or failure (onFailure) of the verification workflow.

Request credentials with explicit same-device flow

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

// result can be retrieved on redirect uri page. for example
window.addEventListener("load", async () => {
  MATTRVerifierSDK.initialise({ apiBaseUrl });
  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.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  walletProviderId,
  mode: "crossDevice",
  crossDeviceCallback: {
    onComplete: (result) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
    },
    onFailure: (error) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
    },
  },
});

• 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.