Core Concepts
This page explains the key concepts shared by both Fire Arrow editions. Understanding these concepts will help you design your application's data model and security rules.
FHIR in a Nutshell
HL7 FHIR (Fast Healthcare Interoperability Resources) is an international standard for exchanging healthcare data. FHIR models data as resources -- structured objects like Patient, Observation, CarePlan, or Organization.
Each resource has a type, an ID, and a set of fields defined by the FHIR specification. Resources reference each other through Reference fields (similar to foreign keys in relational databases). For example, an Observation might reference the Patient it belongs to.
Fire Arrow uses FHIR as its data model. You don't need to be a FHIR expert to use Fire Arrow, but understanding a few key resource types will help you set up your security model.
Identity Resources
When a user authenticates with Fire Arrow, they are mapped to a FHIR identity resource. This mapping is the foundation of Fire Arrow's security model. The supported identity resource types are:
| Identity Type | Typical Use Case |
|---|---|
| Patient | End users who are patients in your application |
| Practitioner | Healthcare professionals, administrators, or staff |
| RelatedPerson | Caregivers, family members, or legal guardians |
| Device | Service accounts, automated systems, or API integrations |
The identity mapping happens during authentication: Fire Arrow examines the claims in the OAuth token (such as sub, email, or custom claims) to find or create the corresponding FHIR resource. Once mapped, all authorization decisions are based on this identity.
Role-Based Access Control (RBAC)
Fire Arrow's RBAC system determines what each authenticated user can do. It works through validation rules that you define in your configuration file. Each rule specifies:
- Client role -- which identity type the rule applies to (Patient, Practitioner, RelatedPerson, or Device)
- Resource type -- which FHIR resource type the rule governs (e.g., Observation, CarePlan)
- Operation -- what action is being performed (read, search, create, update, delete)
- Validator -- the logic that determines whether access is allowed
Validators
Validators are the building blocks of Fire Arrow's authorization system. Each validator implements a specific access control strategy:
- Allowed / Forbidden -- unconditionally allow or deny access
- PatientCompartment -- allow access only to resources in the patient's FHIR compartment (resources directly linked to the patient)
- PractitionerCompartment -- allow access to resources linked to the practitioner
- OrganizationCompartment -- allow access to resources within the user's organization
- LegitimateInterest -- a sophisticated validator that checks organizational relationships and PractitionerRole assignments to determine access
- GeneralPractitioner -- grants access based on the general practitioner relationship
The same validator concepts apply in both Fire Arrow Core and Fire Arrow Server, though Server offers additional validators like CareTeam and advanced features like identity filters and property filters.
Compartments
FHIR defines compartments as logical groupings of resources centered around a specific resource. For example, the Patient compartment includes all resources that are directly associated with a particular patient (their observations, conditions, medications, etc.).
Fire Arrow uses compartments as the primary mechanism for scoping access. When a validation rule uses a compartment-based validator (like PatientCompartment), Fire Arrow automatically restricts search results and read access to only those resources that belong to the authenticated user's compartment.
Organizations and Multi-Tenancy
For applications that serve multiple organizations (clinics, hospitals, insurance companies), Fire Arrow supports multi-tenancy through the FHIR Organization resource and the LegitimateInterest, CareTeam (Server only) and OrganizationCompartment validators.
Organizations can form hierarchies using the Organization.partOf reference. The LegitimateInterest and CareTeam validators can be configured to traverse these hierarchies, allowing parent organization staff to access data from child organizations.
This approach keeps your tenant model in the FHIR data itself, rather than requiring separate databases or infrastructure per tenant.