docs: archive entra materials and simplify deployment docs
This commit is contained in:
defiQUG
@@ -1,264 +0,0 @@
|
||||
# Connector Status - Microsoft Entra VerifiedID & Azure Logic Apps
|
||||
|
||||
**Last Updated**: 2024-12-28
|
||||
**Status**: ✅ All Connectors Implemented
|
||||
|
||||
---
|
||||
|
||||
## ✅ Microsoft Entra VerifiedID Connector
|
||||
|
||||
**Status**: Fully Implemented
|
||||
**Package**: `@the-order/auth`
|
||||
**File**: `packages/auth/src/entra-verifiedid.ts`
|
||||
|
||||
### Features Implemented
|
||||
- ✅ OAuth2 client credentials authentication
|
||||
- ✅ Automatic access token caching and refresh
|
||||
- ✅ Verifiable credential issuance
|
||||
- ✅ Verifiable credential verification
|
||||
- ✅ Presentation request creation
|
||||
- ✅ QR code generation for mobile wallets
|
||||
- ✅ Issuance status checking
|
||||
|
||||
### API Integration
|
||||
- ✅ Microsoft Entra VerifiedID REST API v1.0
|
||||
- ✅ Token endpoint: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`
|
||||
- ✅ VerifiedID endpoint: `https://verifiedid.did.msidentity.com/v1.0/{tenantId}`
|
||||
|
||||
### Environment Variables
|
||||
- ✅ `ENTRA_TENANT_ID` - Azure AD tenant ID
|
||||
- ✅ `ENTRA_CLIENT_ID` - Azure AD application (client) ID
|
||||
- ✅ `ENTRA_CLIENT_SECRET` - Azure AD client secret
|
||||
- ✅ `ENTRA_CREDENTIAL_MANIFEST_ID` - Credential manifest ID
|
||||
|
||||
### Service Integration
|
||||
- ✅ Integrated into Identity Service
|
||||
- ✅ API endpoints: `/vc/issue/entra`, `/vc/verify/entra`
|
||||
- ✅ Swagger documentation included
|
||||
|
||||
---
|
||||
|
||||
## ✅ Azure Logic Apps Connector
|
||||
|
||||
**Status**: Fully Implemented
|
||||
**Package**: `@the-order/auth`
|
||||
**File**: `packages/auth/src/azure-logic-apps.ts`
|
||||
|
||||
### Features Implemented
|
||||
- ✅ Workflow trigger support
|
||||
- ✅ Access key authentication
|
||||
- ✅ Managed identity authentication (via @azure/identity)
|
||||
- ✅ Pre-configured workflow triggers:
|
||||
- ✅ eIDAS verification workflows
|
||||
- ✅ VC issuance workflows
|
||||
- ✅ Document processing workflows
|
||||
|
||||
### Authentication Methods
|
||||
- ✅ Access key authentication
|
||||
- ✅ Azure Managed Identity authentication
|
||||
- ✅ Dynamic import of @azure/identity (optional dependency)
|
||||
|
||||
### Environment Variables
|
||||
- ✅ `AZURE_LOGIC_APPS_WORKFLOW_URL` - Logic Apps workflow URL
|
||||
- ✅ `AZURE_LOGIC_APPS_ACCESS_KEY` - Access key (if not using managed identity)
|
||||
- ✅ `AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID` - Managed identity client ID
|
||||
|
||||
### Service Integration
|
||||
- ✅ Integrated into Identity Service
|
||||
- ✅ Integrated into eIDAS bridge
|
||||
- ✅ Optional integration (gracefully degrades if not configured)
|
||||
|
||||
---
|
||||
|
||||
## ✅ eIDAS to Microsoft Entra VerifiedID Bridge
|
||||
|
||||
**Status**: Fully Implemented
|
||||
**Package**: `@the-order/auth`
|
||||
**File**: `packages/auth/src/eidas-entra-bridge.ts`
|
||||
|
||||
### Features Implemented
|
||||
- ✅ eIDAS signature verification
|
||||
- ✅ Automatic credential issuance via Entra VerifiedID after eIDAS verification
|
||||
- ✅ Certificate chain validation
|
||||
- ✅ Certificate validity period checking
|
||||
- ✅ Optional Logic Apps workflow integration
|
||||
- ✅ Two-step process: verify then issue
|
||||
|
||||
### Flow
|
||||
1. ✅ Request eIDAS signature for document
|
||||
2. ✅ Verify eIDAS signature and certificate
|
||||
3. ✅ Extract certificate information
|
||||
4. ✅ Issue verifiable credential via Entra VerifiedID with eIDAS claims
|
||||
5. ✅ (Optional) Trigger Logic Apps workflow
|
||||
|
||||
### Service Integration
|
||||
- ✅ Integrated into Identity Service
|
||||
- ✅ API endpoint: `/eidas/verify-and-issue`
|
||||
- ✅ Swagger documentation included
|
||||
|
||||
### Environment Variables
|
||||
- ✅ All eIDAS variables (`EIDAS_PROVIDER_URL`, `EIDAS_API_KEY`)
|
||||
- ✅ All Entra VerifiedID variables
|
||||
- ✅ All Azure Logic Apps variables (optional)
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints Summary
|
||||
|
||||
### Identity Service Endpoints
|
||||
|
||||
#### Microsoft Entra VerifiedID
|
||||
- ✅ `POST /vc/issue/entra` - Issue credential via Entra VerifiedID
|
||||
- ✅ `POST /vc/verify/entra` - Verify credential via Entra VerifiedID
|
||||
|
||||
#### eIDAS Bridge
|
||||
- ✅ `POST /eidas/verify-and-issue` - Verify eIDAS and issue credential via Entra
|
||||
|
||||
#### Existing Endpoints (Still Available)
|
||||
- ✅ `POST /vc/issue` - Issue credential via KMS (original method)
|
||||
- ✅ `POST /vc/verify` - Verify credential (original method)
|
||||
- ✅ `POST /sign` - Sign document via KMS
|
||||
|
||||
---
|
||||
|
||||
## Recommended Additional Connectors
|
||||
|
||||
### High Priority
|
||||
|
||||
1. **Azure Key Vault Connector**
|
||||
- **Purpose**: Secure secret storage
|
||||
- **Status**: Not yet implemented
|
||||
- **Priority**: High
|
||||
- **Use Case**: Store Entra client secrets, eIDAS API keys securely
|
||||
|
||||
2. **Azure Service Bus / Event Grid Connector**
|
||||
- **Purpose**: Event-driven architecture
|
||||
- **Status**: Not yet implemented
|
||||
- **Priority**: High
|
||||
- **Use Case**: Async workflow processing, event notifications
|
||||
|
||||
### Medium Priority
|
||||
|
||||
3. **Azure Active Directory B2C Connector**
|
||||
- **Purpose**: User authentication
|
||||
- **Status**: Not yet implemented
|
||||
- **Priority**: Medium
|
||||
- **Use Case**: User sign-up and sign-in flows
|
||||
|
||||
4. **Azure Monitor / Application Insights Connector**
|
||||
- **Purpose**: Enhanced observability
|
||||
- **Status**: Partially implemented (OpenTelemetry exists)
|
||||
- **Priority**: Medium
|
||||
- **Use Case**: Enhanced monitoring for Entra VerifiedID operations
|
||||
|
||||
### Low Priority
|
||||
|
||||
5. **Azure Storage (Blob) Connector**
|
||||
- **Purpose**: Document storage alternative
|
||||
- **Status**: Not yet implemented (S3/GCS supported)
|
||||
- **Priority**: Low
|
||||
- **Use Case**: Azure-native document storage
|
||||
|
||||
6. **Azure Functions Connector**
|
||||
- **Purpose**: Serverless function integration
|
||||
- **Status**: Not yet implemented
|
||||
- **Priority**: Low
|
||||
- **Use Case**: Serverless workflow steps
|
||||
|
||||
---
|
||||
|
||||
## Testing Status
|
||||
|
||||
### Unit Tests
|
||||
- ⚠️ Not yet implemented
|
||||
- **Recommended**: Add tests for:
|
||||
- EntraVerifiedIDClient
|
||||
- AzureLogicAppsClient
|
||||
- EIDASToEntraBridge
|
||||
|
||||
### Integration Tests
|
||||
- ⚠️ Not yet implemented
|
||||
- **Recommended**: Add tests for:
|
||||
- Identity service Entra endpoints
|
||||
- eIDAS bridge flow
|
||||
- Logic Apps workflow triggers
|
||||
|
||||
### Manual Testing
|
||||
- ✅ Code compiles successfully
|
||||
- ✅ Type checking passes
|
||||
- ⚠️ Requires Azure setup for full testing
|
||||
|
||||
---
|
||||
|
||||
## Configuration Checklist
|
||||
|
||||
### Microsoft Entra VerifiedID Setup
|
||||
- [ ] Create Azure AD app registration
|
||||
- [ ] Configure API permissions
|
||||
- [ ] Create client secret
|
||||
- [ ] Create credential manifest in Azure Portal
|
||||
- [ ] Set environment variables:
|
||||
- [ ] `ENTRA_TENANT_ID`
|
||||
- [ ] `ENTRA_CLIENT_ID`
|
||||
- [ ] `ENTRA_CLIENT_SECRET`
|
||||
- [ ] `ENTRA_CREDENTIAL_MANIFEST_ID`
|
||||
|
||||
### eIDAS Provider Setup
|
||||
- [ ] Configure eIDAS provider
|
||||
- [ ] Obtain API key
|
||||
- [ ] Set environment variables:
|
||||
- [ ] `EIDAS_PROVIDER_URL`
|
||||
- [ ] `EIDAS_API_KEY`
|
||||
|
||||
### Azure Logic Apps Setup (Optional)
|
||||
- [ ] Create Logic App workflow
|
||||
- [ ] Configure trigger endpoints
|
||||
- [ ] Set environment variables:
|
||||
- [ ] `AZURE_LOGIC_APPS_WORKFLOW_URL`
|
||||
- [ ] `AZURE_LOGIC_APPS_ACCESS_KEY` OR
|
||||
- [ ] `AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID`
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### ✅ Implemented
|
||||
- ✅ OAuth2 client credentials flow
|
||||
- ✅ Automatic token refresh
|
||||
- ✅ Secure secret handling (via environment variables)
|
||||
- ✅ Certificate chain validation for eIDAS
|
||||
- ✅ Validity period checking
|
||||
|
||||
### ⚠️ Recommended
|
||||
- ⚠️ Store secrets in Azure Key Vault (not yet implemented)
|
||||
- ⚠️ Use managed identity when possible
|
||||
- ⚠️ Implement rate limiting for external API calls
|
||||
- ⚠️ Add retry logic with exponential backoff
|
||||
- ⚠️ Implement circuit breaker pattern
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- ✅ [Microsoft Entra VerifiedID Integration Guide](./MICROSOFT_ENTRA_VERIFIEDID.md)
|
||||
- ✅ [Integration Summary](./INTEGRATION_SUMMARY.md)
|
||||
- ✅ [Environment Variables Documentation](../configuration/ENVIRONMENT_VARIABLES.md)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**All requested connectors are fully implemented:**
|
||||
|
||||
1. ✅ **Microsoft Entra VerifiedID Connector** - Complete
|
||||
2. ✅ **Azure Logic Apps Connector** - Complete
|
||||
3. ✅ **eIDAS to Entra Bridge** - Complete
|
||||
4. ✅ **eIDAS verification connected for issuance through Entra VerifiedID** - Complete
|
||||
|
||||
**Next Steps:**
|
||||
1. Configure Azure resources (app registration, credential manifest)
|
||||
2. Set environment variables
|
||||
3. Test integration end-to-end
|
||||
4. Add comprehensive tests
|
||||
5. Consider additional connectors (Key Vault, Service Bus, etc.)
|
||||
|
||||
@@ -1,262 +0,0 @@
|
||||
# Integration Summary
|
||||
|
||||
This document provides an overview of all external integrations in The Order platform.
|
||||
|
||||
## EU Laissez-Passer (EU-LP) 📋
|
||||
|
||||
**Status**: Specification Documented
|
||||
**Type**: Reference Documentation
|
||||
**Documentation**: [EU_LAISSEZ_PASSER_SPECIFICATION.md](./EU_LAISSEZ_PASSER_SPECIFICATION.md)
|
||||
|
||||
### Overview
|
||||
Technical specification for EU diplomatic travel document (Council Regulation EU 1417/2013). Meets ICAO Doc 9303 standards for eMRTD.
|
||||
|
||||
### Key Features
|
||||
- TD3 format (88mm × 125mm, 48 pages)
|
||||
- Contactless IC chip (eMRTD) with biometrics
|
||||
- ICAO-compliant MRZ (2 lines × 44 chars)
|
||||
- EU-LP PKI (CSCA operated by European Commission JRC)
|
||||
- Extended Access Control (EAC) support
|
||||
- Security features: watermarks, OVI, UV/IR, intaglio printing
|
||||
|
||||
### Integration Points
|
||||
- Identity Service (document verification)
|
||||
- Diplomatic Credential Management
|
||||
- Document validation systems
|
||||
- Certificate chain validation (EU-LP CSCA)
|
||||
|
||||
### Standards Compliance
|
||||
- ICAO Doc 9303 (Parts 3-5, 10-12)
|
||||
- EU Regulation 1417/2013
|
||||
- Security standards equivalent to Member-State passports
|
||||
|
||||
### Implementation Status
|
||||
- [x] Technical specification documented
|
||||
- [ ] MRZ parser implementation
|
||||
- [ ] Chip reading integration
|
||||
- [ ] Certificate validation (CSCA)
|
||||
- [ ] Biometric verification
|
||||
- [ ] Security feature validation
|
||||
|
||||
## Microsoft Entra VerifiedID ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: [MICROSOFT_ENTRA_VERIFIEDID.md](./MICROSOFT_ENTRA_VERIFIEDID.md)
|
||||
|
||||
### Features
|
||||
- ✅ Verifiable credential issuance
|
||||
- ✅ Verifiable credential verification
|
||||
- ✅ Presentation request creation
|
||||
- ✅ QR code generation for mobile wallet integration
|
||||
- ✅ OAuth2 client credentials flow for authentication
|
||||
- ✅ Automatic token caching and refresh
|
||||
|
||||
### API Endpoints
|
||||
- `POST /vc/issue/entra` - Issue credential via Entra VerifiedID
|
||||
- `POST /vc/verify/entra` - Verify credential via Entra VerifiedID
|
||||
- `POST /eidas/verify-and-issue` - eIDAS verification with Entra issuance
|
||||
|
||||
## Azure Logic Apps ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: [MICROSOFT_ENTRA_VERIFIEDID.md](./MICROSOFT_VERIFIEDID.md) (see Logic Apps section)
|
||||
|
||||
### Features
|
||||
- ✅ Workflow trigger support
|
||||
- ✅ Access key authentication
|
||||
- ✅ Managed identity authentication (via @azure/identity)
|
||||
- ✅ Pre-configured triggers for:
|
||||
- eIDAS verification workflows
|
||||
- VC issuance workflows
|
||||
- Document processing workflows
|
||||
|
||||
### Usage
|
||||
```typescript
|
||||
import { AzureLogicAppsClient } from '@the-order/auth';
|
||||
|
||||
const client = new AzureLogicAppsClient({
|
||||
workflowUrl: process.env.AZURE_LOGIC_APPS_WORKFLOW_URL!,
|
||||
accessKey: process.env.AZURE_LOGIC_APPS_ACCESS_KEY,
|
||||
});
|
||||
|
||||
await client.triggerEIDASVerification(documentId, userId, eidasProviderUrl);
|
||||
```
|
||||
|
||||
## eIDAS to Microsoft Entra VerifiedID Bridge ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: [MICROSOFT_ENTRA_VERIFIEDID.md](./MICROSOFT_ENTRA_VERIFIEDID.md) (see eIDAS Bridge section)
|
||||
|
||||
### Features
|
||||
- ✅ eIDAS signature verification
|
||||
- ✅ Automatic credential issuance via Entra VerifiedID after eIDAS verification
|
||||
- ✅ Certificate chain validation
|
||||
- ✅ Validity period checking
|
||||
- ✅ Optional Logic Apps workflow integration
|
||||
|
||||
### Flow
|
||||
1. Request eIDAS signature for document
|
||||
2. Verify eIDAS signature and certificate
|
||||
3. Extract certificate information
|
||||
4. Issue verifiable credential via Entra VerifiedID with eIDAS claims
|
||||
5. (Optional) Trigger Logic Apps workflow
|
||||
|
||||
## eIDAS Provider ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: See auth package README
|
||||
|
||||
### Features
|
||||
- ✅ Document signing via eIDAS provider
|
||||
- ✅ Signature verification
|
||||
- ✅ Certificate chain validation
|
||||
- ✅ Validity period checking
|
||||
|
||||
## OIDC/OAuth2 ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: See auth package README
|
||||
|
||||
### Features
|
||||
- ✅ Authorization URL generation
|
||||
- ✅ Authorization code to token exchange
|
||||
- ✅ Token introspection
|
||||
- ✅ User info retrieval
|
||||
|
||||
## DID (Decentralized Identifiers) ✅
|
||||
|
||||
**Status**: Fully Integrated
|
||||
**Package**: `@the-order/auth`
|
||||
**Documentation**: See auth package README
|
||||
|
||||
### Supported Methods
|
||||
- ✅ `did:web` - Web-based DID resolution
|
||||
- ✅ `did:key` - Key-based DID resolution
|
||||
|
||||
### Features
|
||||
- ✅ DID document resolution
|
||||
- ✅ Signature verification (multibase and JWK formats)
|
||||
|
||||
## Recommended Additional Integrations
|
||||
|
||||
### 1. Azure Key Vault
|
||||
- **Purpose**: Secure secret storage
|
||||
- **Status**: Not yet integrated
|
||||
- **Priority**: High
|
||||
- **Use Case**: Store Entra client secrets, eIDAS API keys
|
||||
|
||||
### 2. Azure Service Bus / Event Grid
|
||||
- **Purpose**: Event-driven architecture
|
||||
- **Status**: Not yet integrated
|
||||
- **Priority**: Medium
|
||||
- **Use Case**: Async workflow processing, event notifications
|
||||
|
||||
### 3. Azure Monitor / Application Insights
|
||||
- **Purpose**: Observability and monitoring
|
||||
- **Status**: Partially integrated (OpenTelemetry)
|
||||
- **Priority**: Medium
|
||||
- **Use Case**: Enhanced monitoring for Entra VerifiedID operations
|
||||
|
||||
### 4. Azure Active Directory B2C
|
||||
- **Purpose**: User authentication
|
||||
- **Status**: Not yet integrated
|
||||
- **Priority**: Medium
|
||||
- **Use Case**: User sign-up and sign-in flows
|
||||
|
||||
### 5. Azure Storage (Blob)
|
||||
- **Purpose**: Document storage alternative
|
||||
- **Status**: Not yet integrated (S3/GCS supported)
|
||||
- **Priority**: Low
|
||||
- **Use Case**: Azure-native document storage
|
||||
|
||||
## Integration Checklist
|
||||
|
||||
### Microsoft Entra VerifiedID
|
||||
- [x] Client implementation
|
||||
- [x] OAuth2 authentication
|
||||
- [x] Credential issuance
|
||||
- [x] Credential verification
|
||||
- [x] Presentation requests
|
||||
- [x] Environment variable configuration
|
||||
- [x] API endpoints
|
||||
- [x] Documentation
|
||||
|
||||
### Azure Logic Apps
|
||||
- [x] Client implementation
|
||||
- [x] Access key authentication
|
||||
- [x] Managed identity authentication
|
||||
- [x] Workflow triggers
|
||||
- [x] Environment variable configuration
|
||||
- [x] Documentation
|
||||
|
||||
### eIDAS Bridge
|
||||
- [x] Bridge implementation
|
||||
- [x] eIDAS verification integration
|
||||
- [x] Entra VerifiedID issuance integration
|
||||
- [x] Logic Apps integration
|
||||
- [x] API endpoints
|
||||
- [x] Documentation
|
||||
|
||||
## Configuration Requirements
|
||||
|
||||
### Required for Entra VerifiedID
|
||||
```bash
|
||||
ENTRA_TENANT_ID=your-tenant-id
|
||||
ENTRA_CLIENT_ID=your-client-id
|
||||
ENTRA_CLIENT_SECRET=your-client-secret
|
||||
ENTRA_CREDENTIAL_MANIFEST_ID=your-manifest-id
|
||||
```
|
||||
|
||||
### Required for eIDAS Bridge
|
||||
```bash
|
||||
EIDAS_PROVIDER_URL=https://your-eidas-provider.com
|
||||
EIDAS_API_KEY=your-eidas-api-key
|
||||
# Plus all Entra VerifiedID variables above
|
||||
```
|
||||
|
||||
### Required for Logic Apps
|
||||
```bash
|
||||
AZURE_LOGIC_APPS_WORKFLOW_URL=https://your-logic-app.azurewebsites.net
|
||||
# Either:
|
||||
AZURE_LOGIC_APPS_ACCESS_KEY=your-access-key
|
||||
# Or:
|
||||
AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID=your-managed-identity-client-id
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing
|
||||
1. Set up Azure AD app registration
|
||||
2. Create credential manifest in Azure Portal
|
||||
3. Configure environment variables
|
||||
4. Test credential issuance: `POST /vc/issue/entra`
|
||||
5. Test credential verification: `POST /vc/verify/entra`
|
||||
6. Test eIDAS bridge: `POST /eidas/verify-and-issue`
|
||||
|
||||
### Integration Testing
|
||||
- Unit tests for EntraVerifiedIDClient
|
||||
- Unit tests for AzureLogicAppsClient
|
||||
- Unit tests for EIDASToEntraBridge
|
||||
- Integration tests for identity service endpoints
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Client Secrets**: Store in Azure Key Vault or similar
|
||||
2. **Access Tokens**: Automatically cached and refreshed
|
||||
3. **Managed Identity**: Prefer over client secrets when possible
|
||||
4. **Certificate Validation**: Full chain validation for eIDAS
|
||||
5. **Network Security**: Use private endpoints when available
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Add Azure Key Vault integration for secret management
|
||||
2. Add comprehensive integration tests
|
||||
3. Add monitoring and alerting for Entra VerifiedID operations
|
||||
4. Add retry logic with exponential backoff
|
||||
5. Add circuit breaker pattern for external service calls
|
||||
|
||||
+14
-41
@@ -1,53 +1,26 @@
|
||||
# Integration Documentation
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Purpose**: Integration guide index
|
||||
**Last Updated**: 2026-04-16
|
||||
**Purpose**: Integration guide index for active The Order integrations
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains documentation for all external integrations used by The Order platform.
|
||||
This directory covers active integrations used by The Order platform.
|
||||
|
||||
## Available Integrations
|
||||
## Active Areas
|
||||
|
||||
### Microsoft Entra VerifiedID
|
||||
- [Entra VerifiedID Guide](entra-verifiedid/README.md) - Complete integration guide
|
||||
- Credential issuance and verification
|
||||
- Multi-manifest support
|
||||
- Webhook handling
|
||||
- Rate limiting and metrics
|
||||
### Identity
|
||||
- DID and issuer-domain based credential services
|
||||
- OIDC where configured for operator and portal flows
|
||||
|
||||
### Azure Services
|
||||
- [Azure CDN](../deployment/azure/cdn-setup.md) - CDN configuration
|
||||
- [Azure Key Vault](../../infra/terraform/key-vault.tf) - Secrets management
|
||||
- [Azure Storage](../deployment/azure/cdn-setup.md) - Object storage
|
||||
### Payments
|
||||
- Finance service integrations live under `services/finance/`
|
||||
|
||||
### Payment Gateways
|
||||
- Stripe integration (see `services/finance/`)
|
||||
- Additional providers (planned)
|
||||
### Legal and Documents
|
||||
- Legal and document-management integrations live under `docs/legal/`
|
||||
|
||||
### E-Signature Providers
|
||||
- DocuSign (planned)
|
||||
- Adobe Sign (planned)
|
||||
## Historical Material
|
||||
|
||||
### Court E-Filing
|
||||
- Federal court systems (planned)
|
||||
- State court systems (planned)
|
||||
Legacy provider integration guides have been quarantined under:
|
||||
|
||||
## Integration Documentation Structure
|
||||
|
||||
```
|
||||
integrations/
|
||||
├── README.md # This file
|
||||
└── entra-verifiedid/ # Entra VerifiedID integration
|
||||
└── README.md # Complete guide
|
||||
```
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Entra VerifiedID](entra-verifiedid/README.md) - Credential issuance
|
||||
- [Azure Deployment](../deployment/azure/) - Azure service integration
|
||||
- [Service Documentation](../../services/) - Service-specific integrations
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
- `../archive/quarantined-legacy-stack/`
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
# Entra VerifiedID Integration
|
||||
|
||||
Complete integration guide for Microsoft Entra VerifiedID credential issuance and verification.
|
||||
|
||||
## Overview
|
||||
|
||||
The Order integrates with Microsoft Entra VerifiedID for issuing and verifying verifiable credentials. This integration supports multiple credential types, custom display properties, and webhook-based event handling.
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Setup Guide](../../deployment/azure/entra-verifiedid.md)** - Deployment and configuration
|
||||
- **[Credential Images](credential-images.md)** - Image requirements and setup
|
||||
- **[Best Practices](best-practices.md)** - Implementation best practices
|
||||
- **[JSON Content Readiness](json-content-readiness.md)** - Content format requirements
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Enable Entra VerifiedID** in Azure Portal
|
||||
2. **Create Application Registration** with required permissions
|
||||
3. **Configure Credential Manifests** for each credential type
|
||||
4. **Set Environment Variables** (see deployment guide)
|
||||
5. **Deploy Services** with Entra integration
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Multi-manifest support
|
||||
- ✅ Custom credential display (logo, colors)
|
||||
- ✅ Webhook event handling
|
||||
- ✅ Retry logic with exponential backoff
|
||||
- ✅ Rate limiting
|
||||
- ✅ Prometheus metrics
|
||||
- ✅ Comprehensive error handling
|
||||
|
||||
## Credential Types
|
||||
|
||||
- **Default/Identity**: Basic member credentials
|
||||
- **Financial**: Digital Bank credentials
|
||||
- **Judicial**: ICCC credentials
|
||||
- **Diplomatic**: Diplomatic Security credentials
|
||||
- **Legal Office**: Legal Office credentials
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Deployment Guide](../../deployment/azure/entra-verifiedid.md)
|
||||
- [Operations Runbook](../../operations/ENTRA_VERIFIEDID_RUNBOOK.md)
|
||||
- [Training Materials](../../training/ENTRA_VERIFIEDID_TRAINING.md)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
@@ -1,426 +0,0 @@
|
||||
# Entra VerifiedID - Best Practices Implementation Summary
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Status**: ✅ All Best Practices Implemented
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document summarizes all best practices improvements implemented for the Entra VerifiedID integration.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Implemented Improvements
|
||||
|
||||
### 1. Enhanced Claims Type Support
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Changes:**
|
||||
- Updated `VerifiableCredentialRequest` interface to support multiple claim value types
|
||||
- Added `ClaimValue` type: `string | number | boolean | null`
|
||||
- Automatic conversion to strings for Entra VerifiedID API (which requires strings)
|
||||
|
||||
**Before:**
|
||||
```typescript
|
||||
claims: Record<string, string> // Only strings
|
||||
```
|
||||
|
||||
**After:**
|
||||
```typescript
|
||||
claims: Record<string, ClaimValue> // string | number | boolean | null
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- More flexible API - accepts native types
|
||||
- Type-safe handling
|
||||
- Automatic conversion to required format
|
||||
|
||||
**Files Modified:**
|
||||
- `packages/auth/src/entra-verifiedid.ts`
|
||||
- `packages/auth/src/eidas-entra-bridge.ts`
|
||||
- `services/identity/src/entra-integration.ts`
|
||||
|
||||
---
|
||||
|
||||
### 2. File Handling Utilities
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**New Module**: `packages/auth/src/file-utils.ts`
|
||||
|
||||
**Features:**
|
||||
- ✅ Base64 encoding/decoding
|
||||
- ✅ Base64 validation
|
||||
- ✅ MIME type detection (from buffer magic bytes and file extensions)
|
||||
- ✅ File size validation
|
||||
- ✅ File type validation
|
||||
- ✅ Filename sanitization
|
||||
- ✅ File hash calculation (SHA256, SHA512)
|
||||
- ✅ Data URL support
|
||||
|
||||
**Key Functions:**
|
||||
```typescript
|
||||
// Encode file to base64
|
||||
encodeFileToBase64(file: Buffer | string, mimeType?: string): string
|
||||
|
||||
// Decode base64 to buffer
|
||||
decodeBase64ToBuffer(base64: string): Buffer
|
||||
|
||||
// Validate base64 file
|
||||
validateBase64File(base64: string, options?: FileValidationOptions): FileValidationResult
|
||||
|
||||
// Detect MIME type
|
||||
detectMimeType(data: Buffer | string, filename?: string): string
|
||||
|
||||
// Encode with full metadata
|
||||
encodeFileWithMetadata(file: Buffer | string, filename?: string, mimeType?: string): FileEncodingResult
|
||||
|
||||
// Sanitize filename
|
||||
sanitizeFilename(filename: string): string
|
||||
|
||||
// Calculate file hash
|
||||
calculateFileHash(data: Buffer | string, algorithm?: 'sha256' | 'sha512'): string
|
||||
```
|
||||
|
||||
**Supported MIME Types:**
|
||||
- Documents: PDF, DOCX, DOC, XLSX, XLS
|
||||
- Images: PNG, JPEG, GIF, WEBP
|
||||
- Text: Plain text, JSON, XML
|
||||
- Archives: ZIP, TAR, GZIP
|
||||
|
||||
**File Size Limits:**
|
||||
- SMALL: 1 MB
|
||||
- MEDIUM: 10 MB
|
||||
- LARGE: 100 MB
|
||||
- XLARGE: 500 MB
|
||||
|
||||
---
|
||||
|
||||
### 3. Content Type Detection
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Implementation:**
|
||||
- Magic byte detection for common file types
|
||||
- File extension-based detection
|
||||
- Fallback to `application/octet-stream`
|
||||
|
||||
**Supported Detection:**
|
||||
- PDF (from `%PDF` header)
|
||||
- PNG (from magic bytes)
|
||||
- JPEG (from magic bytes)
|
||||
- GIF (from magic bytes)
|
||||
- ZIP/DOCX/XLSX (from ZIP magic bytes)
|
||||
- JSON (from content structure)
|
||||
|
||||
---
|
||||
|
||||
### 4. Input Validation
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Credential Request Validation:**
|
||||
- ✅ At least one claim required
|
||||
- ✅ Claim keys cannot be empty
|
||||
- ✅ Claim key length limit (100 characters)
|
||||
- ✅ PIN validation (4-8 digits, numeric only)
|
||||
- ✅ Callback URL format validation
|
||||
|
||||
**Credential Validation:**
|
||||
- ✅ Credential ID required
|
||||
- ✅ Credential type required (array, non-empty)
|
||||
- ✅ Issuer required
|
||||
- ✅ Issuance date required
|
||||
- ✅ Credential subject required (object)
|
||||
- ✅ Proof required with type and jws
|
||||
|
||||
**Document Validation:**
|
||||
- ✅ Base64 encoding validation
|
||||
- ✅ File size limits
|
||||
- ✅ MIME type validation
|
||||
- ✅ Allowed file types
|
||||
|
||||
**Error Messages:**
|
||||
- Clear, descriptive error messages
|
||||
- Actionable feedback
|
||||
- Proper error propagation
|
||||
|
||||
---
|
||||
|
||||
### 5. Enhanced Error Handling
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Improvements:**
|
||||
- ✅ Comprehensive try-catch blocks
|
||||
- ✅ Detailed error messages
|
||||
- ✅ Error context preservation
|
||||
- ✅ Proper error propagation
|
||||
- ✅ Non-blocking error handling for optional operations
|
||||
|
||||
**Error Response Format:**
|
||||
```typescript
|
||||
{
|
||||
verified: boolean;
|
||||
errors?: string[]; // Detailed error messages
|
||||
credentialRequest?: {...};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. eIDAS Bridge Enhancements
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Improvements:**
|
||||
- ✅ Support for Buffer input (auto-encodes to base64)
|
||||
- ✅ Document validation before processing
|
||||
- ✅ Enhanced error reporting
|
||||
- ✅ Flexible claim types
|
||||
- ✅ File validation options
|
||||
|
||||
**New Signature:**
|
||||
```typescript
|
||||
async verifyAndIssue(
|
||||
document: string | Buffer, // Now accepts Buffer
|
||||
userId: string,
|
||||
userEmail: string,
|
||||
pin?: string,
|
||||
validationOptions?: FileValidationOptions // Optional validation
|
||||
): Promise<{
|
||||
verified: boolean;
|
||||
credentialRequest?: {...};
|
||||
errors?: string[]; // Detailed errors
|
||||
}>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. API Schema Updates
|
||||
|
||||
**Status**: ✅ **COMPLETED**
|
||||
|
||||
**Fastify Schema Updates:**
|
||||
- ✅ Enhanced claims schema to accept multiple types
|
||||
- ✅ Updated documentation strings
|
||||
- ✅ Better type validation
|
||||
|
||||
**Before:**
|
||||
```typescript
|
||||
claims: {
|
||||
type: 'object',
|
||||
description: 'Credential claims',
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```typescript
|
||||
claims: {
|
||||
type: 'object',
|
||||
description: 'Credential claims (values can be string, number, boolean, or null)',
|
||||
additionalProperties: {
|
||||
oneOf: [
|
||||
{ type: 'string' },
|
||||
{ type: 'number' },
|
||||
{ type: 'boolean' },
|
||||
{ type: 'null' },
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
**Status**: ✅ **TEST SUITE CREATED**
|
||||
|
||||
**Test File**: `packages/auth/src/file-utils.test.ts`
|
||||
|
||||
**Coverage:**
|
||||
- ✅ Base64 encoding/decoding
|
||||
- ✅ Base64 validation
|
||||
- ✅ MIME type detection
|
||||
- ✅ File validation
|
||||
- ✅ Filename sanitization
|
||||
- ✅ Hash calculation
|
||||
|
||||
**Run Tests:**
|
||||
```bash
|
||||
pnpm test file-utils
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Enhanced Claims
|
||||
|
||||
```typescript
|
||||
import { EntraVerifiedIDClient } from '@the-order/auth';
|
||||
|
||||
const client = new EntraVerifiedIDClient({...});
|
||||
|
||||
// Now supports multiple types
|
||||
await client.issueCredential({
|
||||
claims: {
|
||||
email: '[email protected]', // string
|
||||
age: 30, // number
|
||||
verified: true, // boolean
|
||||
notes: null, // null
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### File Handling
|
||||
|
||||
```typescript
|
||||
import {
|
||||
encodeFileToBase64,
|
||||
validateBase64File,
|
||||
detectMimeType,
|
||||
FILE_SIZE_LIMITS
|
||||
} from '@the-order/auth';
|
||||
|
||||
// Encode file
|
||||
const buffer = fs.readFileSync('document.pdf');
|
||||
const base64 = encodeFileToBase64(buffer, 'application/pdf');
|
||||
|
||||
// Validate file
|
||||
const validation = validateBase64File(base64, {
|
||||
maxSize: FILE_SIZE_LIMITS.MEDIUM,
|
||||
allowedMimeTypes: ['application/pdf'],
|
||||
});
|
||||
|
||||
if (validation.valid) {
|
||||
// Use file
|
||||
}
|
||||
|
||||
// Detect MIME type
|
||||
const mimeType = detectMimeType(buffer, 'document.pdf');
|
||||
```
|
||||
|
||||
### eIDAS Bridge with Buffer
|
||||
|
||||
```typescript
|
||||
import { EIDASToEntraBridge } from '@the-order/auth';
|
||||
|
||||
const bridge = new EIDASToEntraBridge({...});
|
||||
|
||||
// Now accepts Buffer directly
|
||||
const documentBuffer = fs.readFileSync('document.pdf');
|
||||
const result = await bridge.verifyAndIssue(
|
||||
documentBuffer, // Buffer - auto-encoded
|
||||
userId,
|
||||
userEmail,
|
||||
pin,
|
||||
{
|
||||
maxSize: FILE_SIZE_LIMITS.MEDIUM,
|
||||
allowedMimeTypes: ['application/pdf'],
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### For Existing Code
|
||||
|
||||
**Claims Updates:**
|
||||
- No breaking changes - existing string claims still work
|
||||
- Can now use numbers, booleans, null directly
|
||||
- Automatic conversion to strings for API
|
||||
|
||||
**Document Handling:**
|
||||
- Can now pass Buffer directly to `verifyAndIssue`
|
||||
- Base64 strings still supported
|
||||
- Validation is optional but recommended
|
||||
|
||||
**Error Handling:**
|
||||
- Errors now include detailed messages
|
||||
- Check `errors` array in responses
|
||||
- Handle validation errors before processing
|
||||
|
||||
---
|
||||
|
||||
## Security Improvements
|
||||
|
||||
1. ✅ **Input Sanitization**
|
||||
- Filename sanitization
|
||||
- Claim key validation
|
||||
- URL validation
|
||||
|
||||
2. ✅ **File Validation**
|
||||
- Size limits enforced
|
||||
- MIME type validation
|
||||
- Base64 encoding validation
|
||||
|
||||
3. ✅ **Error Information**
|
||||
- No sensitive data in error messages
|
||||
- Proper error logging
|
||||
- Secure error handling
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. ✅ **Efficient Encoding**
|
||||
- Direct buffer operations
|
||||
- Minimal memory copies
|
||||
- Streaming support ready
|
||||
|
||||
2. ✅ **Validation Caching**
|
||||
- MIME type detection optimized
|
||||
- Base64 validation efficient
|
||||
- File size checks early
|
||||
|
||||
3. ✅ **Error Handling**
|
||||
- Fast-fail validation
|
||||
- Non-blocking optional operations
|
||||
- Efficient error propagation
|
||||
|
||||
---
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Created
|
||||
- ✅ `packages/auth/src/file-utils.ts` - File handling utilities
|
||||
- ✅ `packages/auth/src/file-utils.test.ts` - Test suite
|
||||
- ✅ `docs/integrations/ENTRA_BEST_PRACTICES_IMPLEMENTATION.md` - This document
|
||||
|
||||
### Modified
|
||||
- ✅ `packages/auth/src/entra-verifiedid.ts` - Enhanced claims, validation
|
||||
- ✅ `packages/auth/src/eidas-entra-bridge.ts` - Buffer support, validation
|
||||
- ✅ `packages/auth/src/index.ts` - Export file-utils
|
||||
- ✅ `services/identity/src/entra-integration.ts` - Updated schemas
|
||||
- ✅ `docs/integrations/ENTRA_JSON_CONTENT_READINESS.md` - Updated status
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**All Best Practices Implemented**: ✅
|
||||
|
||||
1. ✅ Enhanced claims type support
|
||||
2. ✅ File handling utilities
|
||||
3. ✅ Content type detection
|
||||
4. ✅ Input validation
|
||||
5. ✅ Enhanced error handling
|
||||
6. ✅ Security improvements
|
||||
7. ✅ Test suite
|
||||
|
||||
**Status**: ✅ **PRODUCTION READY**
|
||||
|
||||
The Entra VerifiedID integration now follows all best practices and is ready for production use with enhanced capabilities.
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
- Run tests to verify functionality
|
||||
- Update API documentation
|
||||
- Deploy to staging for integration testing
|
||||
|
||||
@@ -1,232 +0,0 @@
|
||||
# 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
|
||||
|
||||
@@ -1,418 +0,0 @@
|
||||
# Entra VerifiedID - JSON and Content Readiness Assessment
|
||||
|
||||
**Last Updated**: 2025-01-27
|
||||
**Status**: ✅ Ready for JSON, ⚠️ Limited for other content types
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Entra VerifiedID integration is READY for JSON content** with full support for:
|
||||
- ✅ JSON request/response handling
|
||||
- ✅ Credential claims as JSON objects
|
||||
- ✅ Credential verification with JSON payloads
|
||||
- ✅ API responses in JSON format
|
||||
|
||||
**Limited support for other content types:**
|
||||
- ⚠️ Documents must be base64-encoded strings
|
||||
- ⚠️ No direct binary file handling
|
||||
- ⚠️ No image/PDF processing built-in
|
||||
- ⚠️ Claims are restricted to string values only
|
||||
|
||||
---
|
||||
|
||||
## JSON Support - ✅ FULLY READY
|
||||
|
||||
### 1. Request/Response Handling
|
||||
|
||||
**Status**: ✅ **COMPLETE**
|
||||
|
||||
All API endpoints properly handle JSON:
|
||||
|
||||
```typescript
|
||||
// Request headers
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
Authorization: `Bearer ${token}`,
|
||||
}
|
||||
|
||||
// Request body
|
||||
body: JSON.stringify(requestBody)
|
||||
|
||||
// Response parsing
|
||||
const data = await response.json()
|
||||
```
|
||||
|
||||
**Locations:**
|
||||
- `packages/auth/src/entra-verifiedid.ts` - Lines 151, 154, 162, 209, 212, 221, 259, 262, 270
|
||||
- `services/identity/src/entra-integration.ts` - All endpoints use JSON
|
||||
|
||||
### 2. TypeScript Interfaces
|
||||
|
||||
**Status**: ✅ **COMPLETE**
|
||||
|
||||
All JSON structures are properly typed:
|
||||
|
||||
```typescript
|
||||
// Request interface
|
||||
export interface VerifiableCredentialRequest {
|
||||
claims: Record<string, string>;
|
||||
pin?: string;
|
||||
callbackUrl?: string;
|
||||
}
|
||||
|
||||
// Response interface
|
||||
export interface VerifiableCredentialResponse {
|
||||
requestId: string;
|
||||
url: string;
|
||||
expiry: number;
|
||||
qrCode?: string;
|
||||
}
|
||||
|
||||
// Credential interface
|
||||
export interface VerifiedCredential {
|
||||
id: string;
|
||||
type: string[];
|
||||
issuer: string;
|
||||
issuanceDate: string;
|
||||
expirationDate?: string;
|
||||
credentialSubject: Record<string, unknown>; // ✅ Flexible
|
||||
proof: { ... };
|
||||
}
|
||||
```
|
||||
|
||||
### 3. API Endpoints - JSON Schema Validation
|
||||
|
||||
**Status**: ✅ **COMPLETE**
|
||||
|
||||
All endpoints have JSON schema validation via Fastify:
|
||||
|
||||
```typescript
|
||||
schema: {
|
||||
body: {
|
||||
type: 'object',
|
||||
required: ['claims'],
|
||||
properties: {
|
||||
claims: {
|
||||
type: 'object',
|
||||
description: 'Credential claims',
|
||||
},
|
||||
// ...
|
||||
},
|
||||
},
|
||||
response: {
|
||||
200: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
requestId: { type: 'string' },
|
||||
url: { type: 'string' },
|
||||
qrCode: { type: 'string' },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Endpoints:**
|
||||
- ✅ `POST /vc/issue/entra` - JSON request/response
|
||||
- ✅ `POST /vc/verify/entra` - JSON request/response
|
||||
- ✅ `POST /eidas/verify-and-issue` - JSON request/response
|
||||
|
||||
---
|
||||
|
||||
## Content Type Support
|
||||
|
||||
### 1. JSON Content - ✅ READY
|
||||
|
||||
**Status**: ✅ **FULLY SUPPORTED**
|
||||
|
||||
- ✅ All API requests use `application/json`
|
||||
- ✅ All responses are JSON
|
||||
- ✅ Proper JSON parsing and stringification
|
||||
- ✅ Type-safe JSON handling with TypeScript
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
{
|
||||
"claims": {
|
||||
"email": "[email protected]",
|
||||
"name": "John Doe",
|
||||
"role": "member"
|
||||
},
|
||||
"pin": "1234",
|
||||
"callbackUrl": "https://example.com/callback"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Base64-Encoded Documents - ⚠️ LIMITED
|
||||
|
||||
**Status**: ⚠️ **BASIC SUPPORT**
|
||||
|
||||
Documents must be provided as base64-encoded strings:
|
||||
|
||||
```typescript
|
||||
// eIDAS endpoint expects base64 string
|
||||
{
|
||||
"document": "base64-encoded-document",
|
||||
"userId": "user-123",
|
||||
"userEmail": "[email protected]"
|
||||
}
|
||||
```
|
||||
|
||||
**Limitations:**
|
||||
- ⚠️ No automatic encoding/decoding
|
||||
- ⚠️ No file type validation
|
||||
- ⚠️ No size limits enforced
|
||||
- ⚠️ No MIME type handling
|
||||
|
||||
**Recommendation**: Add helper functions for file handling.
|
||||
|
||||
### 3. Binary Content - ❌ NOT SUPPORTED
|
||||
|
||||
**Status**: ❌ **NOT SUPPORTED**
|
||||
|
||||
- ❌ No direct binary file upload
|
||||
- ❌ No multipart/form-data support
|
||||
- ❌ No file streaming
|
||||
- ❌ No image/PDF processing
|
||||
|
||||
**Workaround**: Convert to base64 before sending.
|
||||
|
||||
### 4. QR Codes - ✅ SUPPORTED
|
||||
|
||||
**Status**: ✅ **SUPPORTED**
|
||||
|
||||
QR codes are returned as base64-encoded data URLs in JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"requestId": "abc123",
|
||||
"url": "https://verifiedid.did.msidentity.com/...",
|
||||
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Claims Handling - ⚠️ TYPE RESTRICTION
|
||||
|
||||
### Current Implementation
|
||||
|
||||
**Status**: ⚠️ **RESTRICTED TO STRINGS**
|
||||
|
||||
```typescript
|
||||
export interface VerifiableCredentialRequest {
|
||||
claims: Record<string, string>; // ⚠️ Only string values
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Limitation**: Claims can only be string values, not:
|
||||
- ❌ Numbers
|
||||
- ❌ Booleans
|
||||
- ❌ Nested objects
|
||||
- ❌ Arrays
|
||||
|
||||
### Credential Subject - ✅ FLEXIBLE
|
||||
|
||||
**Status**: ✅ **FLEXIBLE**
|
||||
|
||||
```typescript
|
||||
export interface VerifiedCredential {
|
||||
credentialSubject: Record<string, unknown>; // ✅ Any type
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Credential subject can contain any JSON-serializable value.
|
||||
|
||||
---
|
||||
|
||||
## Recommendations for Enhancement
|
||||
|
||||
### 1. Enhanced Claims Type Support
|
||||
|
||||
**Priority**: Medium
|
||||
|
||||
```typescript
|
||||
// Enhanced interface
|
||||
export interface VerifiableCredentialRequest {
|
||||
claims: Record<string, string | number | boolean | null>;
|
||||
// Or use JSON Schema validation
|
||||
}
|
||||
```
|
||||
|
||||
### 2. File Handling Utilities
|
||||
|
||||
**Priority**: High
|
||||
|
||||
```typescript
|
||||
// Add helper functions
|
||||
export async function encodeFileToBase64(file: Buffer | string): Promise<string> {
|
||||
// Handle file encoding
|
||||
}
|
||||
|
||||
export function validateBase64Document(base64: string, maxSize?: number): boolean {
|
||||
// Validate document
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Content Type Detection
|
||||
|
||||
**Priority**: Medium
|
||||
|
||||
```typescript
|
||||
export function detectContentType(data: string | Buffer): string {
|
||||
// Detect MIME type
|
||||
// Validate against allowed types
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Document Processing
|
||||
|
||||
**Priority**: Low (can use external services)
|
||||
|
||||
```typescript
|
||||
// Integration with document processing
|
||||
export async function processDocumentForEntra(
|
||||
document: Buffer,
|
||||
options: DocumentProcessingOptions
|
||||
): Promise<ProcessedDocument> {
|
||||
// OCR, validation, etc.
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Current Capabilities Summary
|
||||
|
||||
### ✅ Fully Supported
|
||||
|
||||
1. **JSON Requests/Responses**
|
||||
- All API endpoints
|
||||
- Proper Content-Type headers
|
||||
- JSON parsing/stringification
|
||||
|
||||
2. **Credential Claims (as strings)**
|
||||
- Simple key-value pairs
|
||||
- String values only
|
||||
|
||||
3. **Credential Verification**
|
||||
- Full credential objects
|
||||
- Flexible credentialSubject
|
||||
|
||||
4. **QR Code Generation**
|
||||
- Base64-encoded in JSON response
|
||||
|
||||
### ⚠️ Limited Support
|
||||
|
||||
1. **Documents**
|
||||
- Must be base64-encoded
|
||||
- No automatic encoding
|
||||
- No file type validation
|
||||
|
||||
2. **Claims Types**
|
||||
- Only string values
|
||||
- No numbers, booleans, objects, arrays
|
||||
|
||||
3. **Binary Content**
|
||||
- No direct binary handling
|
||||
- Must convert to base64
|
||||
|
||||
### ❌ Not Supported
|
||||
|
||||
1. **Multipart Uploads**
|
||||
- No multipart/form-data
|
||||
- No file streaming
|
||||
|
||||
2. **Direct File Processing**
|
||||
- No image processing
|
||||
- No PDF parsing
|
||||
- No document extraction
|
||||
|
||||
---
|
||||
|
||||
## Testing JSON Readiness
|
||||
|
||||
### Test JSON Request
|
||||
|
||||
```bash
|
||||
curl -X POST https://your-api/vc/issue/entra \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-d '{
|
||||
"claims": {
|
||||
"email": "[email protected]",
|
||||
"name": "Test User"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Expected JSON Response
|
||||
|
||||
```json
|
||||
{
|
||||
"requestId": "abc123",
|
||||
"url": "https://verifiedid.did.msidentity.com/...",
|
||||
"qrCode": "data:image/png;base64,...",
|
||||
"expiry": 3600
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Path for Enhanced Content Support
|
||||
|
||||
### Phase 1: Enhanced Claims (1-2 days)
|
||||
- [ ] Update `VerifiableCredentialRequest` interface
|
||||
- [ ] Add JSON Schema validation for mixed types
|
||||
- [ ] Update API documentation
|
||||
|
||||
### Phase 2: File Utilities (3-5 days)
|
||||
- [ ] Add base64 encoding/decoding helpers
|
||||
- [ ] Add file validation functions
|
||||
- [ ] Add MIME type detection
|
||||
- [ ] Add size limit validation
|
||||
|
||||
### Phase 3: Document Processing (1-2 weeks)
|
||||
- [ ] Integrate with document processing service
|
||||
- [ ] Add OCR capabilities
|
||||
- [ ] Add PDF parsing
|
||||
- [ ] Add image processing
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**JSON Support**: ✅ **READY FOR PRODUCTION**
|
||||
|
||||
The Entra VerifiedID integration is fully ready to handle:
|
||||
- ✅ All JSON request/response formats
|
||||
- ✅ Credential issuance with JSON claims
|
||||
- ✅ Credential verification with JSON payloads
|
||||
- ✅ API responses in JSON format
|
||||
|
||||
**Enhanced Features**: ✅ **IMPLEMENTED**
|
||||
|
||||
Best practices improvements have been implemented:
|
||||
- ✅ **Enhanced Claims Support** - Now supports `string | number | boolean | null`
|
||||
- ✅ **File Handling Utilities** - Complete base64 encoding/decoding, validation
|
||||
- ✅ **Content Type Detection** - Automatic MIME type detection
|
||||
- ✅ **Input Validation** - Comprehensive validation for requests and credentials
|
||||
- ✅ **Error Handling** - Improved error messages and validation
|
||||
- ✅ **Document Processing** - Automatic encoding for Buffer inputs
|
||||
|
||||
**Status**: ✅ **PRODUCTION READY WITH BEST PRACTICES**
|
||||
|
||||
All recommended improvements have been implemented:
|
||||
- ✅ Enhanced claims type support (string, number, boolean, null)
|
||||
- ✅ File handling utilities (`file-utils.ts`)
|
||||
- ✅ Content type detection and validation
|
||||
- ✅ Input sanitization and security improvements
|
||||
- ✅ Comprehensive error handling
|
||||
|
||||
---
|
||||
|
||||
**Status**: ✅ **READY FOR PRODUCTION WITH BEST PRACTICES**
|
||||
**Implementation**: All recommended improvements completed
|
||||
|
||||
Reference in New Issue
Block a user