Updated: 4 days ago
Update 26/11/2021 – Microsoft has depreciated the SDK for verifiable credentials. In their own words:
“From October 31, 2021 certain Microsoft Azure AD Verifiable Credential SDK functionality will stop working in Microsoft Authenticator. Applications and services that currently use the Microsoft Azure AD Verifiable Credential SDK should migrate to the Microsoft Request Service REST API”
I will be updating and adding to the blogs over the coming weeks. Rather than simply editing the current blogs, I have decided to add new blogs that show the functionality using the Microsoft Request Service REST API Service. The old blogs I have tagged as using the SDK. I have left them as they could be a useful reference.
In my first blog in the series , I introduced you to Verifiable Credentials (VCs) and Decentralized Identifiers (DIDs). In this blog, I want to show you how you can issue your own VCs using the Microsoft public preview of their Verifiable Credentials (VCs) service. To do this, we will use the Microsoft SDK apps, which are available on GitHub.
The blogs in the series are (No 3 and 5 are coming soon)
Issuing DIDs and VCs with the Microsoft SDK app and Authenticator (This one)
Issuing DIDs and VCs with the Microsoft Request Service REST API - replaces no 2
Issuing your own DIDs & VCs with Azure AD and Microsoft Request Service REST API - replaces no 4
By the end of this blog, you will understand how VCs are issued and verified. Please make sure you are familiar with the first blog before proceeding.
Microsoft has provided a tutorial which you can find here. I am basing this blog on the tutorial but will show you what is really going on.
The Microsoft example app and the Verifiable Claims SDK are written in Node.js. I am pitching this blog at IT Pros and assuming that the reader is a competent IT admin but knows nothing about Node.js or building the development environment. I will not teach you Node.js but will show you how to modify the code samples to better understand what's going on under the hood.
I am assuming you have a reasonable understanding of OpenID Connect and ID Tokens. If you need help in these topics, watch my webinar on "Federated Identity Authentication and Authorization with OpenID Connect and OAuth2.0" or better still come on my identity masterclass https://learn.xtseminars.co.uk/. It would be great to meet you.
Preparing your environment
I recommend you create a Windows 10 VM to host your development environment. This will provide you with a sandbox environment for installing all the tools and development code. The Microsoft documentation for the tutorial is a little sparse when setting up the environment, especially if you are new to GitHub and Node.js. So let me help you. When installing the required apps, choose all the default settings unless otherwise specified below.
Download and install Visual Studio Code from here: https://code.visualstudio.com/Download
Download and install GIT from here: https://gitforwindows.org/
Download and install (see next paragraph) Node.js from here: https://nodejs.org/en/download/
To successfully run the node package manager (npm), you will need Python, and the Visual Studio Build Tools. During the Node.js installation, you can choose the option to install these tools along with Chocolatey. Alternatively, you could install Python, and the Visual Studio Build Tools separately. For the blog, I chose the Chocolatey option.
After installing the tools, sign out and sign in to set the appropriate paths variables.
Git is an open-source version control system. Files can be committed to a repository (storage) and then managed, including rolling back changes to a particular version and cloning. The repository could be local or remote. GitHub is a very popular remote repository where anyone can sign-up and host a public or private repository for free. GitHub is extensively used to make open-source projects publicly available. GitHub makes money through hosting, paid for, full featured private repositories.
Open a command prompt, and you can check the versions of the installed components using:
My version 14.16.1
My version 3.9.4
My version 2.31.1.windows.1
Now we have the tools, we can download the code samples, build the code (automatically installing the necessary modules including the VC SDK) and run the code.
The code will be executed locally on your Windows 10 VM. The authenticator app must be able to connect to the code using HTTPS. The Microsoft sample recommends using Ngrok to act as a reverse proxy providing a public URL through which your code can be accessed.
Download the Ngrok Zip from here: https://ngrok.com/download
Extract it to a suitable location, I placed it here: C:\ngrok
I am going to create a directory structure for running the sample code as follows:
Open a command prompt and switch to the version0 directory, and clone the code from GitHub using:
Examine the cloned code, and you will see an active-directory-verifiable-credentials folder and below that an issuer and a verifier folder. The code samples are run from each of these folders.
We'll leave version0 as a clean copy if we want to refer back to anything once we start making changes. Copy the active-directory-verifiable-credentials folder to the version1 folder.
In the command prompt window, switch to the version1\....\issuer folder and run:
Node Package Manager (NPM) builds the project, integrating external modules, including the Verifiable Credentials SDK. The modules that a project depends on are defined in package.json. When you run npm install, all the packages and their dependencies are added to the node_modules folder.
While the environment is being built, you will see some warning messages which you can ignore.
Now we can run the issuer app. To simplify examining the code and executing the app, let's do this from within VS Code. Open VS Code and using File | open Folder, open the issuer folder: c:\vcs\version1\active-directory-verifiable-credentials\issuer
From the menu bar, use Terminal | New Terminal to open a terminal window. In the terminal window, run the issuer app using:
If prompted by Defender to allow firewall access for Node.js, you do not need to enable it.
You will notice in the VS Code console window it reports: "Example issuer app listening on port 8081!". The example app has created a website and is listening on port 8081. If you want to see it running, you can browse to http://localhost:8081
The website must be available to the Microsoft Authenticator app, and for this, we use Ngrok. Open a new command prompt. Switch to the c:\ngrok directory and execute.
ngrok http 8081
You will see something similar to this:
You can run Ngrok, as an unregistered user, registered user, or paying user. Take a look at https://ngrok.com/pricing for more details.
When using Ngrok with the verifier app, you may receive a message about too many connections.
Use your browser (not your mobile) to connect to the HTTPS endpoint, in my example
You will see:
Click on Get credentials, and a QR code is shown. The Microsoft Authenticator app is used to scan the QR code.
The following steps will tell you all you need to know to add and manage a VC in your user agent (wallet).