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:

```bash
# 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:
```json
{
  "claims": {
    "email": "user@example.com",
    "name": "John Doe",
    "role": "member"
  },
  "pin": "1234",
  "callbackUrl": "https://your-app.com/callback"
}
```

Response:
```json
{
  "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:
```json
{
  "credential": {
    "id": "vc:123",
    "type": ["VerifiableCredential", "IdentityCredential"],
    "issuer": "did:web:...",
    "credentialSubject": { ... },
    "proof": { ... }
  }
}
```

Response:
```json
{
  "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:
```json
{
  "document": "base64-encoded-document",
  "userId": "user-123",
  "userEmail": "user@example.com",
  "pin": "1234"
}
```

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

## Usage Examples

### TypeScript Client

```typescript
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

```typescript
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

```json
{
  "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](https://learn.microsoft.com/en-us/azure/active-directory/verifiable-credentials/)
- [Azure Logic Apps Documentation](https://learn.microsoft.com/en-us/azure/logic-apps/)
- [eIDAS Regulation](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32014R0910)