Authentication Overview

Fire Arrow Server authenticates incoming requests using JWT tokens (OAuth 2.0 / OpenID Connect) or API tokens. Multiple authentication providers can be active at the same time, so you can support different identity providers for different clients or environments from a single deployment.

How Authentication Works

Every authenticated request goes through three stages: token validation, identity resolution, and role assignment.

1. Token Validation

Fire Arrow validates the bearer token against the configured provider(s). For JWTs, this means verifying the signature using the provider's JWKS endpoint, checking the audience and expiration. For API tokens, Fire Arrow verifies the HMAC signature and looks up the linked identity.

2. Identity Resolution

After validating the token, Fire Arrow resolves the caller's identity to a FHIR resource. The resolution follows a priority chain:

1. Identifier system lookup - If the provider has an identifier-system configured, Fire Arrow searches for a resource whose identifier matches the token's subject claim in that system.
2. Email fallback - If no match is found by identifier, Fire Arrow searches for a resource matching the token's email claim.
3. Auto-create - If auto-create-enabled is set and no existing resource is found, Fire Arrow creates a new FHIR resource from the token claims.

The resolved resource is always one of: Patient, Practitioner, RelatedPerson, or Device.

3. Role Assignment

The resource type of the resolved identity determines the client's role for authorization:

Resolved Resource	Client Role
Patient	Patient
Practitioner	Practitioner
RelatedPerson	RelatedPerson
Device	Device
(unauthenticated)	Public

This role is then matched against authorization rules to determine what the client can do.

Configuration Overview

Authentication is configured under the fire-arrow.authentication key in your application.yaml. Each provider is identified by a unique name:

fire-arrow:
  authentication:
    providers:
      my-oidc-provider:
        type: oidc
        oidc-uri: https://login.example.com/.well-known/openid-configuration
        audience: api://fire-arrow
        # ... additional settings
      my-service-provider:
        type: azure-identity
        # ... additional settings
    api-tokens:
      hmac-secret: ${API_TOKEN_SECRET}

See the following pages for detailed configuration of each authentication method:

• OAuth / OIDC Providers - configure JWT-based authentication with identity providers
• API Tokens - configure durable and one-time tokens for programmatic access
• Web UI Sign-In - configure how users log in to the administration web UI
• Delegated Access with $drop-privilege - mint short-lived tokens scoped down to a single identity

Web UI Sign-In

The description above covers how Fire Arrow authenticates API requests. Users who open the built-in administration web UI sign in interactively through OpenID Connect. Sign-in runs through a server-side Backend-for-Frontend (BFF): the server acts as a confidential OAuth client, holds the tokens on the server, and gives the browser only a session cookie. Each login profile therefore requires a client secret. See Web UI Sign-In for configuration and upgrade guidance.

Unauthenticated Requests

Requests without an Authorization header are assigned the Public role. Whether public access is allowed depends on your authorization rules. A common pattern is to deny all operations for the Public role except a narrow set of read-only resources.