the_order/docs/integrations/MICROSOFT_ENTRA_VERIFIEDID.md

Microsoft Entra VerifiedID Integration

This document describes the integration with Microsoft Entra VerifiedID for verifiable credential issuance and verification.

Overview

The Order integrates with Microsoft Entra VerifiedID to:

• Issue verifiable credentials through Microsoft's managed service
• Verify verifiable credentials issued by Microsoft Entra VerifiedID
• Bridge eIDAS verification with Microsoft Entra VerifiedID credential issuance
• Integrate with Azure Logic Apps for workflow orchestration

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────────┐
│   Client    │────▶│ Identity     │────▶│ Entra VerifiedID    │
│             │     │ Service      │     │ API                 │
└─────────────┘     └──────────────┘     └─────────────────────┘
                            │
                            │
                            ▼
                    ┌──────────────┐
                    │ eIDAS Bridge │
                    │              │
                    │ 1. Verify    │
                    │ 2. Issue VC  │
                    └──────────────┘
                            │
                            ▼
                    ┌──────────────┐
                    │ Logic Apps   │
                    │ (Optional)   │
                    └──────────────┘

Setup

1. Microsoft Entra VerifiedID Configuration

1. Create Azure AD App Registration

   • Go to Azure Portal → Azure Active Directory → App registrations
   • Create a new registration
   • Note the Application (client) ID and Directory (tenant) ID

2. Configure API Permissions

   • Add permission: Verifiable Credentials Service - VerifiableCredential.Create.All
   • Add permission: Verifiable Credentials Service - VerifiableCredential.Verify.All
   • Grant admin consent

3. Create Client Secret

   • Go to Certificates & secrets
   • Create a new client secret
   • Note the secret value (it's only shown once)

4. Create Credential Manifest

   • Go to Azure Portal → Verified ID
   • Create a new credential manifest
   • Note the Manifest ID

2. Environment Variables

Add the following to your .env file:

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

# eIDAS (for bridge functionality)
EIDAS_PROVIDER_URL=https://your-eidas-provider.com
EIDAS_API_KEY=your-eidas-api-key

# Azure Logic Apps (optional)
AZURE_LOGIC_APPS_WORKFLOW_URL=https://your-logic-app.azurewebsites.net
AZURE_LOGIC_APPS_ACCESS_KEY=your-access-key
AZURE_LOGIC_APPS_MANAGED_IDENTITY_CLIENT_ID=your-managed-identity-client-id

API Endpoints

Issue Credential via Entra VerifiedID

POST /vc/issue/entra

Request body:

{
  "claims": {
    "email": "user@example.com",
    "name": "John Doe",
    "role": "member"
  },
  "pin": "1234",
  "callbackUrl": "https://your-app.com/callback"
}

Response:

{
  "requestId": "abc123",
  "url": "https://verifiedid.did.msidentity.com/...",
  "qrCode": "data:image/png;base64,...",
  "expiry": 3600
}

Verify Credential via Entra VerifiedID

POST /vc/verify/entra

Request body:

{
  "credential": {
    "id": "vc:123",
    "type": ["VerifiableCredential", "IdentityCredential"],
    "issuer": "did:web:...",
    "credentialSubject": { ... },
    "proof": { ... }
  }
}

Response:

{
  "verified": true
}

eIDAS Verification with Entra Issuance

POST /eidas/verify-and-issue

This endpoint:

1. Verifies the eIDAS signature
2. Issues a verifiable credential via Microsoft Entra VerifiedID
3. Optionally triggers Azure Logic Apps workflow

Request body:

{
  "document": "base64-encoded-document",
  "userId": "user-123",
  "userEmail": "user@example.com",
  "pin": "1234"
}

Response:

{
  "verified": true,
  "credentialRequest": {
    "requestId": "abc123",
    "url": "https://verifiedid.did.msidentity.com/...",
    "qrCode": "data:image/png;base64,..."
  }
}

Usage Examples

TypeScript Client

import { EntraVerifiedIDClient } from '@the-order/auth';

const client = new EntraVerifiedIDClient({
  tenantId: process.env.ENTRA_TENANT_ID!,
  clientId: process.env.ENTRA_CLIENT_ID!,
  clientSecret: process.env.ENTRA_CLIENT_SECRET!,
  credentialManifestId: process.env.ENTRA_CREDENTIAL_MANIFEST_ID!,
});

// Issue credential
const credential = await client.issueCredential({
  claims: {
    email: 'user@example.com',
    name: 'John Doe',
  },
  pin: '1234',
});

// Verify credential
const verified = await client.verifyCredential(credential);

eIDAS Bridge

import { EIDASToEntraBridge } from '@the-order/auth';

const bridge = new EIDASToEntraBridge({
  entraVerifiedID: {
    tenantId: process.env.ENTRA_TENANT_ID!,
    clientId: process.env.ENTRA_CLIENT_ID!,
    clientSecret: process.env.ENTRA_CLIENT_SECRET!,
    credentialManifestId: process.env.ENTRA_CREDENTIAL_MANIFEST_ID!,
  },
  eidas: {
    providerUrl: process.env.EIDAS_PROVIDER_URL!,
    apiKey: process.env.EIDAS_API_KEY!,
  },
});

// Verify eIDAS and issue credential
const result = await bridge.verifyAndIssue(
  document,
  userId,
  userEmail,
  pin
);

Azure Logic Apps Integration

The integration supports optional Azure Logic Apps workflows for:

• Document processing
• eIDAS verification workflows
• VC issuance workflows

Logic App Workflow Example

{
  "definition": {
    "triggers": {
      "eidas-verification": {
        "type": "Request",
        "inputs": {
          "schema": {
            "type": "object",
            "properties": {
              "documentId": { "type": "string" },
              "userId": { "type": "string" },
              "eidasProviderUrl": { "type": "string" }
            }
          }
        }
      }
    },
    "actions": {
      "process-eidas": {
        "type": "Http",
        "inputs": {
          "method": "POST",
          "uri": "@{triggerBody()['eidasProviderUrl']}/verify",
          "body": {
            "documentId": "@{triggerBody()['documentId']}"
          }
        }
      }
    }
  }
}

Security Considerations

1. Client Secrets: Store securely in Azure Key Vault or similar
2. Access Tokens: Automatically cached and refreshed
3. PIN Protection: Optional PIN for credential issuance
4. Certificate Validation: Full certificate chain validation for eIDAS
5. Managed Identity: Use Azure Managed Identity when possible instead of client secrets

Troubleshooting

Common Issues

1. "Failed to get access token"

   • Check tenant ID, client ID, and client secret
   • Verify API permissions are granted
   • Check that admin consent is provided

2. "Credential manifest ID is required"

   • Ensure ENTRA_CREDENTIAL_MANIFEST_ID is set
   • Verify the manifest exists in Azure Portal

3. "eIDAS verification failed"

   • Check eIDAS provider URL and API key
   • Verify network connectivity to eIDAS provider
   • Check certificate validity

References

• Microsoft Entra VerifiedID Documentation
• Azure Logic Apps Documentation
• eIDAS Regulation