feat: comprehensive project structure improvements and Cloud for Sovereignty landing zone
- Add Cloud for Sovereignty landing zone architecture and deployment - Implement complete legal document management system - Reorganize documentation with improved navigation - Add infrastructure improvements (Dockerfiles, K8s, monitoring) - Add operational improvements (graceful shutdown, rate limiting, caching) - Create comprehensive project structure documentation - Add Azure deployment automation scripts - Improve repository navigation and organization
This commit is contained in:
defiQUG
232
docs/integrations/entra-verifiedid/credential-images.md
Normal file
232
docs/integrations/entra-verifiedid/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
|
||||
|
||||
Reference in New Issue
Block a user