Create verifiable credentials for ID token hint

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.

A rules definition that uses the idTokenHint attestation produces an issuance flow where the relying party application passes claim values in the issuance request payload. It is the relying party application's responsibility to ensure that required claim values are passed in the request. How the claim values are gathered is up to the application.

Create a custom credential

In the Azure portal, when you select Add credential, you get the option to launch two quickstarts. Select custom credential, and then select Next.

Screenshot of the "Issue credentials" quickstart for creating a custom credential.

On the Create a new credential page, enter the JSON code for the rules and display definitions. In the Credential name box, give the credential a type name. To create the credential, select Create.

Screenshot of the "Create a new credential" page, displaying JSON samples for the rules and display files.

Sample JSON display definitions

The expected JSON for the display definitions is the inner content of the displays collection. The JSON is a collection, so if you want to support multiple locales, you add multiple entries, with a comma as a separator.

{
    "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"
      }
    ]
}

Sample JSON rules definitions

The expected JSON for the rules definitions is the inner content of the rules attribute, which starts with the attestation attribute.

{
      "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"
        ]
      }
}

Configure the samples to issue and verify your custom credential

To configure your sample code to issue and verify by using custom credentials, you need:

  • Your tenant's issuer decentralized identifier (DID)
  • The credential type
  • The manifest URL to your credential

The easiest way to find this information for a custom credential is to go to your credential in the Azure portal. Select Issue credential. There you have access to a text box with a JSON payload for the Request Service API. Replace the placeholder values with your environment's information. The issuer’s DID is the authority value.

Screenshot of the quickstart custom credential issue.

Next steps

For more information, see: