Issue Microsoft Entra Verified ID credentials from an application

Note

Azure Active Directory Verifiable Credentials is now Microsoft Entra Verified ID and part of the Microsoft Entra family of products. Learn more about the Microsoft Entra family of identity solutions and get started in the unified Microsoft Entra admin center.

In this tutorial, you run a sample application from your local computer that connects to your Azure Active Directory (Azure AD) tenant. Using the application, you're going to issue and verify a verified credential expert card.

In this article, you learn how to:

  • Create the verified credential expert card in Azure.
  • Gather credentials and environment details to set up the sample application.
  • Download the sample application code to your local computer.
  • Update the sample application with your verified credential expert card and environment details.
  • Run the sample application and issue your first verified credential expert card.
  • Verify your verified credential expert card.

The following diagram illustrates the Microsoft Entra Verified ID architecture and the component you configure.

Diagram that illustrates the Azure A D Verifiable Credentials architecture.

Prerequisites

Create the verified credential expert card in Azure

In this step, you create the verified credential expert card by using Microsoft Entra Verified ID. After you create the credential, your Azure AD tenant can issue it to users who initiate the process.

  1. Using the Azure portal, search for Verified ID and select it.

  2. After you set up your tenant, the Create credential should appear. Alternatively, you can select Credentials in the left hand menu and select + Add a credential.

  3. In Create credential, select Custom Credential and click Next:

    1. For Credential name, enter VerifiedCredentialExpert. This name is used in the portal to identify your verifiable credentials. It's included as part of the verifiable credentials contract.

    2. Copy the following JSON and paste it in the Display definition textbox

      {
          "locale": "en-US",
          "card": {
            "title": "Verified Credential Expert",
            "issuedBy": "Microsoft",
            "backgroundColor": "#000000",
            "textColor": "#ffffff",
            "logo": {
              "uri": "https://didcustomerplayground.blob.core.windows.net/public/VerifiedCredentialExpert_icon.png",
              "description": "Verified Credential Expert Logo"
            },
            "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
          },
          "consent": {
            "title": "Do you want to get your Verified Credential?",
            "instructions": "Sign in with your account to get your card."
          },
          "claims": [
            {
              "claim": "vc.credentialSubject.firstName",
              "label": "First name",
              "type": "String"
            },
            {
              "claim": "vc.credentialSubject.lastName",
              "label": "Last name",
              "type": "String"
            }
          ]
      }
      
    3. Copy the following JSON and paste it in the Rules definition textbox

      {
        "attestations": {
          "idTokenHints": [
            {
              "mapping": [
                {
                  "outputClaim": "firstName",
                  "required": true,
                  "inputClaim": "$.given_name",
                  "indexed": false
                },
                {
                  "outputClaim": "lastName",
                  "required": true,
                  "inputClaim": "$.family_name",
                  "indexed": false
                }
              ],
              "required": false
            }
          ]
        },
        "validityInterval": 2592000,
        "vc": {
          "type": [
            "VerifiedCredentialExpert"
          ]
        }
      }
      
    4. Select Create.

The following screenshot demonstrates how to create a new credential:

Screenshot that shows how to create a new credential.

Gather credentials and environment details

Now that you have a new credential, you're going to gather some information about your environment and the credential that you created. You use these pieces of information when you set up your sample application.

  1. In Verifiable Credentials, select Issue credential.

    Screenshot that shows how to select the newly created verified credential.

  2. Copy the authority, which is the Decentralized Identifier, and record it for later.

  3. Copy the manifest URL. It's the URL that Authenticator evaluates before it displays to the user verifiable credential issuance requirements. Record it for later use.

  4. Copy your Tenant ID, and record it for later. The Tenant ID is the guid in the manifest URL highlighted in red above.

Download the sample code

The sample application is available in .NET, and the code is maintained in a GitHub repository. Download the sample code from GitHub, or clone the repository to your local machine:

git clone https://github.com/Azure-Samples/active-directory-verifiable-credentials-dotnet.git

Configure the verifiable credentials app

Create a client secret for the registered application that you created. The sample application uses the client secret to prove its identity when it requests tokens.

  1. Go to the App registrations page that is located inside Azure Active Directory.

  2. Select the verifiable-credentials-app application you created earlier.

  3. Select the name to go into the registration details.

  4. Copy the Application (client) ID, and store it for later.

    Screenshot that shows how to copy the app registration ID.

  5. From the main menu, under Manage, select Certificates & secrets.

  6. Select New client secret, and do the following:

    1. In Description, enter a description for the client secret (for example, vc-sample-secret).

    2. Under Expires, select a duration for which the secret is valid (for example, six months). Then select Add.

    3. Record the secret's Value. You'll use this value for configuration in a later step. The secret’s value won't be displayed again, and isn't retrievable by any other means. Record it as soon as it's visible.

At this point, you should have all the required information that you need to set up your sample application.

Update the sample application

Now you'll make modifications to the sample app's issuer code to update it with your verifiable credential URL. This step allows you to issue verifiable credentials by using your own tenant.

  1. Under the active-directory-verifiable-credentials-dotnet-main folder, open Visual Studio Code, and select the project inside the 1-asp-net-core-api-idtokenhint folder.

  2. Under the project root folder, open the appsettings.json file. This file contains information about your Microsoft Entra Verified ID environment. Update the following properties with the information that you recorded in earlier steps:

    1. Tenant ID: your tenant ID
    2. Client ID: your client ID
    3. Client Secret: your client secret
    4. IssuerAuthority: Your Decentralized Identifier
    5. VerifierAuthority: Your Decentralized Identifier
    6. Credential Manifest: Your manifest URL
  3. Save the appsettings.json file.

The following JSON demonstrates a complete appsettings.json file:

{
  "AppSettings": {
    "Endpoint": "https://verifiedid.did.msidentity.com/v1.0",
    "VCServiceScope": "3db474b9-6a0c-4840-96ac-1fceb342124f/.default",
    "Instance": "https://login.microsoftonline.com/{0}",
    "TenantId": "12345678-0000-0000-0000-000000000000",
    "ClientId": "33333333-0000-0000-0000-000000000000",
    "ClientSecret": "123456789012345678901234567890",
    "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]",
    "IssuerAuthority": "did:web:example.com...",
    "VerifierAuthority": "did:web:example.com...",
    "CredentialManifest":  "https://verifiedid.did.msidentity.com/v1.0/12345678-0000-0000-0000-000000000000/verifiableCredentials/contracts/VerifiedCredentialExpert"
  }
}

Issue your first verified credential expert card

Now you're ready to issue your first verified credential expert card by running the sample application.

  1. From Visual Studio Code, run the Verifiable_credentials_DotNet project. Or, from your operating system's command line, run:

    cd active-directory-verifiable-credentials-dotnet/1-asp-net-core-api-idtokenhint
    dotnet build "AspNetCoreVerifiableCredentials.csproj" -c Debug -o .\\bin\\Debug\\netcoreapp3.
    dotnet run
    
  2. In another command prompt window, run the following command. This command runs ngrok to set up a URL on 5000, and make it publicly available on the internet.

    ngrok http 5000
    

    Note

    On some computers, you might need to run the command in this format: ./ngrok http 3000.

  3. Open the HTTPS URL generated by ngrok.

    Screenshot that shows how to get the ngrok public URL.

  4. From a web browser, select Get Credential.

    Screenshot that shows how to choose get the credential from the sample app.

  5. Using your mobile device, scan the QR code with the Authenticator app. You can also scan the QR code directly from your camera, which will open the Authenticator app for you.

    Screenshot that shows how to scan the Q R code.

  6. At this time, you'll see a message warning that this app or website might be risky. Select Advanced.

    Screenshot that shows how to respond to the warning message.

  7. At the risky website warning, select Proceed anyways (unsafe). You're seeing this warning because your domain isn't linked to your decentralized identifier (DID). To verify your domain, follow Link your domain to your decentralized identifier (DID). For this tutorial, you can skip the domain registration, and select Proceed anyways (unsafe).

    Screenshot that shows how to proceed with the risky warning.

  8. You'll be prompted to enter a PIN code that is displayed in the screen where you scanned the QR code. The PIN adds an extra layer of protection to the issuance. The PIN code is randomly generated every time an issuance QR code is displayed.

    Screenshot that shows how to type the pin code.

  9. After you enter the PIN number, the Add a credential screen appears. At the top of the screen, you see a Not verified message (in red). This warning is related to the domain validation warning mentioned earlier.

  10. Select Add to accept your new verifiable credential.

    Screenshot that shows how to add your new credential.

Congratulations! You now have a verified credential expert verifiable credential.

Screenshot that shows a newly added verifiable credential.

Go back to the sample app. It shows you that a credential successfully issued.

Screenshot that shows a successfully issued verifiable credential.

Verify the verified credential expert card

Now you are ready to verify your verified credential expert card by running the sample application again.

  1. Hit the back button in your browser to return to the sample app home page.

  2. Select Verify credentials.

    Screenshot that shows how to select the verify credential button.

  3. Using the authenticator app, scan the QR code, or scan it directly from your mobile camera.

  4. When you see the warning message, select Advanced. Then select Proceed anyways (unsafe).

  5. Approve the presentation request by selecting Allow.

    Screenshot that shows how to approve the verifiable credentials new presentation request.

  6. After you approve the presentation request, you can see that the request has been approved. You can also check the log. To see the log, select the verifiable credential.

    Screenshot that shows a verified credential expert card.

  7. Then select Recent Activity.

    Screenshot that shows the recent activity button that takes you to the credential history.

  8. You can now see the recent activities of your verifiable credential.

    Screenshot that shows the history of the verifiable credential.

  9. Go back to the sample app. It shows you that the presentation of the verifiable credentials was received.
    Screenshot that shows that a presentation was received.

Verifiable credential names

Your verifiable credential contains Megan Bowen for the first name and last name values in the credential. These values were hardcoded in the sample application, and were added to the verifiable credential at the time of issuance in the payload.

In real scenarios, your application pulls the user details from an identity provider. The following code snippet shows where the name is set in the sample application.

//file: IssuerController.cs
[HttpGet("/api/issuer/issuance-request")]
public async Task<ActionResult> issuanceRequest()
  {
    ...

    // Here you could change the payload manifest and change the first name and last name.
    payload["claims"]["given_name"] = "Megan";
    payload["claims"]["family_name"] = "Bowen";
    ...
}

Next steps

In the next step, learn how a third-party application, also known as a relying party application, can verify your credentials with its own Azure AD tenant verifiable credentials API service.