Chapter 7: Phase 4 - Integration

┌─────────────────────────────────────────────────────────────┐
│                    WIA-ACS Core Platform                     │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐             │
│  │    Auth    │ │   Authz    │ │   Audit    │             │
│  │  Service   │ │  Service   │ │  Service   │             │
│  └──────┬─────┘ └──────┬─────┘ └──────┬─────┘             │
└─────────┼──────────────┼──────────────┼────────────────────┘
          │              │              │
    ┌─────▼──────────────▼──────────────▼──────┐
    │        Integration Adapter Layer          │
    │  (Translates between WIA-ACS and external)│
    └─────┬────────┬────────┬─────────┬─────────┘
          │        │        │         │
    ┌─────▼──┐ ┌──▼────┐ ┌─▼─────┐ ┌─▼───────┐
    │  LDAP  │ │ PACS  │ │  Bio  │ │ Cloud   │
    │Adapter │ │Adapter│ │Adapter│ │ Adapter │
    └─────┬──┘ └──┬────┘ └─┬─────┘ └─┬───────┘
          │       │        │         │
    ┌─────▼──┐ ┌──▼────┐ ┌─▼─────┐ ┌─▼───────┐
    │   AD   │ │  HID  │ │Suprema│ │ Azure   │
    │  LDAP  │ │ Lenel │ │ ZKTeco│ │   AD    │
    └────────┘ └───────┘ └───────┘ └─────────┘
            

interface IAdapter {
  // Lifecycle methods
  initialize(config: AdapterConfig): Promise<void>;
  healthCheck(): Promise<HealthStatus>;
  shutdown(): Promise<void>;

  // Data synchronization
  syncUsers(options: SyncOptions): Promise<SyncResult>;
  syncCredentials(options: SyncOptions): Promise<SyncResult>;

  // Event handling
  onEvent(event: ExternalEvent): Promise<WiaEvent>;
  subscribeToEvents(callback: EventCallback): void;

  // Capabilities
  getCapabilities(): AdapterCapabilities;
}

type AdapterCapabilities = {
  supportsUserSync: boolean;
  supportsCredentialSync: boolean;
  supportsRealTimeEvents: boolean;
  supportedCredentialTypes: CredentialType[];
  supportedAuthMethods: AuthMethod[];
  bidirectionalSync: boolean;
};
            

{
  "adapter_type": "ldap",
  "adapter_id": "ldap-corporate-ad",
  "connection": {
    "url": "ldaps://ldap.example.com:636",
    "bind_dn": "cn=wia-acs-service,ou=Service Accounts,dc=example,dc=com",
    "bind_password": "${LDAP_BIND_PASSWORD}",
    "tls": {
      "enabled": true,
      "verify_cert": true,
      "ca_cert_path": "/etc/ssl/certs/ca-bundle.crt",
      "client_cert_path": null,
      "min_tls_version": "1.2"
    },
    "timeout_seconds": 30,
    "connection_pool_size": 10
  },
  "schema_mapping": {
    "user": {
      "base_dn": "ou=Users,dc=example,dc=com",
      "object_class": "inetOrgPerson",
      "filter": "(&(objectClass=inetOrgPerson)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))",
      "attributes": {
        "user_id": "employeeNumber",
        "given_name": "givenName",
        "family_name": "sn",
        "email": "mail",
        "phone": "telephoneNumber",
        "department": "department",
        "title": "title",
        "manager": "manager",
        "employee_type": "employeeType"
      }
    },
    "group": {
      "base_dn": "ou=Groups,dc=example,dc=com",
      "object_class": "groupOfNames",
      "filter": "(objectClass=groupOfNames)",
      "member_attribute": "member"
    }
  },
  "sync": {
    "schedule": "0 */4 * * *",
    "full_sync_interval_hours": 24,
    "incremental_sync": true,
    "usnChanged_attribute": "modifyTimestamp",
    "deleted_users_ou": "ou=Disabled Users,dc=example,dc=com",
    "batch_size": 500
  },
  "role_mapping": [
    {
      "ldap_group": "cn=Engineering,ou=Groups,dc=example,dc=com",
      "wia_role": "role-engineering"
    },
    {
      "ldap_group": "cn=Security,ou=Groups,dc=example,dc=com",
      "wia_role": "role-security"
    },
    {
      "ldap_group": "cn=Employees,ou=Groups,dc=example,dc=com",
      "wia_role": "role-employee"
    }
  ]
}
            

Incremental Sync (every 4 hours):

1. Query LDAP for changes since last sync
   (&(modifyTimestamp>=20251226120000Z))

2. For each changed entry:
   a. Map LDAP attributes to WIA-ACS user schema
   b. Resolve group memberships to roles
   c. Check if user exists in WIA-ACS
   d. Create new user or update existing

3. Handle deletions:
   a. Query users in WIA-ACS not in LDAP result
   b. Mark as "terminated" status
   c. Revoke all active credentials
   d. Log deprovisioning event

4. Update sync metadata:
   last_sync_timestamp: 2025-12-26T16:00:00Z
   users_created: 5
   users_updated: 47
   users_deleted: 2
   errors: []

Full Sync (daily):

1. Retrieve all users from LDAP
2. Compare with WIA-ACS user database
3. Identify orphaned accounts (in WIA-ACS but not LDAP)
4. Reconcile discrepancies
5. Generate sync report
            

Credential Provisioning to HID VertX:

1. WIA-ACS creates credential
   POST /v1/credentials
   {
     "user_id": "usr-001",
     "credential_type": "proximity",
     "encoding": {
       "format": "wiegand_26bit",
       "facility_code": 123,
       "card_number": 45678
     }
   }

2. Adapter converts to HID format
   POST /api/v1/credentials
   Host: vertx.example.com
   Authorization: Bearer HID_API_TOKEN
   {
     "CardNumber": 45678,
     "FacilityCode": 123,
     "CardFormat": "Wiegand26Bit",
     "Status": "Active",
     "ActivationDate": "2025-12-26T00:00:00Z",
     "ExpirationDate": "2026-12-26T23:59:59Z",
     "Doors": [
       {"DoorID": 101, "AccessSchedule": "24x7"},
       {"DoorID": 102, "AccessSchedule": "BusinessHours"}
     ]
   }

3. Event monitoring (webhook from HID)
   POST /webhook/hid-vertx
   X-HID-Event-Type: AccessGranted
   {
     "EventType": "AccessGranted",
     "Timestamp": "2025-12-26T14:32:17Z",
     "DoorID": 101,
     "CardNumber": 45678,
     "FacilityCode": 123,
     "Direction": "Entry"
   }

4. Adapter translates to WIA-ACS event
   {
     "event_type": "access_granted",
     "timestamp": "2025-12-26T14:32:17Z",
     "actor": {
       "credential_id": "cred-xyz789"
     },
     "target": {
       "resource_type": "door",
       "resource_id": "door-101"
     },
     "result": "success"
   }
            

Enrollment Workflow:

1. User places finger on reader
2. Reader captures fingerprint (multiple samples)
3. Generate biometric template
   {
     "biometric_type": "fingerprint",
     "algorithm": "ISO_19794_2",
     "template": "BASE64_ENCODED_TEMPLATE",
     "quality_score": 85,
     "finger_position": "right_index",
     "minutiae_count": 47
   }

4. Store template in WIA-ACS
   POST /v1/biometrics
   {
     "user_id": "usr-001",
     "biometric_type": "fingerprint",
     "template_hash": "SHA256_OF_TEMPLATE",
     "template_encrypted": "AES256_ENCRYPTED_TEMPLATE",
     "metadata": {
       "enrolled_at": "2025-12-26T10:00:00Z",
       "device_id": "bio-reader-001",
       "quality_score": 85
     }
   }

Authentication Workflow:

1. User places finger on reader
2. Generate authentication template
3. Send to WIA-ACS for matching
   POST /v1/biometrics/authenticate
   {
     "device_id": "bio-reader-001",
     "biometric_type": "fingerprint",
     "template": "BASE64_ENCODED_TEMPLATE",
     "quality_score": 82
   }

4. WIA-ACS performs 1:N matching
   - Retrieve all fingerprint templates
   - Compare against authentication template
   - Apply threshold (FAR = 0.001%, FRR = 0.1%)
   - Return best match if above threshold

5. Response
   {
     "match": true,
     "user_id": "usr-001",
     "confidence": 98.7,
     "match_duration_ms": 87
   }

Performance Requirements:
- 1:1 matching: < 100ms
- 1:10,000 matching: < 2 seconds
- False Accept Rate (FAR): < 0.001%
- False Reject Rate (FRR): < 0.1%
            

PIV (Personal Identity Verification) Card Structure:

Card contains:
├── Contactless interface (13.56 MHz)
├── Contact interface (ISO 7816)
├── Cryptographic processor
└── Data objects:
    ├── Cardholder Unique Identifier (CHUID)
    ├── Card Authentication Certificate
    ├── PIV Authentication Certificate (9A)
    ├── Digital Signature Certificate (9C)
    ├── Key Management Certificate (9D)
    ├── Card Authentication Key (9E)
    ├── Fingerprint templates (optional)
    └── Facial image

Authentication Flow:

1. Card presented to reader
2. Reader requests PIV Auth Certificate
   APDU: 00 CB 3F FF 05 5C 03 5F C1 05

3. Card returns certificate
4. Reader generates random challenge
5. Card signs challenge with private key
6. Reader verifies signature with public key
7. Extract user ID from certificate DN
   Subject: CN=DOE.JOHN.MIDDLE.1234567890

8. Map to WIA-ACS user
   POST /v1/authenticate
   {
     "credential_type": "smart_card",
     "certificate_dn": "CN=DOE.JOHN.MIDDLE.1234567890",
     "challenge_response": "SIGNED_CHALLENGE"
   }

9. WIA-ACS validates and returns token
            

Azure AD SCIM Provisioning:

1. Configure enterprise application
   - Enable SCIM provisioning
   - Set tenant URL: https://acs.example.com/scim/v2
   - Set secret token: SCIM_BEARER_TOKEN

2. Attribute mapping
   Azure AD          →  WIA-ACS
   ──────────────────────────────
   id                →  external_id
   displayName       →  identity.name
   givenName         →  identity.given_name
   surname           →  identity.family_name
   userPrincipalName →  identity.email
   department        →  employment.department
   jobTitle          →  employment.title

3. Azure AD provisions user
   POST /scim/v2/Users
   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "externalId": "00000000-0000-0000-0000-000000000001",
     "userName": "john.doe@example.com",
     "name": {
       "givenName": "John",
       "familyName": "Doe"
     },
     "emails": [{
       "value": "john.doe@example.com",
       "primary": true
     }],
     "active": true
   }

4. WIA-ACS creates user and returns
   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id": "usr-001",
     "externalId": "00000000-0000-0000-0000-000000000001",
     "meta": {
       "resourceType": "User",
       "created": "2025-12-26T10:00:00Z",
       "lastModified": "2025-12-26T10:00:00Z",
       "location": "https://acs.example.com/scim/v2/Users/usr-001"
     }
   }

5. Deprovisioning (user disabled in Azure AD)
   PATCH /scim/v2/Users/usr-001
   {
     "Operations": [{
       "op": "replace",
       "path": "active",
       "value": false
     }]
   }
            

Event Correlation Example:

Time    System          Event
─────────────────────────────────────────────────────────────
10:00   Azure AD        User john.doe@example.com created
10:01   WIA-ACS         User usr-001 provisioned via SCIM
10:02   WIA-ACS         Credential cred-xyz789 issued to usr-001
10:03   HID VertX       Card 123-45678 programmed
10:05   LDAP Sync       User synchronized to corporate directory

14:30   HID VertX       Card 123-45678 presented at Door 101
14:30   WIA-ACS         Authentication successful for cred-xyz789
14:30   WIA-ACS         Authorization granted for door-101
14:30   HID VertX       Door 101 unlocked

17:00   Azure AD        User john.doe@example.com disabled
17:01   WIA-ACS         User usr-001 status changed to suspended
17:01   WIA-ACS         Credential cred-xyz789 revoked
17:02   HID VertX       Card 123-45678 deactivated

Unified Query:
GET /v1/audit/events?user_id=usr-001&start_date=2025-12-26T00:00:00Z

Returns chronological events from all systems with correlation IDs