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.

Provider Types​

OIDC Provider​

Azure Identity Provider​

Claim Mapping​

User Tokens vs. Application Tokens​

User Tokens (Authorization Code Flow)​

Application Tokens (Client Credentials Flow)​

Identity Resolution​

Full Configuration Example​