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:**
```bash
./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

```bash
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

```bash
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

```typescript
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

```typescript
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

```typescript
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](./cdn-setup.md)
- [Deployment Overview](../overview.md)
- [Entra VerifiedID Integration](../../integrations/entra-verifiedid/README.md)
- [Operations Runbook](../../operations/ENTRA_VERIFIEDID_RUNBOOK.md)

---

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