Azure Verified ID Implementation Guide

Last Updated on May 26, 2026 by Arnav Sharma

If you are an identity architect or cloud security engineer, you already know that password-based verification is a liability. Microsoft Entra Verified ID gives enterprises a practical path to decentralized, cryptographically verifiable credentials that work across organizational boundaries without exposing raw identity data. This Azure Verified ID implementation guide walks you through every configuration stage: tenant setup, Azure Key Vault, credential issuance, verification requests, API integration, and production hardening.

By the end of this guide, you will have a fully operational Microsoft Entra Verified ID service capable of issuing and verifying W3C-compliant verifiable credentials in your environment.

---

What Is Microsoft Entra Verified ID?

Microsoft Entra Verified ID is Microsoft’s managed issuance and verification service for W3C Verifiable Credentials, operating on the did:web decentralized identifier method. It sits within the broader Microsoft Entra identity platform and is available to any Azure tenant.

The service enables three core actors to exchange cryptographically signed claims without a centralized intermediary.

How Verified IDs Work: The Issuer, Holder, Verifier Model

Every Verified ID interaction involves three parties:

• Issuer: An organization that creates and signs a verifiable credential (for example, Woodgrove Inc. issuing an employment credential to an employee).
• Holder: The individual who stores the credential in a wallet app, typically Microsoft Authenticator.
• Verifier: A relying party that requests and validates the credential (for example, Proseware verifying the employment claim to grant a discount).

The issuer signs the credential with a private key stored in Azure Key Vault. The verifier checks the signature against the issuer’s public key, which is published at the issuer’s well-known DID endpoint. No personal data flows through Microsoft’s service; only the signed claim and the verification result travel between parties.

W3C Verifiable Credentials and the did:web Method

Microsoft Entra Verified ID implements the W3C Verifiable Credentials Data Model, ensuring interoperability with any standards-compliant wallet or verifier. The default trust system for new tenants is did:web, which anchors your Decentralized Identifier (DID) to a domain you control rather than a blockchain. This means your DID resolves as a JSON document hosted at https://your-domain/.well-known/did.json.

Any new tenant onboarded after June 2022 defaults to did:web. Older tenants that onboarded on ION (the Bitcoin-anchored method) can reconfigure to did:web, though doing so requires tenant reconfiguration and credential reissuance.

Key Use Cases

Microsoft Entra Verified ID targets several enterprise identity scenarios where traditional federated identity falls short:

• Employee verification across organizations: A contractor proves employment at a partner company without that company exposing directory access.
• Accelerated onboarding: NHS used Azure AD and Verified ID to reduce staff transfer processing from multiple days to minutes.
• Education credential portability: Universities issue tamper-proof degree credentials that students present to employers directly.
• Healthcare workforce management: Clinicians carry role and license credentials in a wallet, verified at point of care.
• Government and regulated industries: The service now supports Microsoft GCC environments for public sector deployments.

---

Prerequisites Before You Configure Your Tenant

Getting these prerequisites right before touching the Azure portal saves hours of troubleshooting. Skipping any of them is the most common reason implementations stall.

Required Roles and Permissions

You need the following role assignments in place before you begin:

Role	Scope	Purpose
Authentication Policy Administrator	Microsoft Entra directory	Configure the Verified ID service and register the DID
Application Administrator (or Global Admin)	Microsoft Entra directory	Register the app and grant API permissions
Contributor	Azure subscription or resource group	Deploy and configure Azure Key Vault
Key Vault Crypto Officer	Key Vault instance	Create and manage signing keys

Using Global Administrator for routine setup is not recommended. Scope permissions to the least-privilege roles above and use Global Admin only if no combination of the above meets your needs.

Azure Key Vault Requirements

The Verified ID service stores your issuer’s signing keys in Azure Key Vault. Before setup:

1. Permission model: The Key Vault you use must be set to Key Vault Access Policy as its permission model. Azure role-based access control (RBAC) is not currently supported for the Verified ID service’s key operations. This is a hard limitation and a common misconfiguration that causes silent failures.
2. Access policies: You need two separate access policies on the Key Vault: one for the Verified ID admin account (with Create, Delete, Sign, List permissions), and one for the Request Service API service principal (with Sign and Get Key permissions).
3. Region alignment: The Verified ID service is available in West Europe, North Europe, West US 2, West Central US, Australia, and Japan. Deploy your Key Vault in the same region as your planned Verified ID service to minimize latency and keep data residency consistent. For EU tenants, the service automatically uses EU regions.

Licensing: Free Tier vs Entra ID P1/P2

Verified ID itself is free up to 50,000 transactions per month. A transaction is defined as a single issuance, verification, or revocation. Once you exceed that monthly threshold, you need Microsoft Entra ID P1 or P2 to continue. For most enterprise implementations that are still in pilot phase, the free tier is sufficient to validate the solution before committing to licensing.

Face Check, the premium facial matching feature, is priced separately and billed through an Azure subscription linked to your tenant.

---

Quick Setup vs Advanced Setup: Which to Choose?

Microsoft offers two setup paths for configuring your tenant to support the Verified ID service. Choosing the wrong one early creates re-architecture work later.

Factor	Quick Setup (Managed)	Advanced Setup
Key Vault management	Microsoft-managed	Customer-managed
DID format	did:web:verifiedid.entra.microsoft.com	did:web:your-domain.com
Domain branding	Microsoft domain	Your own domain
FIPS compliance	Already compliant (P-256)	Requires upgrade if pre-Feb 2024
Admin complexity	Low	High
Enterprise customization	Limited	Full control
Best for	Pilots, SMBs, fast proof-of-concept	Enterprise, regulated industries, custom branding

Quick Setup: When to Use It

Quick Setup is the right choice if you need to test credential issuance rapidly, operate a small tenant, or do not have custom domain requirements. Microsoft manages the signing keys and hosts the DID document. Quick Setup authorities already use FIPS-compliant P-256 keys, so no key upgrade is required.

Advanced Setup: When to Use It

Advanced Setup gives you full control over the configuration: your own Azure Key Vault, your own domain-anchored DID, and the ability to customize every aspect of credential definitions. It is the required path for enterprises operating in regulated industries, organizations with custom domain branding requirements, and any deployment that needs to publish credential types on its own domain.

Advanced Setup is the approach detailed in the step-by-step section below.

FIPS Compliance Warning: Action Required Before July 1, 2026

If your organization configured Verified ID using Advanced Setup before February 2024, you are almost certainly using a P-256K signing key. P-256K keys are not FIPS compliant and are being retired on July 1, 2026. After that date, non-compliant keys will stop functioning.

To check your exposure: if your DID does not start with did:web:verifiedid.entra.microsoft.com, you were set up using Advanced Setup and should verify your key type immediately. Upgrade using the PowerShell script provided by Microsoft (the Upgrade-SigningKey.ps1 script from the GitHub samples repository). The process requires Verifiable Credentials Service Admin API permission, Key Vault access, and the ability to deploy an updated did.json to your .well-known endpoint.

---

Step-by-Step: Configure Microsoft Entra Verified ID (Advanced Setup)

This walkthrough assumes you are configuring a new tenant from scratch using Advanced Setup for full enterprise control.

Step 1: Create and Configure Azure Key Vault

1. Sign in to the Azure portal and navigate to Key Vaults.
2. Select Create and provision a new Key Vault in the same region as your planned Verified ID service.
3. On the Access configuration tab, set the Permission model to Vault access policy (not Azure RBAC).
4. After creation, go to Access Policies and add two policies:
   • Policy 1 (Admin account): Key permissions: Get, List, Create, Delete, Sign. This is the account you will use during setup.
   • Policy 2 (Request Service API): Key permissions: Get, Sign. Assign this to the Verifiable Credentials Service Request service principal.
5. Save both policies before proceeding.

A common pitfall: if you skip the Request Service API access policy, credential signing fails at runtime with a generic 401 error that does not identify Key Vault as the source.

Step 2: Configure the Verified ID Service in the Admin Center

1. Sign in to the Microsoft Entra admin center using an account with Authentication Policy Administrator role.
2. Navigate to Verified ID in the left menu.
3. Select Setup and choose Advanced.
4. On the Organization page, enter your organization name and website.
5. Under Key Vault, select the Key Vault you created in Step 1. The service will generate a signing key in that vault.
6. Complete the setup wizard. Once the signing key is created, you will see the Verified ID service status move to the next configuration phase.

Step 3: Register Your Decentralized Identifier (DID)

After the Key Vault signing key is provisioned, register your DID document:

1. In the Entra admin center under Verified ID, select Overview.
2. From the setup checklist, select Register decentralized ID.
3. The service generates your DID in the format did:web:your-domain.com. Copy this value.
4. Download the did.json file provided by the portal.
5. Publish did.json to https://your-domain/.well-known/did.json. This endpoint must be publicly accessible over HTTPS.

If you are using Azure App Service for your web frontend, the .well-known directory may need an explicit routing rule to serve static files in that path.

Step 4: Verify Domain Ownership

Domain verification links your DID to a domain you control, establishing the trust root for credential verification:

1. In the setup checklist, select Verify domain ownership.
2. Download the did-configuration.json file.
3. Publish did-configuration.json to https://your-domain/.well-known/did-configuration.json.
4. Return to the portal and select Verify. The service fetches your .well-known endpoint and confirms the DID document matches.

Both JSON files must resolve publicly before the verification check succeeds. A firewall, CDN misconfiguration, or missing MIME type for .json files will cause the check to fail silently. Test your endpoints with a browser or curl before triggering the portal verification.

Once both the DID registration and domain verification show green checkmarks in the setup checklist, your tenant is ready to issue credentials.

Step 5: Register an Application and Grant API Permissions

Your issuer and verifier applications call the Request Service API to trigger issuance and verification flows. Each application needs a registered service principal with the correct permissions.

1. In the Entra admin center, go to App registrations and select New registration.
2. Name the application (for example: verifiable-credentials-app) and set Supported account types to Single tenant.
3. Select Register.
4. Go to API permissions and add: Verifiable Credentials Service Request > VerifiableCredential.Create.All.
5. Grant admin consent for the permission.
6. Under Certificates and secrets, create a client secret. Record the Client ID, Tenant ID, and Secret value for use in your application configuration.

---

Issuing Your First Verifiable Credential

With the tenant configured, the next step is defining what credentials to issue and wiring up the issuance flow.

Define Credential Rules and Display Definitions

Each credential type has two JSON definitions:

• Display definition: Controls how the credential appears in the holder’s Microsoft Authenticator wallet (card title, background color, logo, claim labels). This can be localized into multiple languages.
• Rules definition: Specifies the required inputs for issuance. For ID token flows, this maps claims from your OIDC provider (such as Entra ID or Azure AD B2C) into the credential’s claim schema.

In the Entra admin center under Verified ID, select Credentials and then Add credential. Choose Custom credentialfor full control over the claim schema, or use Verified Employee for a pre-built schema aligned with the Microsoft Entra Verified ID Network.

Using the Request Service API for Issuance

Your backend application calls the Request Service API to initiate a credential issuance session. The API returns a deep-link URL and a QR code URL that you surface to the user.

A minimal Node.js issuance request looks like this:

javascript

const msalConfig = {
  auth: {
    clientId: 'your-app-client-id',
    authority: 'https://login.microsoftonline.com/your-tenant-id',
    clientSecret: 'your-client-secret'
  }
};
const msalClient = new ConfidentialClientApplication(msalConfig);

// Acquire token for Verified ID API
const tokenResponse = await msalClient.acquireTokenByClientCredential({
  scopes: ['3db474b9-6a0c-4840-96ac-1fceb342124f/.default']
});

// Build issuance request
const issuanceRequest = {
  includeQRCode: true,
  callback: {
    url: 'https://yourapp.com/api/issuance-callback',
    state: sessionId,
    headers: { 'api-key': 'your-callback-secret' }
  },
  authority: 'your-authority-did',
  registration: { clientName: 'Your App Name' },
  type: 'YourCredentialType',
  manifest: 'https://verifiedid.did.msidentity.com/v1.0/tenants/your-tenant-id/verifiableCredentials/contracts/your-contract-id/manifest',
  claims: { firstName: 'Alice', lastName: 'Smith', employeeId: 'E-1234' }
};

// POST to Request Service API
const response = await axios.post(
  'https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createIssuanceRequest',
  issuanceRequest,
  { headers: { Authorization: `Bearer ${tokenResponse.accessToken}` } }
);

The response includes a url (deep link for mobile) and optionally a qrCode (base64 PNG) that you embed in your web application. The user scans this with Microsoft Authenticator to accept the credential into their wallet.

The QR Code Flow via Microsoft Authenticator

When the user scans the QR code:

1. Authenticator fetches the manifest from your credential contract URL.
2. The app presents the claim values to the user for consent.
3. Upon acceptance, Authenticator calls the Verified ID service to complete issuance.
4. The credential is stored in the user’s Authenticator wallet as a card.
5. Your callback endpoint receives a issuance_successful status notification.

The callback includes the time the credential was issued and its expiration timestamp. Your business logic can use these values for downstream access control.

---

Verifying Credentials with the Request Service API

The verification flow mirrors issuance. Your verifier application creates a presentation request, the user scans a QR code, Authenticator presents the credential, and your callback receives the verification result.

Creating a Verification Request

javascript

const verificationRequest = {
  includeQRCode: true,
  callback: {
    url: 'https://yourapp.com/api/verification-callback',
    state: sessionId,
    headers: { 'api-key': 'your-callback-secret' }
  },
  authority: 'your-verifier-did',
  registration: { clientName: 'Your Verifier App' },
  requestedCredentials: [
    {
      type: 'YourCredentialType',
      purpose: 'Verify employment status',
      acceptedIssuers: ['did:web:issuer-domain.com'],
      configuration: { validation: { allowRevoked: false, validateLinkedDomain: true } }
    }
  ]
};

const response = await axios.post(
  'https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest',
  verificationRequest,
  { headers: { Authorization: `Bearer ${tokenResponse.accessToken}` } }
);

Setting validateLinkedDomain: true ensures the verifier checks that the issuer’s DID is linked to a verified domain. This is the key security control that prevents credential spoofing from unverified issuers.

Handling the Callback Endpoint

Your callback endpoint receives POST requests from the Verified ID service at key state transitions. Validate the api-keyheader on every callback to prevent spoofing. The requestStatus field progresses through:

• request_retrieved: User scanned the QR code.
• presentation_verified: Credential was successfully presented and validated.
• presentation_error: Verification failed (expired credential, revoked, signature mismatch).

Extract the verified claims from the verifiedCredentialsData array in the presentation_verified callback. These claims have been cryptographically validated by the service before reaching your callback.

---

Security Hardening for Production Deployments

Moving Verified ID from a pilot to production requires additional security controls beyond the basic configuration.

Key Vault Access Policies vs Azure RBAC

The current limitation requiring Key Vault Access Policy (not RBAC) deserves explicit architectural planning. In environments where all Key Vault resources are standardized on RBAC, you will need a dedicated Key Vault instance for Verified ID with Access Policy enabled. Do not attempt to reconfigure an existing RBAC-enabled Key Vault as this can cascade access disruptions across other services using that vault.

Service Principal Least-Privilege Configuration

The application service principal registered in Step 5 should be scoped as tightly as possible:

• Grant only VerifiableCredential.Create.All on the Request Service API, nothing broader.
• Rotate client secrets on a defined schedule (90 days is a reasonable baseline for non-automated workloads).
• Consider Managed Identity for your backend service instead of client secrets if your compute layer supports it (Azure App Service, Azure Functions, Azure Container Apps all support Managed Identity).

Monitoring and Throttling Considerations

Azure Key Vault throttling applies to every Verified ID transaction. Each issuance involves three signing operations against Key Vault. At scale, this can cause throttling errors that are not surfaced clearly in the Verified ID service layer.

Plan for:

• Batch credential creation during off-peak windows for large onboarding events.
• Application Insights integration on your frontend for end-to-end latency monitoring.
• Key Vault diagnostic logs forwarded to your SIEM to track signing operation volume and errors.

The Verified ID service is deployed across a limited set of Azure regions. If your application is globally distributed, the region proximity of your Key Vault and your frontend compute will affect issuance latency.

---

Common Errors and Troubleshooting

Error	Likely Cause	Fix
401 during issuance	Missing Key Vault access policy for Request Service API principal	Add Sign and Get Key permissions to the Request Service API service principal in Key Vault access policies
DID domain verification fails	.well-known/did.json not publicly accessible	Check CDN/firewall rules; test with curl https://your-domain/.well-known/did.json
QR code not scanning	Manifest URL unreachable or malformed	Validate the manifest URL returns a valid JSON response
Callback not firing	App firewall blocking Verified ID service IPs	Whitelist Verified ID outbound IPs or use a public callback URL during testing
presentation_error on valid credential	validateLinkedDomain mismatch or expired credential	Check credential expiry; confirm issuer’s domain is verified
Credential not appearing in Authenticator	Credential contract not published correctly	Re-publish display and rules definitions; confirm contract URL resolves
FIPS key error (post July 2026)	P-256K signing key not upgraded	Run Upgrade-SigningKey.ps1 and republish did.json

For DID resolution debugging, use the DID Resolver in the Entra admin center under Verified ID > Tools. Paste your DID to inspect the full DID document and linked domain configuration.

---