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”
THIS BLOG HAS NOW BEEN REPLACED - left here for reference
Please go to part 1 of the series to see what's changed. Introduction to the future of identity - DIDs & VCs (xtseminars.co.uk)
In blog two of the series, I introduced you to issuing and verifying Verifiable Credentials (VCs) using the Microsoft example apps. This blog will go into more detail and show you how the apps use Azure Key Vault and containers. You will then see how to set up your own Verifiable Credentials service in Azure AD, and issue/verify your own credentials.
The blogs in the series are (No 3 and 5 are coming soon)
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 be issuing and verifying your own VCs. Please make sure you are familiar with the first two blogs before proceeding. I recently held a webinar that covered the majority of blogs 2 & 4. If you would like to see the recording, please go here. https://learn.xtseminars.co.uk/video/verifiable-credentials
Microsoft has provided a tutorial which you can find here https://aka.ms/VC/issue-credential. I am basing this blog on the tutorial but will show you what is really going on.
As my webinar video is available and you can watch the demos, I will only cover the main points in this blog and let it stand as an introduction/summary. Where appropriate, I have referenced the video with the timing for the demo that shows the required steps.
I am assuming you have a reasonable understanding of OpenID Connect and ID Tokens. If you need help with these topics, watch my webinar on "Federated Identity Authentication and Authorization with OpenID Connect and OAuth2.0" https://learn.xtseminars.co.uk/video/watch or better still come on my identity masterclass https://learn.xtseminars.co.uk/. It would be great to meet you.
The example components
The solution's components are the issuer app, the verifier app and the Azure AD VC service. All three components have a DID and an associated private key. Azure Key Vault holds the keys, and container storage is used to store the VC definition files. The following diagram shows a possible configuration for the solution.
The advantage of using Key Vault for the keys is that a message digest can be sent to Key Vault with a request for signing. The signing is done within Key Vault, and the private key is never externally exposed. To gain access to Key Vault, both of the applications require OAuth 2.0 access tokens. Consequently, they will need to be registered as applications with Azure AD. The OAuth 2.0 Client Credential Grant is used to obtain the tokens.
The VC definition files are held in Azure Container storage, and the appropriate Display and Rules files are uploaded when creating a new credential.
To sign in to the Azure AD B2C directory requires an app to be registered that represents the Authenticator. This will allow the Authenticator to receive an ID token after the user has signed in.
To simplify the example apps, Microsoft has used a single DID and Key Vault. This is shown below.
A single app registration is used in Azure AD for both the issuer and verifier apps. Consequently, both apps are using the same client ID and secret. This is fine for a simple demo, but the verifier would have its own DID and Key Vault in a real-world scenario.
Configuring your own VC service
To issue your own VCs, you will need to configure the VC service and create your own VC definitions. To configure the service, you will need an Azure AD tenant with a P2 license and an associated Azure subscription. The need for a P2 license is a temporary requirement and will be dropped.
Configuring the services requires:
A Key Vault
Stores three keys used by the service: Signing, Recovery, and Update keys
Private container storage for the VC definition files
VC Display and Rule definition files
Public container storage for icons displayed on the VC cards in Authenticator
A domain to be linked to the DID generated by the service
In the following diagram, you will see that the only change made to the demo environment is creating the VC service and its associated components in your demo tenant and subscription. There are no changes to the issuer and verifier app configuration.
You can either create the Key Vault and storage in advance or create them while configuring the VC service. The following diagram depicts the permissions required on Key Vault and container storage.
When you create the Key Vault and container storage, you will be the owner of those resources. As the owner, you will automatically have management permissions. Your administrator will need to be granted cryptographic Sign permission on Key Vault and Storage Blob Data Reader on the private storage container.
As you are doing the deployment, the VC service will be automatically provisioned for Get + Sign. The I/V app permissions are just shown for reference and are the permissions required on the Key Vault in the Microsoft environment.
The domain you supply when you configure the service will be linked to the VC service DID. This DID is automatically generated and published on ION.
To configure the VC service, watch my demo from the webinar https://learn.xtseminars.co.uk/video/verifiable-credentials. You can find it a 27:57
Configuring your VC definition files
Now that we have our own VC service, we need to create the appropriate display and rule files for our VC.
The display file controls how the Authenticator displays the card and other data associated with the VC.
In the diagram above, most of the settings are self-explanatory. However, the claims section needs some explanation. Entries under the claims section are for displaying the claim values in the Authenticator. The label is used as the claim's display name and the value taken from the VC vc.credentialsubject.firstname.
Look at the Rules file, and you will see that the source for the claims is an ID Token and the mapping section shows how the claims in the ID Token map to the VC claims. For instance, the given_name in the ID Token maps to "vc.credentialsubject.firstname"
The source of the ID Token is defined using the well know OpenID Connect metadata URL. Via the URL, all of the required endpoints can be discovered. This includes the endpoint that allows access to the public key needed to verify the signature on the ID Token. The client_id is the client ID of the application (Authenticator) registered with the IdP. The same redirect_uri value must be configured with the IdP.
The two files used for the Microsoft Credential Expert card are available in the issuer_config folder.
I recommend that you take these files as a starting point and make minimal changes. Test that you can create your own VC before exploring further. As a quick test, copy and rename the files and create a new VC by just changing the background colour (#FFD700 is the RGB colour mix) and the VC type.
Once you have created the new display and rules files, you can create a new credential in the VC service.
My recommendation is to set the credential name to the same as the VC type in the rules file.
After configuring your new VC, you will see a summary page:
If you click the credential URL, you should see a manifest with all your settings in it. If this displays an error message, it may be due to latency (wait and try again), or you made an error in one of the files.
Updating issuer/app.js
You will need to update the issuer app to generate an issuance request for your new VC. Open issuer/app.js and locate:
These two lines are specifying the VC based on the credential URL and type. Copy these two lines and then comment out the original lines with a couple of slashes. Update the new lines with your VC's credential URL and type.
Now you are ready to issue your own VC. To create and issue your own VC, watch my demo from the webinar https://learn.xtseminars.co.uk/video/verifiable-credentials. You can find it a 37:19
Proving ownership of the linked domain
As you could see in the video, your VC was being issued by an unverified service.
The domain you configured with the VC services appears as a linked domain in the DID document for the service. This states that the DID is owned by the domain. However, the domain owner needs to prove it.
Ownership is established by placing a signed JSON document at:
The document is created, signed and downloaded via the VC service settings page:
If you publish the document via IIS, you will need to create a virtual directory named ".well-known".
And if you were wondering why your administrator needed Cryptograph Sign permission on Key Vault, this is so that they can produce and sign the document.
Now we are ready to try reissuing the VC and will see that the domain is verified. But before that, let's update the verifier app to generate the correct presentation request.
Updating verifier/app.js
To verify your new VC, you will need to update the presentation request in the verifier app. Open verifier/app.js and locate:
As before, copy all three lines and comment out the originals. Update the three lines with your credential URL, type, and the DID of your VC Service.
Now you are ready to issue and verify your new VC. Watch my demo from the webinar https://learn.xtseminars.co.uk/video/verifiable-credentials. You can find it a 46.49
Changing the IdP
The ID token is created when the user signs in to the Microsoft B2C directory. The claims in the token are used to populate the VC. You can use any OpenID Connect IdP to generate the ID Token.
In the Microsoft example documentation, when they change the IdP they switch the key vault for the issuer and verifier into your own test tenant. This is shown below:
What's more, they combine the app registration for the issuer, verifier and Authenticator. I personally think this is the wrong approach and very confusing. When changing the IdP, there is no advantage to moving the Key Vault for the issuer and verifier apps into your own test environment. The Authenticator could be an app registered with any IdP, Azure AD, Azure B2C, Okta, Auth0 and so on. As such, it should not be combined with the issuer and verifier apps.
My recommendation is to leave the environment as is and simply move the IdP app registration from Azure B2C into an IdP of your choice.
You will need to update the rules file to work with your new IdP. I am going to show the use of an Azure AD as my IdP.
The rules file will need to be updated to reflect the Authenticator app registration client ID and the OpenID Connect metadata endpoint for the IdP. You will also see that a scope parameter has been added. If the scope parameter is not present in the file, then the scope defaults to openid. This returns a very sparsely populated ID Token. To add the additional claims (given_name, family_name), you will need the scope set to "openid, profile". To fully understand OpenID Connect and scope come on my Identity Masterclass.
In the above rules file, you will notice that the VC firstname claim is indexed. This allows the credential to searched and revoked by first name. It's a silly example, and I hadn’t noticed I had left it in the video. The identifier that is used to revoke a credential should be immutable. At least it shows you how to set an indexed claim. Take a look here for more details of revoking VCs https://docs.microsoft.com/en-gb/azure/active-directory/verifiable-credentials/how-to-issuer-revoke.
Registering the Authenticator in Azure AD
Registering the Authenticator is done via App registrations.
You will need to choose a name, set the app type to Public client/native… and redirect URI to vcclient/openid. After registering the app, update the rules file with the client ID and metadata endpoint.
The last step is to add the additional claims to the ID token.
Add a new VC to the VC service, update issuer/apps.js to issue the new VC and verifier/apps.js to request the new VC. And you are good to go.
Watch my demo from the webinar. https://learn.xtseminars.co.uk/video/verifiable-credentials You can find it a 1:05:43
Nearly the end…
If you have got this far, well done!
Thank you for reading this blog, and stay tuned for the next one. Please let your friends and colleagues know about the blog via LinkedIn and Twitter, don't forget to include me, so I see it! twitter: @john_craddock and/or www.linkedin.com/in/johnxts
My next identity masterclasses for CET and EST are in March 2022. Why don't you join me for an action-packed week?
Monday 7th - Friday 11th March 2022 9:00 - 17:00 CET
Monday 14th - Friday 18th March 2022 8:00 - 16:00 EST
Full details at https://learn.xtseminars.co.uk