Interop Service — Security Model

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

---

1. Authentication Layers

Layer	Mechanism
External FHIR clients	Bearer JWT (Keycloak JWKS); SMART on FHIR scopes
External HL7 v2 MLLP	Per-connector: client certificate (mutual TLS) or shared secret
Internal service calls	JWT service account; bypasses ABAC patient-level check
Bulk export file download	Signed URLs (MinIO presigned) with TTL

---

2. RBAC Matrix

Role	Scopes	Capabilities
interop:fhir:read	SMART user/*.read	FHIR resource reads through gateway
interop:fhir:write	SMART user/*.write	FHIR resource creates/updates
interop:admin	svc:interop:admin	Connector management, routing rules, message log
interop:bulk	svc:interop:bulk-export	Initiate bulk $export
interop:import	svc:interop:bulk-import	Initiate bulk $import (admin only)
platform:admin	All	Platform-wide

---

3. ABAC at FHIR Boundary

All FHIR read/write operations for patient-linked resources:

1. Resolve tenantId from JWT.
2. Call access-policy-service ABAC check with resourceType, patientId, actorId, tenantId.
3. On denial → OperationOutcome 403 with security issue.
4. Internal service calls (from other platform services) skip patient ABAC; use X-Internal-Service header + validated service JWT.

---

4. HL7 v2 Security

Control	Detail
MLLP transport	TLS 1.2+ required for all production connectors
Client certificates	Preferred auth for external LIS/HIS; signed by enterprise CA
Shared secrets	Fallback; rotated on security events
IP allowlisting	Per-connector source IP ranges allowed at Kong/firewall layer

---

5. Sensitive Data Controls

Data	Control
Connector auth_config	AES-256 column-level encryption at application layer; key in KMS
HL7 raw payloads	PHI; stored encrypted at rest; access logged
Bulk export NDJSON files	Presigned URLs with 1-hour TTL; files deleted after 24 hours
Message log	PHI; RLS enforced; accessed only by admin roles

---

6. Audit Events

Event	When	Fields
interop.fhir.read	FHIR resource read	actorId, resourceType, resourceId, patientId?, tenantId
interop.fhir.write	FHIR resource create/update	actorId, resourceType, operation, tenantId
interop.hl7v2.received	HL7 message ingested	connectorId, messageType, tenantId
interop.bulk_export.started	$export initiated	actorId, groupId, tenantId
interop.connector.activated	Connector enabled	actorId, connectorId, tenantId

---

7. GDPR / Data Residency

• FHIR gateway routes data to owning services; no PHI stored in the gateway itself.
• HL7 message log contains PHI; subject to retention policies per jurisdiction.
• Afghanistan tenants: data residency enforcement prevents routing to non-AFG services.
• Bulk export files stored in MinIO within the tenant's designated region.

---

8. AFG-Core Profile Enforcement

All FHIR writes from external partners are validated against the AFG-Core profile extensions (patient national ID, facility codes, encounter classification). Profile violations return 422 OperationOutcome.