Minimal Configuration

Fire Arrow Server is configured through a single application.yaml file located at src/main/resources/application.yaml. This guide covers the essentials to get authentication and authorization working.

Configuration Structure

The configuration is organized into three main sections:

Section	Purpose
spring	Database connection (datasource), migrations (flyway), and other Spring Boot settings
hapi.fhir	FHIR server behavior - supported resources, paging defaults, narrative generation
fire-arrow	Fire Arrow features - authentication, authorization, CarePlan scheduling, subscriptions

Most of the default values work well for development. The sections below focus on the settings you'll typically want to configure first.

Enabling Authentication

To secure your server with OAuth 2.0 / OIDC, add an authentication provider under the fire-arrow section:

fire-arrow:
  authentication:
    enabled: true
    providers:
      - name: my_oauth
        type: oidc
        enabled: true
        oidc-uri: "https://your-idp.example.com"
        audience: "your-client-id"
        api-scope: "fhir.access"
        claim-mapping:
          scope-claim: "scp"
          roles-claim: "roles"
          subject-claim: "sub"
          email-claim: "email"
          name-claim: "name"
          fhir-resource-type-claim: "resource_type"
          fhir-id-claim: "fhir_id"
        identity-resolution:
          identifier-system: "https://your-app.example.com/fhir/user-id"
          auto-create-enabled: true

Replace the placeholder values with your identity provider's details:

• oidc-uri - your IdP's issuer URL (the server appends /.well-known/openid-configuration automatically)
• audience - the client ID or audience your tokens are issued for
• api-scope - the scope required to access the FHIR API
• claim-mapping - maps token claims to Fire Arrow's internal identity model
• identity-resolution - controls how authenticated users are linked to FHIR resources; set auto-create-enabled: true to automatically create Patient or Practitioner resources on first login

Setting Up Authorization Rules

Once authentication is enabled, you'll want to control what each role can access. Fire Arrow Server uses a role-based access control (RBAC) model where each rule maps a client role, resource type, and operation to a validator.

Here's a minimal set of rules that lets patients see their own data and practitioners search across patients:

fire-arrow:
  authorization:
    default-validator: Forbidden
    validation-rules:
      - client-role: "Patient"
        resource: "Patient"
        operation: "read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Patient"
        operation: "graphql-read"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Observation"
        operation: "search"
        validator: "PatientCompartment"
      - client-role: "Patient"
        resource: "Observation"
        operation: "graphql-search"
        validator: "PatientCompartment"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "read"
        validator: "LegitimateInterest"
      - client-role: "Practitioner"
        resource: "Patient"
        operation: "search"
        validator: "LegitimateInterest"

Key concepts:

• default-validator: Forbidden - any request that doesn't match a rule is denied. This is the recommended default.
• PatientCompartment - ensures patients can only access resources in their own FHIR compartment.
• LegitimateInterest - allows practitioners to access patient data they have a clinical relationship with.
• Operations ending in graphql- are the GraphQL equivalents of the REST operations (graphql-read, graphql-search).

For the full list of validators and advanced features like identity filters and property filters, see Authorization Concepts.

Environment Variable Overrides

Every YAML property can be overridden with an environment variable. Spring Boot converts nested keys to uppercase with underscores. Some useful examples:

YAML Path	Environment Variable	Example
fire-arrow.authentication.enabled	FIRE_ARROW_AUTHENTICATION_ENABLED	true
spring.datasource.url	SPRING_DATASOURCE_URL	jdbc:postgresql://db:5432/hapi
spring.datasource.username	SPRING_DATASOURCE_USERNAME	hapi
spring.datasource.password	SPRING_DATASOURCE_PASSWORD	secretpassword

This is especially useful for Docker deployments and CI/CD pipelines where you don't want secrets in your YAML files.

Next Steps

With authentication and authorization configured, you're ready to start making requests. Head to Making Requests for examples using curl, GraphQL, and the built-in tools.