Issuing your own DIDs & VCs with Azure AD and the SDK apps

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 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)

  1. Introduction to the future of identity - DIDs & VCs

  2. Issuing DIDs and VCs with the Microsoft SDK app and Authenticator

  3. Issuing DIDs and VCs with the Microsoft Request Service REST API - replaces no 2

  4. Issuing your own DIDs & VCs with Azure AD and the SDK apps

  5. 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.

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.

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" or better still come on my identity masterclass 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.

Components for issuing and verifying VCs

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.

Simplified configuration for Microsoft demo environment and the example apps

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.

Configuring your own Azure AD Verifiable Credential service

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.

Permissions required for Azure 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 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.

VC card display characteristics

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"

Rules for generating a VC

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.

Example display and rules files

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.

Creating a new VC

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:

VC overview showing Credential URL

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.

VC manifest/contract

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: