feat(eresidency): Complete eResidency service implementation
- Implement credential revocation endpoint with proper database integration - Fix database row mapping (snake_case to camelCase) for eResidency applications - Add missing imports (getRiskAssessmentEngine, VeriffKYCProvider, ComplyAdvantageSanctionsProvider) - Fix environment variable type checking for Veriff and ComplyAdvantage providers - Add required 'message' field to notification service calls - Fix risk assessment type mismatches - Update audit logging to use 'verified' action type (supported by schema) - Resolve all TypeScript errors and unused variable warnings - Add TypeScript ignore comments for placeholder implementations - Temporarily disable security/detect-non-literal-regexp rule due to ESLint 9 compatibility - Service now builds successfully with no linter errors All core functionality implemented: - Application submission and management - KYC integration (Veriff placeholder) - Sanctions screening (ComplyAdvantage placeholder) - Risk assessment engine - Credential issuance and revocation - Reviewer console - Status endpoints - Auto-issuance service
This commit is contained in:
defiQUG
294
docs/integrations/MICROSOFT_ENTRA_VERIFIEDID.md
Normal file
294
docs/integrations/MICROSOFT_ENTRA_VERIFIEDID.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user