the_order/docs/training/ENTRA_VERIFIEDID_TRAINING.md

Entra VerifiedID Integration - Team Training Guide

Training Overview

This guide provides training materials for the operations and development teams on the Entra VerifiedID integration.

Training Objectives

By the end of this training, team members should be able to:

1. Understand Entra VerifiedID integration architecture
2. Deploy and configure the integration
3. Monitor and troubleshoot issues
4. Perform common operations
5. Handle emergencies

Training Modules

Module 1: Architecture Overview (30 minutes)

What is Entra VerifiedID?

• Microsoft's managed service for verifiable credentials
• Issues W3C-compliant verifiable credentials
• Provides QR codes for mobile wallet integration
• Handles credential lifecycle management

Integration Architecture

Client → Identity Service → Entra VerifiedID API
                ↓
         Database (tracking)
                ↓
         Event Bus (notifications)
                ↓
         Monitoring (metrics)

Key Components

• EntraVerifiedIDClient: Base client for API communication
• EnhancedEntraVerifiedIDClient: Enhanced with retry and multi-manifest
• Webhook Handler: Processes status updates
• Metrics: Prometheus metrics for monitoring

Module 2: Deployment (45 minutes)

Prerequisites

• Azure subscription access
• Kubernetes cluster access
• Key Vault access

Deployment Steps

1. Azure Configuration

   ./scripts/deploy/setup-entra-automated.sh
   

2. Environment Setup

   ./scripts/deploy/configure-env-dev.sh
   

3. Staging Deployment

   ./scripts/deploy/deploy-staging.sh
   

4. Production Deployment

   ./scripts/deploy/deploy-production.sh
   

Hands-On Exercise

• Deploy to staging environment
• Verify deployment
• Test credential issuance

Module 3: Operations (45 minutes)

Daily Operations

• Health checks
• Monitoring dashboards
• Log review

Common Operations

• Issue credential manually
• Check credential status
• Verify credential
• View metrics

Hands-On Exercise

• Issue a test credential
• Monitor metrics
• Check logs

Module 4: Monitoring & Troubleshooting (60 minutes)

Key Metrics

• Issuance success rate
• API latency
• Error rates
• Webhook processing

Common Issues

1. Credential Issuance Failing

   • Check Entra credentials
   • Verify API permissions
   • Check network connectivity

2. Webhooks Not Received

   • Verify webhook URL configuration
   • Check firewall rules
   • Review webhook logs

3. High Latency

   • Check network connectivity
   • Review retry configuration
   • Check Entra API status

Troubleshooting Workflow

1. Check service health
2. Review logs
3. Check metrics
4. Verify configuration
5. Test connectivity

Hands-On Exercise

• Simulate common issues
• Practice troubleshooting
• Use diagnostic commands

Module 5: Emergency Procedures (30 minutes)

When to Disable Integration

• Critical security issue
• Entra API outage
• Data corruption

Disable Procedure

# Scale down service
kubectl scale deployment identity-service -n the-order-prod --replicas=0

# Or disable routes
kubectl set env deployment/identity-service ENTRA_TENANT_ID="" -n the-order-prod

Rollback Procedure

kubectl rollout undo deployment/identity-service -n the-order-prod

Hands-On Exercise

• Practice disable procedure
• Practice rollback
• Verify service recovery

Training Materials

Documentation

• Deployment Checklist
• Operational Runbook
• Integration Guide

Scripts

• scripts/deploy/setup-entra-automated.sh
• scripts/deploy/deploy-staging.sh
• scripts/test/test-all-entra-features.sh
• scripts/validation/validate-entra-config.sh

Test Environment

• Staging environment for hands-on practice
• Test credentials for safe experimentation

Assessment

Knowledge Check

1. What are the required environment variables?
2. How do you check if Entra integration is working?
3. What metrics indicate a problem?
4. How do you disable the integration in an emergency?

Practical Assessment

1. Deploy to staging
2. Issue a test credential
3. Troubleshoot a simulated issue
4. Perform a rollback

Resources

Internal

• Runbook: docs/operations/ENTRA_VERIFIEDID_RUNBOOK.md
• Troubleshooting: See runbook troubleshooting section
• On-call procedures: [Contact Information]

External

• Microsoft Entra VerifiedID Docs
• Azure Portal
• Azure Support

Training Schedule

Recommended Training Plan

• Week 1: Architecture and Deployment (2 hours)
• Week 2: Operations and Monitoring (2 hours)
• Week 3: Troubleshooting and Emergencies (2 hours)
• Week 4: Assessment and Certification (1 hour)

Follow-Up

• Monthly review sessions
• Quarterly updates on new features
• Annual recertification

Questions & Answers

Common Questions

Q: What happens if Entra API is down? A: The integration will retry automatically. If all retries fail, errors are logged and metrics are updated. Consider disabling integration if outage is prolonged.

Q: How do we rotate client secrets? A: Create new secret in Azure Portal, update in Key Vault, restart service. See runbook for detailed steps.

Q: Can we use multiple credential types? A: Yes! Configure ENTRA_MANIFESTS environment variable with JSON mapping. Use manifestName parameter in API calls.

Q: How do we monitor success rates? A: Use Grafana dashboard or Prometheus queries. Alert on success rate < 95%.

Certification

To be certified on Entra VerifiedID operations, team members must:

1. Complete all training modules
2. Pass knowledge check (80% or higher)
3. Successfully complete practical assessment
4. Demonstrate ability to troubleshoot common issues

---

Training Version: 1.0 Last Updated: [Current Date] Next Review: [Date + 3 months]