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:

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:

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

const client = new EntraVerifiedIDClient({
  // ...
  logoUri: 'https://example.com/logo.svg', // May not work
});

Configuration

In Code

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

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

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:

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

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

const client = new EntraVerifiedIDClient({
  // ...
  logoUri: 'https://cdn.theorder.org/images/credential-logo.png',
  backgroundColor: '#000000',
  textColor: '#ffffff',
});

Example 3: Multiple Credential Types

// 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:

pnpm add sharp

Or use external tools:

• ImageMagick
• Inkscape
• Online converters

References

• Entra VerifiedID Display Definitions
• Image Format Recommendations

---

Last Updated: [Current Date] SVG Support: ✅ Supported with automatic PNG conversion