Tutorial - Get started with Azure Active Directory Verifiable Credentials using a sample app (preview)
In this tutorial, we go over the steps needed to issue your first verifiable credential: a Verified Credential expert card. You can then use this card to prove to a verifier that you are a verified credential expert, mastered in the art of digital credentialing. Get started with Azure Active Directory Verifiable Credentials by using the Verifiable Credentials sample app to issue your first verifiable credential.
- NodeJS version 10.14 or higher installed on our test system.
- You need GIT installed If you want to clone the repository that hosts the sample app,
- Visual Studio Code
- A system to host our sample site.
- A mobile device with Microsoft Authenticator version 6.2005.3599 or higher installed.
- NGROK free.
Download the sample code
To issue yourself a Verified Credential Expert Card, you need to run a website on your local machine. The website is used to initiate a verifiable credential issuance process. We've provided a simple website, written in NodeJS, that we use throughout this tutorial.
First, download our sample code from GitHub here, or clone the repository to your local machine:
git clone https://github.com/Azure-Samples/active-directory-verifiable-credentials.git
You may want to familiarize yourself with the code in the sample websites. The
issuer folder contains all code used to issue a verifiable credential. More details are available in the sample's readme.
Run the issuer website
You can run the steps from within Visual Studio Code or any command line available in your operating system.
Navigate to the
Once there we need to install all required packages and start the site.
npm install node app.js
In the terminal, you will now see that your issuer app is listening on port 8081. Now let's set up a reverse proxy with Ngrok so Authenticator can communicate with your app.
Creating a reverse proxy with Ngrok
When you run the sample website, your device needs to communicate with the Node server running on your local machine. We recommend using ngrok as an easy way to make your local development server available over the internet.
After you download and extract ngrok, we need to run:
ngrok http 8081
By default the sample website runs on port
8081. Ngrok outputs two forwarding URLs for your server. Copy the URL with the
If you are using PowerShell you may need to type
./ngrok for the command to be recognized.
Now that your local port is exposed to the internet using ngrok, the sample site automatically uses the host name generated by ngrok. Open your browser and navigate to the ngrok https forwarding URL. You should be able to successfully visit the sample site's homepage. If the page opens, your device can communicate with the sample app running on your local server. You're now ready to issue yourself a verified credential expert card.
Issue a credential
Install Authenticator on your mobile device. Microsoft Authenticator is used to receive, store, and present your verifiable credentials to interested parties.
Next, issue yourself a verifiable credential. Click the Get Credential button. When you click the Get Credential button, the sample website displays a QR code, that you can be scan using Authenticator. If you view the site from the browser on your mobile device, clicking the Get Credential button triggers a deep link that opens the authenticator app and does not require the scanning of a QR code.
Scan the website's QR code using Authenticator, or if you are accessing the website via a mobile click the Get credential button to trigger the deep link.
Notice that the Add button is greyed out at this time. Choose Sign in to your account below the card image.
Before you get your Credential expert card, the tenant we are using requires that you provide authentication information. If this is your first time going through tutorial you don't have a credential expert account, create a new user account in our B2C tenant.
After you are signed in, the Add button is no longer greyed out. Choose Add to accept your new VC.
Congratulations! You now have a verified credential expert VC.
Next, it is time to verify your credential.
Now that you have completed the issuance portion of the tutorial and you have a verifiable credential in Authenticator, it is time to validate it in your own verifier app.
Stop running your issuer ngrok service.
In another terminal window, open the Verifier app folder and run it similarly to how we ran the issuer app.
cd verifier npm install node app.js
Now run ngrok with the verifier port 8082.
ngrok http 8082
Open the ngrok https forwarding url in your browser and tap on the VERIFY CREDENTIAL button.
Open Authenticator and scan the QR code.
On iOS, it is the top right and on Android it is the bottom right. Scan the QR code.
Choose Allow on the new permission request screen in Authenticator. By pressing allow, you are signing a verifiable presentation with your DID (Decentralized Identifier) to prove you in fact control this Verifiable Credential.
After a successful presentation three things should have been updated:
- The webpage should now display "Congratulations, Your name" + is a Verified Credential Expert!".
- Your verifier app terminal should also display the same message from the logs.
- In Authenticator, there should be an entry for recent activity of this presentation.
While running the verifier app, ngrok may stop working and display an error that there are too many connections. We've found this can be avoided by registering your account with ngrok.
Now that you have successfully completed the quick start guide, it's time to create your own Decentralized identifier in the Azure AD verifiable credentials service and issue your own verifiable credential.