legitimate-interest

legitimate_interest Validator Documentation
Advanced Policy-Driven Access Control for FHIR Resources

---

Intent

The legitimate_interest validator enforces granular, context-aware access rules to comply with regulatory frameworks (e.g., GDPR) or organizational policies. Unlike static compartment validators, it dynamically evaluates relationships between users, resources, and organizations to determine if a "legitimate interest" exists for accessing data.

Why Use This Validator?

• Multi-Tenant Systems: Manage access across organizations sharing a single FHIR repository.
• Regulatory Compliance: Enforce GDPR-like rules where access requires explicit justification.
• Hierarchical Access: Support nested organizations (e.g., hospitals with parent/child units).

---

Core Concepts

1. ActiveOrganizations

A practitioner’s ActiveOrganizations are derived from their active PractitionerRole resources:

ActiveOrganizations = PractitionerRole.where(
  practitioner == Practitioner.id && 
  active == true
).organization

Example: A doctor with roles at General Hospital and Cardiology Unit can access both compartments.

2. Organization Compartment

For practitioners, this includes:

• All patients where Patient.managingOrganization matches an active organization.
• All resources in those patients’ compartments (e.g., Observations, Appointments).

3. Role Inheritance

Configure legitimate_interest.role_inheritance_levels to allow roles to cascade down organizational hierarchies.

• Level 0: No inheritance (default).
• Level 2: Inherit roles from two parent levels (e.g., hospital → department → ward).

---

Detailed Workflow

For Patient Clients

1. Role Check: Confirm the client has the Patient role.
2. Resource Validation:
   • If the resource is in the patient_compartment, allow access.
   • If the resource is an Organization, allow access if it matches Patient.managingOrganization.
   • If the resource is a Practitioner or PractitionerRole, allow access if linked to the patient’s managing organization.

Example:
A patient can view their managing organization (Organization/123) and practitioners affiliated with it, but not other organizations.

For Practitioner Clients

1. Role Check: Confirm the client has the Practitioner role.
2. Fetch ActiveOrganizations: Query active PractitionerRole entries for the practitioner.
3. Resource Validation:
   • Direct Access: Resource references an ActiveOrganization (e.g., Organization/123).
   • Indirect Access: Resource belongs to a patient in the practitioner’s organization compartment.

Example:
A practitioner with ActiveOrganizations = [Organization/123] can:

• Read Patient resources where Patient.managingOrganization = Organization/123.
• Read Observation resources for those patients.

---

Advanced Configuration

1. Role-Specific Access

Require specific practitioner roles using required_role_system and required_role_code:

{
  "client_role": "Practitioner",
  "entity_name": "Patient",
  "operation": "write",
  "validator": "legitimate_interest",
  "params": {
    "required_role_system": "http://hospital.org/roles",
    "required_role_code": "admin"
  }
}

Explanation: Only practitioners with an active PractitionerRole containing role.code = "admin" can modify patient records.

2. Caching Behavior

• Cache Scope: Stores PractitionerRole, Organization, and Patient data.
• Timeout: 2 minutes (configurable via cache_ttl).
• Limitation: Updates to roles/organizations may take up to 2 minutes to reflect.

Mitigation Strategies:

• Pair read/write rules for the same resource to trigger cache invalidation.
• Use webhooks to manually clear the cache on critical updates.

---

Validation Strategy Table

Entity-Specific Rules (Simplified)

Resource Type	Practitioner Validation	Patient Validation
Patient	managingOrganization ∈ ActiveOrganizations	organization_compartment
Observation	subject.managingOrganization ∈ ActiveOrganizations	patient_compartment
Organization	ID ∈ ActiveOrganizations	Must match Patient.managingOrganization
PractitionerRole	organization ∈ ActiveOrganizations	Must be in Patient.general_practitioner
Appointment	actor.managingOrganization ∈ ActiveOrganizations	patient_compartment

---

Role Inheritance Deep Dive

Configuration

# config.yaml
legitimate_interest.role_inheritance_levels: 2

Use Case: Hospital Hierarchy

• Structure:
  • Root: Organization/hospital
  • Children: Organization/cardiology, Organization/orthopedics
• Behavior:
  • A practitioner with roles at Organization/hospital can access data in child departments.
  • A practitioner at Organization/cardiology cannot access Organization/orthopedics unless explicitly granted.

Performance Impact

• Network Requests: Each inheritance level adds 1 request to resolve parent-child relationships.
• Recommendation: Limit inheritance to 2–3 levels for latency-sensitive systems.

---

Best Practices

1. Avoid Overcomplication

• Use patient_compartment for simple patient-owned data.
• Reserve legitimate_interest for multi-organization or regulatory scenarios.

2. Error Handling

• Cache Misses: Log warnings when cached data is stale.
• Role Conflicts: Prioritize required_role_code over inherited roles.

3. Testing

• Unit Tests: Validate rules against mock FHIR resources.
• Edge Cases: Test access denials for:
  • Practitioners with expired roles.
  • Patients accessing disassociated organizations.

---

FHIR Resource Links

1. PractitionerRole: FHIR R4 Specification
2. Compartments: FHIR Compartment Guide
3. GDPR & Legitimate Interest: GDPR Article 6(1)(f)

---

Example: GDPR-Compliant Access

Scenario: A patient requests access to all data shared with their managing organization.

Validator Workflow:

1. Patient requests Bundle of resources.
2. legitimate_interest allows:
   • Resources in their patient_compartment.
   • Organization and PractitionerRole linked to their managing organization.
3. Blocks access to unrelated resources (e.g., another patient’s DiagnosticReport).

---