the_order/docs/integrations/INTEGRATION_SUMMARY.md

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

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

• 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

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 (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

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 (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

• Client implementation
• OAuth2 authentication
• Credential issuance
• Credential verification
• Presentation requests
• Environment variable configuration
• API endpoints
• Documentation

Azure Logic Apps

• Client implementation
• Access key authentication
• Managed identity authentication
• Workflow triggers
• Environment variable configuration
• Documentation

eIDAS Bridge

• Bridge implementation
• eIDAS verification integration
• Entra VerifiedID issuance integration
• Logic Apps integration
• API endpoints
• Documentation

Configuration Requirements

Required for Entra VerifiedID

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

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

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