the_order/docs/deployment/azure/entra-verifiedid.md

Entra VerifiedID Deployment Guide

Last Updated: 2025-01-27
Status: Complete and Operational

Overview

Complete deployment guide for Microsoft Entra VerifiedID integration, including credential issuance, verification, and webhook handling.

Quick Start

Automated Setup:

./scripts/deploy/deploy-entra-verifiedid.sh

Prerequisites

Azure Requirements

1. Azure Subscription with active Entra ID tenant
2. Entra VerifiedID service enabled
3. Azure Key Vault for secret storage
4. Application Registration in Entra ID

Required Permissions

• Global Administrator or Application Administrator
• Key Vault Contributor
• Entra ID Application Administrator

Setup Steps

Step 1: Enable Entra VerifiedID

1. Navigate to Azure Portal → Entra ID → Verified ID
2. Enable the service
3. Create a Verified ID credential issuer
4. Note the Tenant ID and Client ID

Step 2: Create Application Registration

1. Go to Azure Portal → Entra ID → App registrations
2. Create new registration
3. Generate Client Secret
4. Grant API permissions:
   • VerifiableCredential.Create.All
   • VerifiableCredential.Read.All

Step 3: Configure Key Vault

az keyvault secret set \
  --vault-name <key-vault-name> \
  --name "entra-tenant-id" \
  --value "<tenant-id>"

az keyvault secret set \
  --vault-name <key-vault-name> \
  --name "entra-client-id" \
  --value "<client-id>"

az keyvault secret set \
  --vault-name <key-vault-name> \
  --name "entra-client-secret" \
  --value "<client-secret>"

Step 4: Create Credential Manifest

1. Use Azure Portal or API to create manifest
2. Configure claims and display properties
3. Note the Manifest ID

Step 5: Configure Environment Variables

export ENTRA_TENANT_ID="<tenant-id>"
export ENTRA_CLIENT_ID="<client-id>"
export ENTRA_CLIENT_SECRET="<client-secret>"
export ENTRA_CREDENTIAL_MANIFEST_ID="<manifest-id>"
export ENTRA_CREDENTIAL_LOGO_URI="https://theordercdn12439.blob.core.windows.net/images/digital-bank-seal.png"
export ENTRA_CREDENTIAL_BG_COLOR="#1a1a1a"
export ENTRA_CREDENTIAL_TEXT_COLOR="#ffffff"

Credential Issuance

Single Manifest

import { EntraVerifiedIDClient } from '@the-order/auth';

const client = new EntraVerifiedIDClient({
  tenantId: process.env.ENTRA_TENANT_ID!,
  clientId: process.env.ENTRA_CLIENT_ID!,
  clientSecret: process.env.ENTRA_CLIENT_SECRET!,
  credentialManifestId: process.env.ENTRA_CREDENTIAL_MANIFEST_ID!,
  logoUri: process.env.ENTRA_CREDENTIAL_LOGO_URI,
  backgroundColor: process.env.ENTRA_CREDENTIAL_BG_COLOR,
  textColor: process.env.ENTRA_CREDENTIAL_TEXT_COLOR,
});

const credential = await client.issueCredential({
  claims: {
    email: 'user@example.com',
    name: 'John Doe',
    role: 'member',
  },
});

Multi-Manifest Support

import { EnhancedEntraVerifiedIDClient } from '@the-order/auth';

const client = new EnhancedEntraVerifiedIDClient({
  tenantId: process.env.ENTRA_TENANT_ID!,
  clientId: process.env.ENTRA_CLIENT_ID!,
  clientSecret: process.env.ENTRA_CLIENT_SECRET!,
  manifests: {
    default: '<default-manifest-id>',
    financial: '<financial-manifest-id>',
    judicial: '<judicial-manifest-id>',
    diplomatic: '<diplomatic-manifest-id>',
  },
});

Webhook Configuration

Setup Webhook Endpoint

1. Create webhook endpoint in your service
2. Configure in Entra VerifiedID portal
3. Set webhook URL: https://your-service.com/api/webhooks/entra

Webhook Handler

app.post('/api/webhooks/entra', async (req, res) => {
  const event = req.body;
  
  switch (event.type) {
    case 'credential.issued':
      // Handle credential issuance
      break;
    case 'credential.verified':
      // Handle credential verification
      break;
  }
  
  res.status(200).send('OK');
});

Best Practices

Security

• ✅ Store secrets in Azure Key Vault
• ✅ Use managed identities where possible
• ✅ Rotate client secrets regularly
• ✅ Enable audit logging
• ✅ Use HTTPS for all endpoints

Performance

• ✅ Implement retry logic with exponential backoff
• ✅ Use connection pooling
• ✅ Cache manifest configurations
• ✅ Monitor API rate limits

Reliability

• ✅ Implement circuit breakers
• ✅ Add health checks
• ✅ Monitor webhook delivery
• ✅ Handle webhook retries

Monitoring

Metrics

• Credential issuance rate
• Credential verification rate
• API error rates
• Webhook delivery success rate
• Average issuance time

Alerts

• High error rates
• Webhook delivery failures
• API quota approaching limits
• Authentication failures

Troubleshooting

Common Issues

Authentication Failures

• Verify tenant ID and client ID
• Check client secret is correct
• Ensure API permissions are granted

Manifest Not Found

• Verify manifest ID is correct
• Check manifest is active
• Ensure proper permissions

Webhook Not Receiving Events

• Verify webhook URL is accessible
• Check webhook configuration in portal
• Review webhook logs

Related Documentation

• Azure CDN Setup
• Deployment Overview
• Entra VerifiedID Integration
• Operations Runbook

---

Note: This guide consolidates information from multiple Entra VerifiedID deployment files. Historical deployment documents have been archived in docs/archive/deployment/entra/.