Maybe you are new to verifiable credentials, or maybe you’ve been on the decentralised identity journey with us for many years. Either way if you’ve participated in the previews of Azure Active Directory Verifiable Credentials and more recently with Entra Verified ID you’ll know there are numerous steps to successfully creating, issuing and presenting a verifiable credential. The quicker you can go through the process of debugging Microsoft Entra Verified ID setup and configuration to get to a working solution the better. The key is knowing which configuration maybe incorrect, which element of the configuration and what to do to fix it.
If you’re reading this, hopefully the resources in this post will see you successfully issuing, presenting and using Verified IDs quickly.
Three of the key items once you have the foundation configuration of the service completed are:
- DID Registration and Domain Ownership Verification
- Testing Issuance / Presentation as an Application
- Testing Issuance / Presentation as a Wallet
I cover these in this post and also provide additional troubleshooting resources.
DID Registration and Domain Ownership Verification (DID:Web)
Verifying your DID Web Registration and Domain Ownership may return errors indicating that they cannot be validated. You may be confident that you have created your did-configuration.json and did.json configuration files with their content under a directory named .well-known but it still fails.
After copying the URLs from the Verified ID Registration configuration blade in the Azure Portal and pasting them into a browser to confirm they are present on the URL path in the configuration the next step is to verify TLS is appropriately configured.
The quickest and easiest way to do that is using my DIDSearcher PowerShell Module to verify the domain configuration. There is a chance it may return a TLS error such as “The SSL connection could not be established” as shown below.
Search-DecentralizedIdentifier -Web -FQDN "https://darrenjrobinson.com"
NOTE: There is a DID Resolver in the troubleshooting tool mentioned in the sections further below under the Tools menu if you don’t like my PowerShell Module.
The format for this example would be did:web:darrenjrobinson.com but it won’t give you the more informative SSL message shown in mine below.
In my particular example this error was because I was trying to be tricky and use DNS redirects. This was because my certificate didn’t support my base DNS namespace. Trying the URL in a browser will follow the redirects and you’ll see you configuration.
But this is not acceptable. You’ll need SSL on the root of the namespace you are attempting to use for Verified ID and you will need to add the configuration at the root of the namespace as directed.
In this case I reconfigured my Verified ID credential for a namespace where I had an appropriate SSL Certificate associated.
Microsoft Verified ID Configuration Troubleshooter Tool
Microsoft have recently published a Verified ID configuration troubleshooter tool that acts as a virtual wallet and can be used to test issuing and presenting Verified IDs as both a wallet and application. That is, you can use to verify your QR codes for both issuance and presentation without using the Authenticator App. It also has additional tools as mentioned above under the Tools menu.
Configuring the Verified ID Troubleshooter Virtual Wallet
Start by visiting the troubleshooter tool in your browser. From the Wallet menu give it a name and select New. The Id will be automatically generated. That’s it. Job done.
IMPORTANT
This is for test purposes ONLY.
AND the wallet will only exist for 600 seconds in memory cache. After this time you will need to either set it again or create a new wallet.
Keep this in mind if you’re debugging for more than an hour and you start seeing different errors that what you were previously debugging.
Testing Issuance / Presentation as an Application
The tool is particularly useful if you are debugging Microsoft Entra Verified ID setup and configuration at the early steps of QR Code generation for either issuance or presentation.
Running your app and trying to issue or present a credential may result in an error.
Using the Verified ID Troubleshooter we can look to find where the error is. Paste the contents of your appsettings.json file that contains your TenantId, ClientId, ClientSecret, Issuer and Verifier and select Set Config. Â Â
Look at the output steps to see what was successful and what failed. In this example the credential manifest does not include the Tenant Id. Update the appsettings.json to correct the manifest path to include the Tenant Id, restart your application and try again.
After updating our application configuration and restarting our application we can look to validate it even before trying to test issuing a credential via our app. Step 4 now passes and is looking great after retrieving our VC Issuance configuration. Check the rest of the results to ensure you don’t have any other misconfigurations. The good thing is this tool makes it quite obvious where misconfigurations are.
Now let’s try getting a credential via our app.
We now have the expected QR Code for Issuance.
Testing Issuance / Presentation as a Wallet
Switch to Test Issuance/Presentation as Wallet, copy the QR code image from your Verified ID issuance/presentation application and paste it into the top window and select Process Request.
If all is correct you will see that the QR Code is shown as scanned. Currently the troubleshooter can’t act on your behalf so getting to this point gives you confidence you should have your configuration right if everything you see in the output aligns with your configuration (check for typo’s, claims etc).
Further Troubleshooting Resources
This tool really does make debugging Microsoft Entra Verified ID setup and configuration a lot easier. There is still a chance though you may encounter errors outside the ones I’ve manufactured for this post. A good place to dig deeper is with the API Error codes reference in the GitHub repo.