the_order/docs/integrations/entra-verifiedid/credential-images.md

# 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