Access Control Decision Guide

Companion to the Authorization and Access Control docs.

Section 1: Use Case & Participants

1.1 Who are the users?

• Patients only
• Providers / staff / partners (clients or outside vendors) only
• Both

1.2 What is your organizational structure?

• Single organization
• Multiple locations of one organization
• Multiple independent organizations (MSO-style)
• Departments or service lines within one organization
• Combination

Why: biggest driver of downstream design. If single org with no internal isolation, skip Section 2.

Section 2: Multi-tenancy

Skip if single-organization with no internal isolation.

Isolation uses compartments (meta.compartment) matched by parameterized access policies.

Design principle (from Medplum docs): Push complexity into enrollment Bots, not policies. Each patient is tagged with their tenant(s); each practitioner’s ProjectMembership.access lists every tenant they work in. See the MSO demo enrollment.ts for reference.

2a Tenant Modeling

Questions:

• Internal term for tenants? (clinics, programs, sites, accounts)
• Grouping is organizational, functional, or per-patient?
• Is there an organizational hierarchy (e.g., region → clinic)?

Hierarchy pattern (if tenants nest, e.g., region → clinic):

• Patients are tagged only at the lowest level they belong to.
• Practitioners enrolled at an intermediary level get one ProjectMembership.access entry per lowest-level tenant under it (iteratively expanded).
• Adding a new lowest-level tenant requires a workflow to update every practitioner membership at or above that intermediary.

2b Patient and Practitioner Sharing

Questions:

• Can a patient be enrolled in more than one tenant at a time?
• Are practitioners isolated to their tenant, or visible across all tenants (global directory)?

Section 3: Roles & Permissions

For each role: name it, scope it (which tenants, if multi-tenant), say what resources it touches, and narrow as needed.

3a Role Inventory & Scope

Questions:

• What are the role names? (physician, RN, MA, front desk, billing, care coordinator, medical director)
• If multi-tenant: for each role, which tenants does it cover? (one, several, all)
• Any oversight roles that need visibility across all tenants without per-tenant enrollment?

⚠ One-way door: stacking is additive only. Policies compose by union — you can’t narrow by composition. For genuinely narrower API access in one context (not just a filtered UI view), use separate logins, not stacked policies.

3b Permission Mechanics

Questions:

• For each role: which resource types does it read / write / search / delete?
• Any partial FHIR interactions? (create-only, read-without-search, etc.)

3c Narrowing What a Role Can Do

Cover only the knobs that apply.

Field-level — partial field access (e.g., billing sees Patient minus diagnoses):

Write constraints — enforce state transitions or required fields at the policy layer:

Keep FHIRPath simple; complex logic belongs in a Bot.

Criteria-based filtering — filter by resource attribute (geography, code, status):

criteria supports only :not / :missing — no chained searches. Denormalize or tag via an enrollment Bot.

Section 4: Admin Structure

Questions:

• Who invites/removes users and manages memberships?
• Who manages Bots, ClientApplications, AccessPolicies?
• Any super admin needs? (project creation via API, overwriting protected fields)
• Should admins be blocked from clinical data?

⚠ Note: Admin flag covers admin resources only (Project, ProjectMembership, User) — admins still need a policy for clinical data.

Appendix: Additional Decisions

Narrower decisions that apply only in specific situations. Cover each only if relevant.

A. Open Registration & Caregivers

If the product has a patient portal.

Questions:

• Self-registration or staff-invite?
• Are caregivers / proxies needed? (parents, adult children, guardians)
• One caregiver with multiple patients? One patient with multiple caregivers?
• How is the caregiver relationship established and revoked?

B. SMART on FHIR

If third-party apps (not your own frontend) request access.

Questions:

• Patient-context launch, provider-context launch, or standalone?
• Which scopes?
• Offline access needed?

⚠ Note: Effective access = SMART scopes ∩ AccessPolicy.

C. IP Access Rules

If access should be restricted by IP range.

Questions:

• Restrict by IP range? (VPN, on-prem devices)
• Any roles that bypass?

⚠ Note: IPv4 only. Rules evaluate sequentially — always terminate with a wildcard block.

D. Enrollment & Reassignment Workflows

If Section 2 multi-tenancy applies.

Questions:

• When does a patient get enrolled in a tenant? (registration, first appointment, referral, insurance, geography)
• Who is authorized to move a patient between tenants?
• On transfer: do records follow the patient, stay with the original tenant, or become shared?

Reference implementation: MSO demo enrollment.ts — canonical example patterns.

E. Shared vs. Tenant-Specific Resources

If Section 2 multi-tenancy applies.

Questions:

• Terminology (CodeSystems, ValueSets) shared or tenant-specific?
• Questionnaires shared or per-tenant?
• PlanDefinitions / ActivityDefinitions global or per-tenant?
• Any resources shared across projects (not just tenants)?

⚠ Note: Forgetting unfiltered read on standard terminology causes empty dropdowns — a common multi-tenant misconfiguration.

F. Role-Aware UI

If your frontend needs to show / hide UI based on the user’s role

Using AccessPolicy.basedOn keeps the UI in sync with what the API enforces. The alternative (hardcoded role field, custom endpoint) tends to drift.