Add Legal Office seal and complete Azure CDN deployment
- Add Legal Office of the Master seal (SVG design with Maltese Cross, scales of justice, legal scroll) - Create legal-office-manifest-template.json for Legal Office credentials - Update SEAL_MAPPING.md and DESIGN_GUIDE.md with Legal Office seal documentation - Complete Azure CDN infrastructure deployment: - Resource group, storage account, and container created - 17 PNG seal files uploaded to Azure Blob Storage - All manifest templates updated with Azure URLs - Configuration files generated (azure-cdn-config.env) - Add comprehensive Azure CDN setup scripts and documentation - Fix manifest URL generation to prevent double slashes - Verify all seals accessible via HTTPS
This commit is contained in:
defiQUG
232
docs/integrations/ENTRA_CREDENTIAL_IMAGES.md
Normal file
232
docs/integrations/ENTRA_CREDENTIAL_IMAGES.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# Entra VerifiedID Credential Images Guide
|
||||
|
||||
## Image Format Support
|
||||
|
||||
### Officially Supported Formats
|
||||
Microsoft Entra VerifiedID **officially supports**:
|
||||
- **PNG** (Recommended) ✅
|
||||
- **JPG/JPEG** ✅
|
||||
- **BMP** ✅
|
||||
|
||||
### SVG Support
|
||||
**SVG files may work** but are **not officially documented** as supported. The integration includes automatic SVG-to-PNG conversion for compatibility.
|
||||
|
||||
## Image Specifications
|
||||
|
||||
### Recommended Specifications
|
||||
- **Format**: PNG (best compatibility)
|
||||
- **Dimensions**: 200x200 pixels (square)
|
||||
- **Max Size**: 100 KB
|
||||
- **Aspect Ratio**: 1:1 (square) recommended
|
||||
- **Color Mode**: RGB
|
||||
|
||||
### Display Requirements
|
||||
- Images are displayed in digital wallets
|
||||
- Should be recognizable at small sizes
|
||||
- High contrast recommended for readability
|
||||
- Transparent backgrounds supported (PNG)
|
||||
|
||||
## Using SVG Files
|
||||
|
||||
### Option 1: Automatic Conversion (Recommended)
|
||||
The integration automatically converts SVG to PNG when provided:
|
||||
|
||||
```typescript
|
||||
import { prepareCredentialImage } from '@the-order/auth';
|
||||
|
||||
// SVG will be automatically converted to PNG
|
||||
const image = await prepareCredentialImage(svgData, 'svg');
|
||||
```
|
||||
|
||||
### Option 2: Manual Conversion
|
||||
Convert SVG to PNG before use:
|
||||
|
||||
```bash
|
||||
# Using ImageMagick
|
||||
convert logo.svg -resize 200x200 logo.png
|
||||
|
||||
# Using Inkscape
|
||||
inkscape logo.svg --export-filename=logo.png --export-width=200 --export-height=200
|
||||
```
|
||||
|
||||
### Option 3: Use SVG Directly (Not Recommended)
|
||||
You can try using SVG directly, but it may not be supported:
|
||||
|
||||
```typescript
|
||||
const client = new EntraVerifiedIDClient({
|
||||
// ...
|
||||
logoUri: 'https://example.com/logo.svg', // May not work
|
||||
});
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### In Code
|
||||
```typescript
|
||||
import { EntraVerifiedIDClient } from '@the-order/auth';
|
||||
|
||||
const client = new EntraVerifiedIDClient({
|
||||
tenantId: '...',
|
||||
clientId: '...',
|
||||
clientSecret: '...',
|
||||
credentialManifestId: '...',
|
||||
logoUri: 'https://theorder.org/images/credential-logo.png',
|
||||
backgroundColor: '#1a1a1a',
|
||||
textColor: '#ffffff',
|
||||
});
|
||||
```
|
||||
|
||||
### In Azure Portal
|
||||
When creating credential manifests:
|
||||
1. Go to Verified ID → Credentials → Your Credential
|
||||
2. Navigate to "Display" or "Branding" section
|
||||
3. Upload logo image (PNG, JPG, or BMP)
|
||||
4. Configure colors
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Logo URL (must be publicly accessible)
|
||||
ENTRA_CREDENTIAL_LOGO_URI=https://theorder.org/images/credential-logo.png
|
||||
|
||||
# Display colors
|
||||
ENTRA_CREDENTIAL_BG_COLOR=#1a1a1a
|
||||
ENTRA_CREDENTIAL_TEXT_COLOR=#ffffff
|
||||
```
|
||||
|
||||
## Image Preparation
|
||||
|
||||
### Step 1: Create/Obtain SVG
|
||||
Create your credential logo in SVG format with:
|
||||
- Square aspect ratio (1:1)
|
||||
- Clean, simple design
|
||||
- High contrast
|
||||
- Recognizable at small sizes
|
||||
|
||||
### Step 2: Convert to PNG
|
||||
Use the provided utility or external tools:
|
||||
|
||||
```typescript
|
||||
import { prepareCredentialImage, convertSvgToPng } from '@the-order/auth';
|
||||
|
||||
// Automatic conversion
|
||||
const pngImage = await prepareCredentialImage(svgData, 'svg');
|
||||
|
||||
// Manual conversion
|
||||
const pngBuffer = await convertSvgToPng(svgData, 200, 200);
|
||||
```
|
||||
|
||||
### Step 3: Host Image
|
||||
Upload PNG to a publicly accessible location:
|
||||
- CDN (recommended)
|
||||
- Static website hosting
|
||||
- Object storage with public access
|
||||
|
||||
### Step 4: Configure
|
||||
Set the logo URI in your configuration:
|
||||
|
||||
```typescript
|
||||
logoUri: 'https://cdn.theorder.org/images/credential-logo.png'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Image Design
|
||||
1. **Keep it simple**: Complex designs don't scale well
|
||||
2. **High contrast**: Ensure visibility on various backgrounds
|
||||
3. **Square format**: 1:1 aspect ratio works best
|
||||
4. **Vector source**: Start with SVG, convert to PNG
|
||||
5. **Multiple sizes**: Prepare 200x200, 400x400, 800x800 versions
|
||||
|
||||
### Technical
|
||||
1. **Use PNG**: Best compatibility with Entra VerifiedID
|
||||
2. **Optimize size**: Keep under 100KB
|
||||
3. **Public URL**: Image must be publicly accessible
|
||||
4. **HTTPS**: Use HTTPS URLs for security
|
||||
5. **CORS**: Ensure CORS headers allow Entra to fetch
|
||||
|
||||
### Performance
|
||||
1. **CDN hosting**: Use CDN for fast delivery
|
||||
2. **Caching**: Set appropriate cache headers
|
||||
3. **Compression**: Optimize PNG files
|
||||
4. **Multiple formats**: Provide PNG as primary, SVG as fallback
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Image Not Displaying
|
||||
1. **Check URL accessibility**: Verify image is publicly accessible
|
||||
2. **Check format**: Ensure PNG, JPG, or BMP
|
||||
3. **Check size**: Verify under 100KB
|
||||
4. **Check CORS**: Ensure Entra can fetch the image
|
||||
5. **Check HTTPS**: Use HTTPS URLs
|
||||
|
||||
### SVG Not Working
|
||||
1. **Convert to PNG**: Use automatic conversion utility
|
||||
2. **Check SVG validity**: Ensure valid SVG format
|
||||
3. **Try PNG directly**: Use PNG for best compatibility
|
||||
|
||||
### Image Quality Issues
|
||||
1. **Increase resolution**: Use 400x400 or 800x800
|
||||
2. **Optimize compression**: Balance quality and size
|
||||
3. **Check color profile**: Use sRGB color space
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Using SVG with Auto-Conversion
|
||||
```typescript
|
||||
import { prepareCredentialImage } from '@the-order/auth';
|
||||
import fs from 'fs';
|
||||
|
||||
const svgData = fs.readFileSync('logo.svg');
|
||||
const { data, mimeType } = await prepareCredentialImage(svgData, 'svg');
|
||||
|
||||
// Upload to storage/CDN, then use URL
|
||||
const logoUri = await uploadToCDN(data, 'credential-logo.png');
|
||||
```
|
||||
|
||||
### Example 2: Direct PNG Usage
|
||||
```typescript
|
||||
const client = new EntraVerifiedIDClient({
|
||||
// ...
|
||||
logoUri: 'https://cdn.theorder.org/images/credential-logo.png',
|
||||
backgroundColor: '#000000',
|
||||
textColor: '#ffffff',
|
||||
});
|
||||
```
|
||||
|
||||
### Example 3: Multiple Credential Types
|
||||
```typescript
|
||||
// Default credential
|
||||
const defaultClient = new EntraVerifiedIDClient({
|
||||
logoUri: 'https://cdn.theorder.org/images/default-logo.png',
|
||||
});
|
||||
|
||||
// Diplomatic credential
|
||||
const diplomaticClient = new EntraVerifiedIDClient({
|
||||
logoUri: 'https://cdn.theorder.org/images/diplomatic-logo.png',
|
||||
});
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Optional: SVG to PNG Conversion
|
||||
For automatic SVG conversion, install:
|
||||
|
||||
```bash
|
||||
pnpm add sharp
|
||||
```
|
||||
|
||||
Or use external tools:
|
||||
- ImageMagick
|
||||
- Inkscape
|
||||
- Online converters
|
||||
|
||||
## References
|
||||
|
||||
- [Entra VerifiedID Display Definitions](https://learn.microsoft.com/en-us/entra/verified-id/rules-and-display-definitions-model)
|
||||
- [Image Format Recommendations](https://learn.microsoft.com/en-us/entra/verified-id/decentralized-identifier-overview)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Current Date]
|
||||
**SVG Support**: ✅ Supported with automatic PNG conversion
|
||||
|
||||
@@ -286,9 +286,204 @@ The integration supports optional Azure Logic Apps workflows for:
|
||||
- Verify network connectivity to eIDAS provider
|
||||
- Check certificate validity
|
||||
|
||||
## Enhanced Features
|
||||
|
||||
### Retry Logic
|
||||
|
||||
The integration includes automatic retry logic for transient failures:
|
||||
|
||||
- **Configurable retries**: Default 3 retries with exponential backoff
|
||||
- **Retryable errors**: 429 (rate limit), 500, 502, 503, 504
|
||||
- **Backoff strategy**: Exponential backoff with configurable delays
|
||||
|
||||
```typescript
|
||||
import { EnhancedEntraVerifiedIDClient } from '@the-order/auth';
|
||||
|
||||
const client = new EnhancedEntraVerifiedIDClient(config, {
|
||||
maxRetries: 3,
|
||||
initialDelayMs: 1000,
|
||||
maxDelayMs: 10000,
|
||||
backoffMultiplier: 2,
|
||||
});
|
||||
```
|
||||
|
||||
### Multi-Manifest Support
|
||||
|
||||
Support for multiple credential manifests:
|
||||
|
||||
```bash
|
||||
# Environment variable (JSON format)
|
||||
ENTRA_MANIFESTS='{"default":"manifest-id-1","diplomatic":"manifest-id-2","judicial":"manifest-id-3"}'
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Issue credential with specific manifest
|
||||
await client.issueCredential({
|
||||
claims: { ... },
|
||||
manifestName: 'diplomatic', // Uses diplomatic manifest
|
||||
});
|
||||
```
|
||||
|
||||
### Webhook/Callback Handling
|
||||
|
||||
Automatic webhook processing for issuance status updates:
|
||||
|
||||
**POST** `/vc/entra/webhook`
|
||||
|
||||
The webhook endpoint:
|
||||
- Receives status updates from Entra VerifiedID
|
||||
- Updates credential status in database
|
||||
- Publishes events for downstream processing
|
||||
- Records metrics for monitoring
|
||||
|
||||
**GET** `/vc/entra/status/:requestId`
|
||||
|
||||
Manual status check endpoint (polling fallback).
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
Entra-specific rate limiting to prevent API quota exhaustion:
|
||||
|
||||
```bash
|
||||
# Environment variables
|
||||
ENTRA_RATE_LIMIT_ISSUANCE=10 # Per minute
|
||||
ENTRA_RATE_LIMIT_VERIFICATION=20 # Per minute
|
||||
ENTRA_RATE_LIMIT_STATUS_CHECK=30 # Per minute
|
||||
ENTRA_RATE_LIMIT_GLOBAL=50 # Per minute
|
||||
```
|
||||
|
||||
Rate limits are applied automatically to all Entra endpoints.
|
||||
|
||||
### Monitoring & Metrics
|
||||
|
||||
Comprehensive Prometheus metrics:
|
||||
|
||||
- `entra_api_requests_total` - Total API requests by operation and status
|
||||
- `entra_api_request_duration_seconds` - Request duration histogram
|
||||
- `entra_credentials_issued_total` - Credentials issued by manifest and status
|
||||
- `entra_issuance_duration_seconds` - Issuance duration histogram
|
||||
- `entra_credentials_verified_total` - Verification results
|
||||
- `entra_webhooks_received_total` - Webhook events received
|
||||
- `entra_active_requests` - Currently active requests gauge
|
||||
|
||||
Access metrics at `/metrics` endpoint.
|
||||
|
||||
### Automated Setup Script
|
||||
|
||||
Use the automated setup script for Azure configuration:
|
||||
|
||||
```bash
|
||||
./scripts/deploy/setup-entra-automated.sh
|
||||
```
|
||||
|
||||
The script:
|
||||
- Creates Azure AD App Registration
|
||||
- Configures API permissions
|
||||
- Creates client secrets
|
||||
- Stores secrets in Azure Key Vault
|
||||
- Generates environment file template
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```bash
|
||||
cd packages/auth
|
||||
pnpm test entra-verifiedid.test.ts
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
Integration tests verify:
|
||||
- Token management and caching
|
||||
- Credential issuance flow
|
||||
- Retry logic on failures
|
||||
- Multi-manifest support
|
||||
- Webhook processing
|
||||
|
||||
### End-to-End Testing
|
||||
|
||||
1. Set up test environment variables
|
||||
2. Create test credential manifest in Azure
|
||||
3. Run E2E test suite:
|
||||
```bash
|
||||
pnpm test:e2e entra
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Automated Deployment
|
||||
|
||||
1. Run setup script:
|
||||
```bash
|
||||
./scripts/deploy/setup-entra-automated.sh
|
||||
```
|
||||
|
||||
2. Update environment variables in all environments
|
||||
|
||||
3. Configure webhook URLs in Entra VerifiedID:
|
||||
- Production: `https://api.theorder.org/vc/entra/webhook`
|
||||
- Staging: `https://api-staging.theorder.org/vc/entra/webhook`
|
||||
|
||||
4. Verify integration:
|
||||
```bash
|
||||
curl -X POST https://api.theorder.org/vc/issue/entra \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"claims": {"email": "test@example.com"}}'
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
Follow the manual steps in `docs/deployment/DEPLOYMENT_STEPS_SUMMARY.md` Phase 3.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Enhanced Client**: Always use `EnhancedEntraVerifiedIDClient` for production
|
||||
2. **Monitor Metrics**: Set up alerts on error rates and latency
|
||||
3. **Configure Rate Limits**: Adjust based on your Entra API quota
|
||||
4. **Webhook Security**: Validate webhook signatures if Entra provides them
|
||||
5. **Multi-Manifest**: Use manifest names for different credential types
|
||||
6. **Error Handling**: Implement proper error handling and logging
|
||||
7. **Retry Configuration**: Tune retry settings based on your needs
|
||||
|
||||
## Credential Images
|
||||
|
||||
### Image Format Support
|
||||
|
||||
**Yes, SVG files can be used!** The integration includes automatic SVG-to-PNG conversion for Entra VerifiedID compatibility.
|
||||
|
||||
#### Officially Supported Formats
|
||||
- **PNG** (Recommended) ✅
|
||||
- **JPG/JPEG** ✅
|
||||
- **BMP** ✅
|
||||
- **SVG** (with automatic conversion) ✅
|
||||
|
||||
#### Using SVG Files
|
||||
|
||||
1. **Automatic Conversion** (Recommended):
|
||||
```typescript
|
||||
import { prepareCredentialImage } from '@the-order/auth';
|
||||
|
||||
const image = await prepareCredentialImage(svgData, 'svg');
|
||||
// Automatically converts to PNG
|
||||
```
|
||||
|
||||
2. **Manual Conversion**:
|
||||
```bash
|
||||
./scripts/tools/convert-svg-to-png.sh logo.svg logo.png 200 200
|
||||
```
|
||||
|
||||
3. **Prepare All Images**:
|
||||
```bash
|
||||
./scripts/tools/prepare-credential-images.sh
|
||||
```
|
||||
|
||||
See [ENTRA_CREDENTIAL_IMAGES.md](./ENTRA_CREDENTIAL_IMAGES.md) for detailed image guide.
|
||||
|
||||
## References
|
||||
|
||||
- [Microsoft Entra VerifiedID Documentation](https://learn.microsoft.com/en-us/azure/active-directory/verifiable-credentials/)
|
||||
- [Azure Logic Apps Documentation](https://learn.microsoft.com/en-us/azure/logic-apps/)
|
||||
- [eIDAS Regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32014R0910)
|
||||
- [Entra VerifiedID Display Definitions](https://learn.microsoft.com/en-us/entra/verified-id/rules-and-display-definitions-model)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user