# 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
  ```bash
  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
  ```bash
  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
  ```bash
  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
  ```bash
  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:
  ```bash
  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`:
  ```bash
  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):
  ```bash
  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:
  ```bash
  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:
  ```bash
  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:
  ```bash
  curl -X POST http://localhost:4002/vc/verify/entra \
    -H "Content-Type: application/json" \
    -d '{"credential": {...}}'
  ```
- [ ] **Task 4.3.4**: Test status endpoint:
  ```bash
  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](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade)
- **Entra VerifiedID Docs**: [Microsoft Learn](https://learn.microsoft.com/en-us/azure/active-directory/verifiable-credentials/)
- **Internal Team**: [Your team contact]

---

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