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

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.