Multi-Tenant Access Control | Medplum

Overview

What is a tenant?

In healthcare applications, Practitioners often work across multiple organizational boundaries. A doctor might work at multiple clinics, a nurse might be part of several care teams, or a care coordinator might manage patients across different healthcare services. Each of these logical groupings represents a distinct tenant in your system: a collection of FHIR resources (Patients, Observations, Encounters, etc.) that make sense to be grouped together.

Using this model will allow you to restrict Users' access to only the resources that are part of the tenant(s) that you assign them to. This diagram shows how your User's access is determined by the tenant(s) that you assign them to and the Patients that belong to those tenants.

Step 1: Modeling your tenants

The first decision you need to make is which FHIR resource type semantically models your tenants. Common choices include:

• Organization: Best for Managed Service Organizations (MSOs) where tenants represent different clinics, practices, or healthcare organizations.
• HealthcareService: Best for service-based access control where tenants represent different departments or services (e.g., Cardiology Department, Oncology Department).
• CareTeam: Best for care coordination scenarios where clinical data needs to be tightly contained to the providers working directly with a patient.

You can use any FHIR resource type that accurately models your tenants. The implementation patterns shown in the following steps apply regardless of your choice.

Step 2: Assigning data to tenants

Once you've decided on your tenant resource type and created your tenant resources, you need to associate your data (patients, observations, encounters, etc.) with those tenants. This is done using compartments and the $set-accounts operation.

Most implementations will be able to just assign Patients to tenants.

Understanding Compartments

Compartments are an advanced FHIR concept that gives you a way to label a resource with a reference to a tenant that the resource belongs to. For example, this would be the basic structure of a Patient that belongs to a tenant (Organization, HealthcareService, or CareTeam):

//This Patient belongs to the clinic-a tenant
{
  "resourceType": "Patient",
  "meta": {
    "compartment": [{ "reference": "Organization/clinic-a" }]
  }
}

Adding references to the meta.compartment field

In all resources, the meta.compartment field is readonly. You cannot modify it directly. Instead, you need to use the $set-accounts operation to add references to the meta.compartment field.

Step 3: User Registration & Management

Once you've modeled your tenants and associated data with them, you also need to give your Practitioner Users access to those tenants. This is done through AccessPolicies and ProjectMembership configuration.

Create AccessPolicies with Parameterized Variables

Your AccessPolicy uses parameterized variables (like %organization, %healthcare_service, or %care_team) that get replaced at runtime with the tenant references from the user's ProjectMembership. These variables are used in the compartment section and for Criteria-based Access Control.

Configure ProjectMemberships to Reference Tenants

The User's ProjectMembership references their enrolled tenants via the access.parameter array. Each parameter name must match the variable name used in the AccessPolicy (e.g., if your AccessPolicy uses %organization, the User's ProjectMembership access.parameter should be named "organization").

Conclusion

Multi-tenant access control in Medplum enables you to securely partition healthcare data within a single project by leveraging FHIR compartments and parameterized access policies.