Authorization Concepts

Fire Arrow Server uses a rule-based authorization system. Each incoming request is evaluated against a set of rules that determine whether the operation is allowed and, for searches, which resources the client can see.

The Authorization Pipeline

Every request passes through this pipeline:

1. Authenticate -- Validate the bearer token (JWT or API token).
2. Resolve Identity -- Map the token to a FHIR resource (Patient, Practitioner, etc.).
3. Build Rule Set -- Collect all rules matching the client's role.
4. Narrow Search -- For search operations, add conditions so that only authorized resources are returned. On REST, Fire Arrow appends search parameters. On GraphQL, it uses alternative search parameter maps.
5. Execute & Validate -- Run the operation and validate the result against the matching rule's validator.

Rule Structure

Each authorization rule matches a combination of client role, resource type, and operation, then delegates to a validator that decides whether access is granted:

fire-arrow:
  authorization:
    rules:
      - client-role: Patient
        resource: Observation
        operation: read
        validator: PatientCompartment

This rule says: When a Patient reads an Observation, allow it if the Observation is in their patient compartment.

Default Validator

The default-validator applies when no specific rule matches a request. It is strongly recommended to set this to Forbidden:

fire-arrow:
  authorization:
    default-validator: Forbidden

With this setting, any operation that doesn't have an explicit rule is denied. This follows the principle of least privilege -- you grant access explicitly rather than revoking it.

Operations

Fire Arrow defines the following operations that can be used in authorization rules:

Operation	Description
read	Read a single resource by ID (REST GET /fhir/{type}/{id})
search	Search for resources (REST GET /fhir/{type}?...)
create	Create a new resource (REST POST /fhir/{type})
update	Update an existing resource (REST PUT /fhir/{type}/{id})
delete	Delete a resource (REST DELETE /fhir/{type}/{id})
graphql-read	Read a single resource via GraphQL
graphql-search	Search for resources via GraphQL
subscribe	Create or manage FHIR Subscriptions
binary-upload	Upload binary content
generate-durable-token	Generate a durable API token for a resource
generate-one-time-token	Generate a one-time API token for a resource
transaction	Submit a FHIR transaction or batch bundle

GraphQL operations are separate

A rule for read does not automatically grant graphql-read, and a rule for search does not grant graphql-search. If your clients use both REST and GraphQL, you need separate rules for each.

fire-arrow:
  authorization:
    rules:
      # REST access
      - client-role: Patient
        resource: Observation
        operation: read
        validator: PatientCompartment

      # GraphQL access (must be listed separately)
      - client-role: Patient
        resource: Observation
        operation: graphql-read
        validator: PatientCompartment

Search Narrowing

When a client performs a search, Fire Arrow doesn't just check the results after the fact -- it narrows the query itself so the database only returns resources the client is authorized to see. This is both more efficient and more secure than post-hoc filtering.

REST searches: Fire Arrow appends additional search parameters to the query. For example, if a Patient searches for Observations with a PatientCompartment validator, Fire Arrow adds &patient=Patient/123 to ensure only their own observations are returned.

GraphQL searches: Fire Arrow uses alternative search parameter maps to achieve the same narrowing. The GraphQL client doesn't need to add any extra parameters -- the narrowing is applied server-side.

Putting It Together

Here's a minimal but complete authorization configuration:

fire-arrow:
  authorization:
    default-validator: Forbidden
    rules:
      # Patients can read and search their own data
      - client-role: Patient
        resource: Patient
        operation: read
        validator: PatientCompartment
      - client-role: Patient
        resource: Patient
        operation: search
        validator: PatientCompartment
      - client-role: Patient
        resource: Observation
        operation: read
        validator: PatientCompartment
      - client-role: Patient
        resource: Observation
        operation: search
        validator: PatientCompartment

      # Practitioners can read and search all patients
      - client-role: Practitioner
        resource: Patient
        operation: read
        validator: Allowed
      - client-role: Practitioner
        resource: Patient
        operation: search
        validator: Allowed
      - client-role: Practitioner
        resource: Observation
        operation: create
        validator: Allowed

For details on each validator, see Validators. For advanced filtering options, see Identity Filters and Property Filters.