Role-Based Access Control (RBAC) Implementation Guide

Core Concepts

Medbackend's FHIR-based RBAC system provides granular access control through configurable validation rules. Key principles:

• Compartment-based security: Automatic filtering of resources based on patient/practitioner/organization relationships
• Zero-trust default: "Forbidden" baseline with explicit access grants
• Context-aware validation: Dynamic request modification to enforce access policies
• Multi-tenancy support: Built-in isolation mechanisms for organizational data separation

Request Validation Workflow

Critical Components:

1. Azure B2C: Manages client identities and authentication
2. JWT Validation: Verifies token signatures using rotating Azure JWKS keys
3. FHIR RBAC Engine: Applies compartment rules and validation logic
4. Request Modifiers: Dynamically adjust queries to enforce access constraints

Validator Types & Strategies

Compartment Validators

Validator	Scope	Validation Fields	Typical Use	FHIR References
patient_compartment	Direct patient ownership	subject, patient, performer	Patient portals	Patient Compartment
practitioner_compartment	Clinical staff context	practitioner, requester	EHR access	Practitioner Role
relatedperson_compartment	Family/caregiver relationships	patient, relatedPerson, relationship	Family portals	RelatedPerson
encounter_compartment	Care episode context	encounter, context, basedOn	Surgical workflows	Encounter

Specialized Validators

Validator	Purpose	Use Case Example
organization_compartment	Organization-associated resources	Multi-tenant systems
legitimate_interest	GDPR-compliant access without explicit consent	Emergency access
general_practitioner	Verified practitioner-patient relationships	Primary care coordination
allowed/forbidden	Explicit access override	Public APIs/Admin interfaces
device_compartment	Device-linked resources	IoT/remote monitoring

Implementation Examples

Patient Compartment Rule

{
    "client_role": "Patient",
    "entity_name": "Observation",
    "operation": "search",
    "validator": "patient_compartment"
}

Query Transformation:

# Original Query
query {
    Observation { id }
}

# Modified Execution
query {
    Observation(subject: "Patient/123") { id }
}

Practitioner Role Restriction

{
    "client_role": "Practitioner",
    "entity_name": "Patient",
    "operation": "search",
    "validator": "legitimate_interest",
    "required_role_system": "http://hl7.org/fhir/ValueSet/practitioner-role",
    "required_role_code": "ict"
}

Configuration Strategy

Default Access Configuration

{
    "rbac": {
        "default_access": "Borbidden",
        "validation_rules": [
            // Role-specific rules
        ]
    }
}

Security Recommendations:

• Start with "default_access": "Forbidden"
• Never use Allowed as default in production
• Disable RBAC only for public APIs using:

  {
    "rbac": {
        "default_access": "Allowed",
        "validation_rules": []
    }
  }

Rule Definition Structure

{
    "client_role": "<RoleName>",
    "entity_name": "<FHIRResource>",
    "operation": "<search|create|read|update|delete>",
    "validator": "<ValidatorType>",
    // Optional role constraints
    "required_role_system": "<CodingSystem>",
    "required_role_code": "<CodeValue>"
}

Extend with Webhooks

Any validation rule can include pre_request_hook or post_response_hook to add custom validation logic or trigger external workflows. See Webhooks for details.

Validation Hierarchy:

1. Client Role → Resource Type → Operation
2. First matching rule applies (order-sensitive)
3. System logs warnings for ambiguous rules

RBAC Design Methodology

Access Matrix Template

Role	Resource	Operations	Validator	Constraints
Nurse	Patient	search, read	practitioner_compartment	role_code: "nurse"
Doctor	Patient	search, read, update	practitioner_compartment	role_code: "doctor"
ICT Admin	Patient	create	legitimate_interest	role_code: "ict"

Implementation Checklist

1. Define all client roles and associated FHIR resources
2. Map operations (CRUD) per role/resource combination
3. Select appropriate validator for each access pattern
4. Implement compartment boundaries for multi-tenancy
5. Test all rules with realistic query scenarios
6. Audit rule conflicts and validation order
7. Configure monitoring for RBAC events

Advanced Validation Patterns

Composite Validation

[
    {
        "client_role": "Practitioner",
        "entity_name": "Observation",
        "operation": "search",
        "validator": "organization_compartment"
    },
    {
        "client_role": "Practitioner",
        "entity_name": "Observation",
        "operation": "create",
        "validator": "practitioner_compartment"
    }
]

Performance Considerations

• Compartment validators add 0-5ms overhead per request
• LegitimateInterest checks typically add 2-8ms
• Always test with production-like datasets
• Use field projection to minimize data transfer:

  query {
      PatientList {
          id
          name {
              given
              family
          }
      }
  }

Audit & Monitoring

Key metrics to track:

• Rule match rates
• Validation latency per type
• Access denial patterns
• Compartment crossover attempts
• Role assignment drift

Reference Documentation

1. FHIR Compartments R4 Specification
2. Extended Compartment Use Cases