Introduction

This document describes the core concepts of Medplum Access Controls. Security and access controls are notoriously difficult. Complex business and regulatory requirements often lead to a mess of incomprehensible rules. Medplum strives to create a simple and understandable model, which is flexible enough to handle all unique security needs.

Core Model

All resources exist within a "Project". A project is a top-level container. In general, each healthcare organization will have one project for all of their resources.

Every user account can have one or more "Project Memberships". A project membership represents access to resources within a project. The user can either be granted access to all resources within the project, or limited access to a set of compartments.

Access Policies

Users within a Project can be assigned Access Policies. Access Policies are an advanced method of restricting access to certain resource types or even certain fields within a resource type.

Access policies allow you to:

• Block access to any resource type
• Grant read only access to any resource type
• Grant read/write access to any resource type
• Grant read only access to any property
• Grant read/write access to any property

Access policies also allow you to grant access by "Compartment".

Examples

Resource Type

The following access policy grants read/write access to only the "Patient" resource type:

{
  "resourceType": "AccessPolicy",
  "name": "Patient Example",
  "resource": [
    {
      "resourceType": "Patient"
    }
  ]
}

Criteria-based Access Control

You can narrow the set of resources the user has access to by using the criteria field. The following policy uses a FHIR Search Query to grant access only to Patient resources who live in California.

{
  "resourceType": "AccessPolicy",
  "name": "Criteria Based Access Policy",
  "resource": [
    {
      "resourceType": "Patient",
      "criteria": "Patient?address-state=CA"
    }
  ]
}

Read-only Access

The following access policy grants read-only access to the Patient resource type:

{
  "resourceType": "AccessPolicy",
  "name": "Patient Example",
  "resource": [
    {
      "resourceType": "Patient",
      "readonly": true
    }
  ]
}

FHIR Interactions

The above read-only access is special case of the more general ability to control which interactions are allowed for a set of resources. The AccessPolicy.resource.interaction field can specify a subset of FHIR interactions that can be performed on resources of the given type. The following are equivalent:

{
  "resourceType": "AccessPolicy",
  "name": "Read-only modes",
  "resource": [
    {  
      "resourceType": "*",
      "readonly": true,
    },
    {  
      "resourceType": "*",
      "interaction": ["read", "search", "history", "vread"]
    }
  ]
}

Compartments

All resources can be tagged with one or more "Compartments". A compartment is simply a group of resources. Importantly, compartments are not mutually exclusive. A resource can (and often will) exist in multiple compartments.

For example, consider an "Observation" resource representing a blood pressure measurement. That Observation resource will fall into the following Compartments:

• "Patient" - for the "subject" of the observation
• "Practitioner" - for the "performer" of the observation
• "Encounter" - for the "encounter" of the observation

Resources are automatically assigned to compartments based on rules. Currently, the Medplum server automatically assigns resources to the "Patient" compartment. You can find the full definition of the patient compartment here.

You can use compartments to succinctly create an AccessPolicy for resources related to a single patient.

Example Access Policies

Healthcare Partnerships

A common need is to grant access to a subset of resources for a healthcare partnership. For example, a lab provider may want to grant access to all patient records that originated from a specific client organization.

This can be achieved using Access Policy compartments.

Assume that we have an Organization resource representing the customer:

{
  "resourceType": "Organization",
  "name": "Example Customer Organization",
  "id": "abc-123"
}

This access policy grants read-only access to all Patients that are within that customer's "account" compartment:

{
  "resourceType": "AccessPolicy",
  "name": "Patient Example",
  "compartment": {
    "reference": "Organization/abc-123",
    "display": "Example Customer Organization"
  },
  "resource": [
    {
      "resourceType": "Patient",
      "criteria": "Patient?_compartment=Organization/abc-123",
      "readonly": true
    }
  ]
}

Patient Access

If you are building a patient-facing application (such as FooMedical), a common requirement is to restrict each patient's access to only their own data. In this case it is recommended to use templated access policies, that also implement compartments as shown below.

Caregiver Access

The patient access policy above can be combined with policy parameterization to create an policy that allows caregivers to access data on behalf of patients (e.g parents on behalf of children.

{
  "resourceType": "ProjectMembership",
  "access": [
    {
      "policy": { "reference": "AccessPolicy/patient-access-policy-template" },
      "parameter": [
        {
          "name": "patient",
          "valueReference": { "reference": "Patient/xyz" }
        }
      ]
    }
  ]
}

Additional Access Policy Details

The content above outlines various access policies, their configurations, and use-cases demonstrating how to implement secure access control within the Medplum framework.