organization-compartment

OrganizationCompartment Validator Documentation
Custom FHIR Compartment for Multi-Tenant Access Control

---

Intent

The OrganizationCompartment validator creates an artificial FHIR compartment using extensions, enabling granular access control for resources that lack inherent organization associations. This is critical for multi-tenant systems (e.g., SaaS healthcare platforms) where organizations share a database but require data isolation.

Key Use Cases:

• Restricting access to patient consent documents (Consent) to the organization that created them.
• Allowing practitioners to view only resources linked to their organization’s compartment.
• Enforcing GDPR compliance by isolating sensitive resources like research agreements.

---

Key Features

1. Extension-Based Tagging:
   • Resources are tagged with a custom extension:

     "extension": [{
       "url": "https://medbackend.com/fhir/Extensions/organization-compartment",
       "valueReference": {
         "reference": "Organization/<org_id>"
       }
     }]
   • Tagged resources become part of the referenced organization’s compartment.
2. Role Inheritance:
   • Configure legitimate_interest.role_inheritance_levels to grant parent organizations access to child org resources (e.g., hospital admins accessing department data).

---

Validation Logic

Step	Action	Error If Failed
1	Check client_role is Practitioner.	403 Forbidden (Invalid role)
2	Verify the resource has the organization-compartment extension.	403 Forbidden (Not in compartment)
3	Validate the extension’s Organization reference matches one of the practitioner’s active organizations (from PractitionerRole.organization).	403 Forbidden (Org mismatch)
4	If role inheritance is enabled, check parent/child org relationships.	403 Forbidden (Hierarchy mismatch)

---

Example Configurations

1. Read Access to Consent Documents

{
  "client_role": "Practitioner",
  "entity_name": "Consent",
  "operation": "read",
  "validator": "organization_compartment"
}

Explanation: A practitioner can read a Consent resource only if:

• The resource has the organization-compartment extension.
• The extension references an organization linked to the practitioner’s active PractitionerRole.

2. Resource Tagging Example

A Consent resource linked to Organization/123:

{
  "resourceType": "Consent",
  "extension": [{
    "url": "https://medbackend.com/fhir/Extensions/organization-compartment",
    "valueReference": {
      "reference": "Organization/123"
    }
  }],
  "status": "active",
  "scope": {
    "text": "Treatment"
  }
}

---

Role Inheritance Configuration

Control hierarchical access in config.yaml:

legitimate_interest.role_inheritance_levels: 2  # Inherit roles from 2 parent org levels

Use Cases:

1. Hospital Hierarchy: A root hospital (Organization/root) accesses data from its cardiology department (Organization/cardiology).
2. SaaS Support: A root org’s admins troubleshoot issues across all client orgs.

Performance Note: Each inheritance level adds a network request. Use 0 to disable.

---

FHIR References

1. Consent Resource:
   FHIR R4 Consent (Authorization rules for data access).
2. Extensions:
   • Custom Extensions Guide (Defining custom FHIR extensions).

---

Use Case: Multi-Tenant Consent Management

A SaaS platform uses this validator to:

1. Isolate Consent Documents: Clinic A cannot access Clinic B’s Consent resources.
2. Enable Cross-Org Audits: Root org auditors review child org consents via role inheritance.

Error Handling:

• A practitioner from Organization/456 trying to access the above Consent resource receives 403 Forbidden.