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**
   ```bash
   ./scripts/deploy/setup-entra-automated.sh
   ```

2. **Environment Setup**
   ```bash
   ./scripts/deploy/configure-env-dev.sh
   ```

3. **Staging Deployment**
   ```bash
   ./scripts/deploy/deploy-staging.sh
   ```

4. **Production Deployment**
   ```bash
   ./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
```bash
# 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
```bash
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](../deployment/ENTRA_VERIFIEDID_DEPLOYMENT_CHECKLIST.md)
- [Operational Runbook](../operations/ENTRA_VERIFIEDID_RUNBOOK.md)
- [Integration Guide](../integrations/MICROSOFT_ENTRA_VERIFIEDID.md)

### 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](https://learn.microsoft.com/en-us/azure/active-directory/verifiable-credentials/)
- [Azure Portal](https://portal.azure.com)
- [Azure Support](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade)

## 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]