the-order/docs/deployment/ENTRA_VERIFIEDID_DEPLOYMENT_CHECKLIST.md

Entra VerifiedID Deployment Checklist

This checklist provides detailed steps for deploying Entra VerifiedID integration for eCredential issuance.

Prerequisites

• Azure subscription with appropriate permissions
• Azure CLI installed and configured
• Access to Azure Portal
• Key Vault created and accessible
• Identity service codebase updated with latest Entra integration

Phase 1: Azure Configuration

1.1 Azure AD App Registration

• Task 1.1.1: Navigate to Azure Portal → Azure Active Directory → App registrations
• Task 1.1.2: Click "New registration"
• Task 1.1.3: Enter name: the-order-entra (or your preferred name)
• Task 1.1.4: Select supported account types (typically "Accounts in this organizational directory only")
• Task 1.1.5: Click "Register"
• Task 1.1.6: Note the Application (client) ID - save this as ENTRA_CLIENT_ID
• Task 1.1.7: Note the Directory (tenant) ID - save this as ENTRA_TENANT_ID

1.2 Configure API Permissions

• Task 1.2.1: In App Registration, go to "API permissions"
• Task 1.2.2: Click "Add a permission"
• Task 1.2.3: Select "APIs my organization uses"
• Task 1.2.4: Search for "Verifiable Credentials Service" or use App ID: 3db474b9-7a6d-4f50-afdc-70940ce1df8f
• Task 1.2.5: Select "Application permissions"
• Task 1.2.6: Check "VerifiableCredential.Create.All"
• Task 1.2.7: Check "VerifiableCredential.Verify.All"
• Task 1.2.8: Click "Add permissions"
• Task 1.2.9: Click "Grant admin consent for [Your Organization]"
• Task 1.2.10: Verify consent status shows "Granted for [Your Organization]"

1.3 Create Client Secret

• Task 1.3.1: In App Registration, go to "Certificates & secrets"
• Task 1.3.2: Click "New client secret"
• Task 1.3.3: Enter description: "Entra VerifiedID Integration"
• Task 1.3.4: Select expiration (recommend 12-24 months)
• Task 1.3.5: Click "Add"
• Task 1.3.6: IMMEDIATELY copy the secret value - save this as ENTRA_CLIENT_SECRET
• Task 1.3.7: Store secret securely (it won't be shown again)

1.4 Enable Verified ID Service

• Task 1.4.1: Navigate to Azure Portal → Verified ID
• Task 1.4.2: If service is not enabled, click "Get started"
• Task 1.4.3: Wait for service activation (may take 5-10 minutes)
• Task 1.4.4: Verify service is active and accessible

1.5 Create Credential Manifests

Default Credential Manifest

• Task 1.5.1: In Verified ID, click "Add credential"
• Task 1.5.2: Choose credential type (e.g., "Verified Credential")
• Task 1.5.3: Configure credential name: "The Order Identity Credential"
• Task 1.5.4: Define claims schema:
  • Add claim: email (type: string)
  • Add claim: name (type: string)
  • Add claim: role (type: string)
  • Add additional claims as needed
• Task 1.5.5: Configure issuer information
• Task 1.5.6: Review and create manifest
• Task 1.5.7: Note the Manifest ID - save this as ENTRA_CREDENTIAL_MANIFEST_ID

Diplomatic Credential Manifest (Optional)

• Task 1.5.8: Create manifest for Letters of Credence
• Task 1.5.9: Configure diplomatic-specific claims (recipientName, recipientTitle, missionCountry, etc.)
• Task 1.5.10: Note Manifest ID for diplomatic credentials

Judicial Credential Manifest (Optional)

• Task 1.5.11: Create manifest for judicial appointments
• Task 1.5.12: Configure judicial-specific claims (role, appointmentAuthority, jurisdiction, etc.)
• Task 1.5.13: Note Manifest ID for judicial credentials

Financial Credential Manifest (Optional)

• Task 1.5.14: Create manifest for financial role credentials
• Task 1.5.15: Configure financial-specific claims (role, appointmentDate, jurisdiction, etc.)
• Task 1.5.16: Note Manifest ID for financial credentials

Phase 2: Automated Setup (Alternative to Manual Steps)

• Task 2.1: Run automated setup script: ./scripts/deploy/setup-entra-automated.sh
• Task 2.2: Follow script prompts to provide:
  • Subscription ID
  • Resource Group name
  • App Registration name
  • Key Vault name
• Task 2.3: Review generated .env.entra.example file
• Task 2.4: Verify secrets stored in Key Vault

Phase 3: Environment Configuration

3.1 Store Secrets in Key Vault

• Task 3.1.1: Store entra-tenant-id in Key Vault

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

• Task 3.1.2: Store entra-client-id in Key Vault

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

• Task 3.1.3: Store entra-client-secret in Key Vault

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

• Task 3.1.4: Store entra-credential-manifest-id in Key Vault

  az keyvault secret set --vault-name <keyvault> --name "entra-credential-manifest-id" --value "<manifest-id>"
  

3.2 Configure Development Environment

• Task 3.2.1: Update .env file with Entra credentials:

  ENTRA_TENANT_ID=<tenant-id>
  ENTRA_CLIENT_ID=<client-id>
  ENTRA_CLIENT_SECRET=<client-secret>
  ENTRA_CREDENTIAL_MANIFEST_ID=<manifest-id>
  

• Task 3.2.2: If using multiple manifests, set ENTRA_MANIFESTS:

  ENTRA_MANIFESTS='{"default":"manifest-id-1","diplomatic":"manifest-id-2","judicial":"manifest-id-3","financial":"manifest-id-4"}'
  

• Task 3.2.3: Configure rate limits (optional):

  ENTRA_RATE_LIMIT_ISSUANCE=10
  ENTRA_RATE_LIMIT_VERIFICATION=20
  ENTRA_RATE_LIMIT_STATUS_CHECK=30
  ENTRA_RATE_LIMIT_GLOBAL=50
  

• Task 3.2.4: Verify environment variables are loaded correctly

3.3 Configure Staging Environment

• Task 3.3.1: Create Kubernetes secrets or use External Secrets Operator
• Task 3.3.2: Set all Entra environment variables in staging config
• Task 3.3.3: Verify secrets are accessible to identity service pod
• Task 3.3.4: Test secret access from within pod

3.4 Configure Production Environment

• Task 3.4.1: Set up Key Vault integration or secure secret management
• Task 3.4.2: Configure all Entra environment variables
• Task 3.4.3: Enable secret rotation policies
• Task 3.4.4: Verify secret access and permissions

Phase 4: Testing

4.1 Unit Tests

• Task 4.1.1: Run unit tests: cd packages/auth && pnpm test entra-verifiedid.test.ts
• Task 4.1.2: Verify all tests pass
• Task 4.1.3: Review test coverage report

4.2 Integration Tests

• Task 4.2.1: Set test environment variables:

  export ENTRA_TENANT_ID=<test-tenant-id>
  export ENTRA_CLIENT_ID=<test-client-id>
  export ENTRA_CLIENT_SECRET=<test-client-secret>
  export ENTRA_CREDENTIAL_MANIFEST_ID=<test-manifest-id>
  

• Task 4.2.2: Run integration tests: pnpm test entra-verifiedid.integration.test.ts
• Task 4.2.3: Verify tests pass with real Entra API

4.3 API Endpoint Testing

• Task 4.3.1: Test credential issuance:

  curl -X POST http://localhost:4002/vc/issue/entra \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"claims": {"email": "test@example.com", "name": "Test User"}}'
  

• Task 4.3.2: Verify response contains requestId, url, and qrCode
• Task 4.3.3: Test credential verification:

  curl -X POST http://localhost:4002/vc/verify/entra \
    -H "Content-Type: application/json" \
    -d '{"credential": {...}}'
  

• Task 4.3.4: Test status endpoint:

  curl http://localhost:4002/vc/entra/status/<requestId>
  

4.4 Feature Testing

• Task 4.4.1: Test retry logic by simulating transient failures
• Task 4.4.2: Test rate limiting by exceeding limits
• Task 4.4.3: Test multi-manifest support with different manifestName values
• Task 4.4.4: Test webhook endpoint with sample payload
• Task 4.4.5: Test eIDAS bridge integration (if configured)

Phase 5: Staging Deployment

• Task 5.1: Build and push Docker image for identity service
• Task 5.2: Deploy to staging Kubernetes cluster
• Task 5.3: Verify service starts and health check passes
• Task 5.4: Check logs for Entra client initialization
• Task 5.5: Configure webhook URL in Entra VerifiedID:
  • URL: https://api-staging.theorder.org/vc/entra/webhook
• Task 5.6: Issue test credential in staging
• Task 5.7: Verify webhook receives status updates
• Task 5.8: Check database for credential records
• Task 5.9: Verify metrics are being collected

Phase 6: Monitoring Setup

• Task 6.1: Configure Prometheus to scrape /metrics endpoint
• Task 6.2: Verify Entra metrics are being collected:
  • entra_api_requests_total
  • entra_credentials_issued_total
  • entra_issuance_duration_seconds
  • entra_webhooks_received_total
• Task 6.3: Create Grafana dashboard with panels for:
  • Issuance success rate
  • API request latency (p50, p95, p99)
  • Error rates by operation
  • Webhook processing metrics
  • Active requests gauge
• Task 6.4: Set up alerts for:
  • High error rate (>5% failures)
  • Slow API responses (>5 seconds p95)
  • Webhook processing failures
  • Rate limit violations

Phase 7: Production Deployment

• Task 7.1: Review staging deployment and metrics
• Task 7.2: Create production deployment plan
• Task 7.3: Deploy using blue-green or canary strategy
• Task 7.4: Monitor deployment metrics closely
• Task 7.5: Configure production webhook URL:
  • URL: https://api.theorder.org/vc/entra/webhook
• Task 7.6: Issue test credential in production
• Task 7.7: Verify end-to-end flow works correctly
• Task 7.8: Monitor for 24 hours post-deployment

Phase 8: Documentation and Training

• Task 8.1: Update docs/deployment/DEPLOYMENT_STEPS_SUMMARY.md with completion status
• Task 8.2: Create operational runbook:
  • Common operations
  • Troubleshooting steps
  • Diagnostic commands
  • Escalation procedures
• Task 8.3: Document troubleshooting guide:
  • Common errors and solutions
  • How to check logs
  • How to verify configuration
  • How to test endpoints
• Task 8.4: Conduct training session for operations team
• Task 8.5: Create knowledge base articles

Verification Checklist

After deployment, verify:

• Credential issuance works end-to-end
• Webhooks are received and processed
• Database records are created correctly
• Metrics are being collected
• Alerts are configured and working
• Rate limiting is functioning
• Retry logic handles failures gracefully
• Multi-manifest support works (if configured)
• Documentation is complete and accurate

Rollback Plan

If issues occur:

1. Disable Entra routes in identity service
2. Revert to previous deployment
3. Investigate issues in staging
4. Fix and redeploy

Support Contacts

• Azure Support: Azure Support Portal
• Entra VerifiedID Docs: Microsoft Learn
• Internal Team: [Your team contact]

---

Last Updated: [Current Date] Version: 1.0 Status: Ready for Deployment