Credential Verification using QR code

Step by step guide on how to add verification functionality to your web-based business application to enable users to submit their credentials

DICE ID platform provide ability to issue and verify credentials. Once the credentials have been issued to an individual that represents their identity or capability then the user will need a way to present that credential as a proof.

This tutorial is for organizations who want to enable verification functionality in their business app so that the proof provided by the end user can be validated against blockchain and the user's verified data embedded in the proof can be extracted and used further.

The steps required to add verification functionality can be summarized as:

1. Sign up to the DICE ID portal (https://console-uat.diceid.com)

2. Create a Schema from DICE ID portal and issue a credential for testing

3. Get the test credentials in DICE ID app

4. Create a verification template based on that schema from DICE ID portal

5. Download the sample HTML and JavaScript files and replace values in index.html

6. Deploy on web server and open index.html to render the QR code

7. Explore different ways of rendering the QR code based on your application's UI design

8. Scan the QR code using credentials in DICE ID app (from step 2 and 3)

Given below is the detailed step-by-step guide.

1. Sign-up an Sign-in to DICE ID Platform Console

Open https://console-uat.diceid.com/ in your browser and complete the signup and sign-in steps as described in Platform Console

2. Create Sample Schema

After signing up and signing in to DICE ID platform console UI, you can navigate to the Schema screen from the left hand menu.

Click on "Add Schema" and specify the name, version and attributes of the Schema

On clicking "Create Schema" you will get a confirmation and schema will be visible on the next screen.

3. Get Credentials

Navigate to Credentials screen from the left menu and click on "Onboard Customers".

In Onboard Customer screen specify your name and select the Auto Issue credentials option. You will get a screen that requires selection of the Schema based on which credentials need to be created and sent.

Select the Schema created in previous step from the drop down and enter valid values for Name, Email and Phone.

Click OK to save these values and go back to previous screen and specify the email on which the credential invitation should be sent.

On clicking Onboard an email will be sent to the specified email id. To get your sample credentials:

• Download DICE ID app from google play store or apple app store

• Open the app, accept terms and conditions and change the Network in Settings page to DICE ID Testnet

• Scan the QR code received in the email from [e-mail] and wait for processing to complete to obtain the credentials in DICE ID app

4. Create Verification Template

Navigate to the "Verifications Templates" page via the left hand menu

Click on "Add Verification Templates" to open the screen for creating new template in which you need to specify the following:

• Name of the verification template

• Version of the verification template

• Notification Email, which should be your organization's email id on which the verification result needs to be sent.

• Redirect URIs - Enter the fully qualified and valid URLs which needs to be whitelisted so that the verification flow can be redirected and results be rendered. E.g. http://localhost:3000/verification-callback.html

• CORS List - one or more URLs which point to the server and port on which the callback html is hosted e.g. http://localhost:3000

Select a schema from the drop-down in which either global schemas created by other organizations can be selected or your organization's schema can be selected. The schema attributes get pre-selected for the verification template. On clicking "Create Verification Template" button at the end of the page the template gets created.

The name of the attributes in Schema and Verification Template should match always. The Verification template can contain a subset of the attributes in Schema.

If data type of any of the schema attributes is "number" then you can use a predicate so that the actual attribute value does not get revealed. For e.g. if you have Age as an attribute then a condition of Age > 18 can be used as per the use case.

Navigate to the detailed screen of the Verification template you created and copy VCAuth Endpoint, Client ID and Config ID as shown in example below.

Verification Link is a ready-to-user URL which provide the verification QR code corresponding to this verification template. This link can be shared on your website as-is so that your users / customers can scan and submit matching credentials as proof. The verification result will be emailed to your "Notification Email" setup for this template.

5. Download QR code HTML files

Use git clone https://github.com/diceid/qrcode-verification.git or download the two HTML files and one Javascript file available in the repository.

Modify index.html to replace the Client ID and Config ID values copied in previous step as specified below

//Replace the following values in index.html
          'AUTH_BASE_URL': '<VCAuth Endpoint>',
          'VCAUTH_CLIENT_ID': '<Client ID>',
          'WEBAPP_URL': 'http://localhost:3000/',
          'VCAUTH_CONFIG_ID': '75559037-306c-4b08-b4d4-8ee03c3e9895',
          'REDIRECT_URI': 'http://localhost:3000/verification-callback.html'

// Example after replacing the values
          'AUTH_BASE_URL': 'https://console-api-dev.diceid.com/v1/oidc',
          'VCAUTH_CLIENT_ID': '1cefd7e9-3f11-4028-acf8-0a5d1a9fe7d0',
          'WEBAPP_URL': 'http://localhost:3000/',
          'VCAUTH_CONFIG_ID': '75559037-306c-4b08-b4d4-8ee03c3e9895',
          'REDIRECT_URI': 'http://localhost:3000/verification-callback.html'

WEBAPP_URL will be the url on which you are hosting your webserver and will deploy index.html and verification-callback.html on. If you are testing on a web server running on your machine then https://localhost:<port-number> can be used, with your port number

The values in WEBAPP_URL should match the value specified in CORS list of the verification template. And index.html and verification-callback.html should be hosted on the same web server. For actual implementation the name of the callback file can be changed as per need.

REDIRECT_URI will be the url on which you can view the QR code generated. This QR code can be used for scanning and verifying the presented credentials. The value of the url can be tweaked as per requirements. Segments can be added to the url. You can add segments to it e.g. http://localhost:3000/{segment1}/{segment2}/verification-callback.html

// Example after replacing the values 
        'AUTH_BASE_URL': 'https://console-api-dev.diceid.com/v1/oidc', 
        'VCAUTH_CLIENT_ID': '1cefd7e9-3f11-4028-acf8-0a5d1a9fe7d0', 
        'WEBAPP_URL': 'http://localhost:3000/', 
        'VCAUTH_CONFIG_ID': '75559037-306c-4b08-b4d4-8ee03c3e9895', 
        'REDIRECT_URI': 'http://localhost:3000/segment1/segment2/verification-callback.html'

6. Deploy the QR code HTML on web server

Ensure that index.html, verification-callback.html and DiceIdVerification.js are all in the same directory when deploying on the web server.

After the web server is running, open index.html in browser and QR code should get displayed

Instead of QR code if you see the following message then it means that the Redirect URL provided in step 5 is not correct.

{"status":"Failure","message":"Invalid Redirect uri supplied"}

And if you see the message "Forbidden" that means that your server and port are not specified in the CORS list in step 5.

7. Different ways QR code can be launched

QR code can be launched in different ways and this can be adjusted. A user needs to copy the below mentioned line of code in the index.html file to get the QR code displayed in preferred way.

const listener = (evt) => { 
          console.log(JSON.stringify(evt.data));
          switch (evt.data.type) {
            case 'qrReceived': { 
              document.getElementById('myIframe').src = evt.data.data;
              break;
            }
            case 'onLoginTemplate': { 
              document.getElementById('myIframe').style.visibility = 'hidden';
              document.getElementById('scanInsctruction').style.visibility = 'hidden';
              document.getElementById('myIframe').style.height = '0px';
              document.getElementById('backButton').style.visibility = 'visible';
              document.getElementById('successBoxContainer').style.visibility = 'visible';
              var verificationResponse = getUserDataFromToken(evt.data.data.id_token);
              var filteredResponse = filterOutNotToBeListedAttributes(verificationResponse);
              renderResponse(filteredResponse);
              break;
            }
          }
        }

Below are the three ways to display QR code:

a) Same page

For displaying QR code on the same page, user need to

document.getElementById('myIframe').src = evt.data.data;

b) Pop-up

For displaying QR code in a pop-up

window.open(`./QRCodeWindow.html?qrCodeUrl=${evt.data.data}`, "_blank", "left=200,top=200,width=500,height=500");

c) Another tab

For displaying QR code in another tab

window.open(`./QRCodeWindow.html?qrCodeUrl=${evt.data.data}`, "_blank");

8. Scan QR code to test Verification

Open your DICE ID app and scan the QR code for which you will be prompted to submit the proof.

Once submitted the proof will be validated against blockchain and confirmation message will be displayed on the web page. This message is based on the data extracted from JWT token that is generated after the proof is verified and contains the credential data.

Extract and use verified credentials data in your application

Please refer to this code snippet in index.html which extracts the data from JWT token. You can use the same technique and use this data for storing in database or passing it as input to your backend APIs for further processing.

      const getUserDataFromToken = (token) =>{
        const base64Url = token.split('.')[1];
        const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
        const jsonPayload = decodeURIComponent(atob(base64).split('').map(function(c) {
            return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
        }).join(''));
        const userData = JSON.parse(jsonPayload);
        //const filtered = _.omit(userData, attributesNotToBeListed);
        return userData;
      }

Please note that once you are done with development and testing then you should use DICE ID Production environment (https://console.diceid.com) and use those details to go-live and provide verification functionality to your end users