OAuth / OIDC Providers

Fire Arrow Server supports JWT-based authentication through standard OpenID Connect (OIDC) providers and Azure Identity (for managed-identity service-to-service scenarios). You can configure multiple providers simultaneously.

Provider Types

OIDC Provider

The standard provider for user-facing and service-to-service authentication. It discovers endpoints automatically from the OIDC discovery document.

fire-arrow:
  authentication:
    providers:
      my-oidc:
        type: oidc
        oidc-uri: https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
        audience: api://fire-arrow

Azure Identity Provider

A specialized provider for Azure managed identities and service principals. Use this when Azure services need to call Fire Arrow Server using their managed identity tokens.

fire-arrow:
  authentication:
    providers:
      my-azure-service:
        type: azure-identity
        audience: api://fire-arrow

Azure Identity providers validate tokens against the Azure AD JWKS endpoint and accept tokens issued for the configured audience.

Claim Mapping

Fire Arrow extracts identity information from JWT claims. You can customize which claims are used:

Property	Default	Description
subject-claim	sub	Claim containing the unique subject identifier
email-claim	email	Claim containing the user's email address
scope-claim	scp	Claim containing delegated scopes (user tokens)
roles-claim	roles	Claim containing application roles (service tokens)
given-name-claim	given_name	Claim for given name (used during auto-create)
family-name-claim	family_name	Claim for family name (used during auto-create)

fire-arrow:
  authentication:
    providers:
      custom-idp:
        type: oidc
        oidc-uri: https://idp.example.com/.well-known/openid-configuration
        audience: my-api
        subject-claim: sub
        email-claim: emails
        scope-claim: scope
        roles-claim: groups

User Tokens vs. Application Tokens

Fire Arrow distinguishes between two token types based on how the OAuth flow was performed:

User Tokens (Authorization Code Flow)

Issued when a user signs in interactively. Permissions are carried in the scope claim (scp by default).

Configure which scopes grant API and admin access:

fire-arrow:
  authentication:
    providers:
      my-oidc:
        type: oidc
        oidc-uri: https://login.example.com/.well-known/openid-configuration
        audience: api://fire-arrow
        api-scope: access_as_user
        admin-scope: admin_access

• api-scope -- The scope required to access the FHIR API. Tokens without this scope are rejected.
• admin-scope -- The scope required to access the Admin API (/admin-api/).

Application Tokens (Client Credentials Flow)

Issued to services and daemons without a user context. Permissions are carried in the roles claim (roles by default).

Configure which roles grant API and admin access:

fire-arrow:
  authentication:
    providers:
      my-oidc:
        type: oidc
        oidc-uri: https://login.example.com/.well-known/openid-configuration
        audience: api://fire-arrow
        api-role: FhirApi.ReadWrite
        admin-role: FhirApi.Admin

• api-role -- The role required to access the FHIR API.
• admin-role -- The role required to access the Admin API.

Identity Resolution

Each provider can configure how Fire Arrow resolves the JWT subject to a FHIR resource:

fire-arrow:
  authentication:
    providers:
      my-oidc:
        type: oidc
        oidc-uri: https://login.example.com/.well-known/openid-configuration
        audience: api://fire-arrow
        identifier-system: https://login.example.com
        auto-create-enabled: true
        auto-create-resource-type: Patient

Property	Description
identifier-system	The FHIR identifier system to search. Fire Arrow looks for a resource with an identifier matching {system}|{subject-claim-value}.
auto-create-enabled	When true, Fire Arrow creates a new FHIR resource if no existing match is found. Defaults to false.
auto-create-resource-type	The FHIR resource type to create (Patient, Practitioner, RelatedPerson, or Device). Only used when auto-create is enabled.

The resolution order is always: identifier system lookup -> email fallback -> auto-create (if enabled).

Full Configuration Example

Below is a complete example with an OIDC provider for user-facing apps and an Azure Identity provider for backend services:

fire-arrow:
  authentication:
    providers:
      # User-facing authentication via Azure AD B2C
      azure-b2c:
        type: oidc
        oidc-uri: https://myapp.b2clogin.com/myapp.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_signupsignin
        audience: api://fire-arrow
        api-scope: access_as_user
        admin-scope: admin_access
        subject-claim: sub
        email-claim: emails
        identifier-system: https://myapp.b2clogin.com
        auto-create-enabled: true
        auto-create-resource-type: Patient

      # Service-to-service via Azure Managed Identity
      azure-services:
        type: azure-identity
        audience: api://fire-arrow
        api-role: FhirApi.ReadWrite
        admin-role: FhirApi.Admin
        identifier-system: https://sts.windows.net
        auto-create-enabled: true
        auto-create-resource-type: Device

In this setup:

• Patients sign in through Azure AD B2C. Their tokens carry the access_as_user scope. Fire Arrow looks up their FHIR Patient resource by B2C subject identifier, and auto-creates one if they're signing in for the first time.
• Backend services authenticate with their Azure managed identity. Their tokens carry the FhirApi.ReadWrite role. Fire Arrow maps them to Device resources by Azure AD object identifier.