Skip to main content

Supported authentication systems

Each request can be authenticated through a different system. An arbitrary number of authentication system configurations can be specified in the configuration file.

Every listed authentication system imposes overhead on every request because the authentication token needs to be decoded and potentially keys or other data needs to be fetched the corresponding authentication servers.

When configuration authentication systems, the most used system should be at the top. Only those authentication systems which will see actual client requests should be configured.

OAuth 2.0​

Fire Arrow supports OAuth 2.0.

OAuth configuration object
{
    "type": "oauth",
    "parameters": {
        "identifier": "Azure B2C",
        "oidc_url": "https://login.microsoftonline.com/1234-5678-9765-4567/v2.0/.well-known/openid-configuration",
        "entity_type_claim": "extension_entityType",
        "entity_id_claim": "extension_entityId"
    }
}

The identifier property can be set to any human readable name that identifies this system in diagnostic logs.

Server-specific configuration can be done through either specifying the OpenID Connect well-known URL in oidc_url or specifying issuer and jwks_url manually. If all three are specified, the OpenID Connect URL will take precedence.

The OAuth authentication system supports the following roles:

  • Patient
  • Practitioner
  • RelatedPerson
  • Device

The role of the client needs to be sent as token claim in the field configured by entity_type_claim.

If the OAuth server also knows the client's ID (meaning, the FHIR ID of the resource representing the client's identity), the corresponding token claim can be configured in entity_id_claim.

If no entity ID claim exists in the token, the OAuth system will attempt to automatically identify the client through a fallback search mechanism.

One of Fire Arrow's design goals was to be as independent as possible from the authentication service so that users of Fire Arrow could be free to choose how to authenticate users.

While an authentication service is able to assert that a user is who they claim to be (for example that the user is foo@bar.com), the authentication service usually won't be able to provide a FHIR-specific patient or practitioner ID, unless that data is synchronized back into the authentication service.

Fire Arrow works around this problem by providing a fallback entity search that is activated whenever an entity ID is missing in the authentication claim.

If the primary claim specified via entity_id_claim is not contained in the token, the OAuth service inspects the email and phone number claims in the supplied tokens. If an email address is contained, it will search the FHIR database for a matching entity. If the result is empty and a phone number is specified, phone number will be attempted.

Example:

  • A client sends a token with the value Patient in the entity_type_claim claim and gets the role Patient assigned.
  • The claim entity_id_claim doesn't exist in the token, but the email claim is set to foo@bar.com
  • The OAuth system will search the FHIR server for Patient.email = foo@bar.com. If a result is found, it will become the client's identity.

Azure Identity​

Azure Identity is supported for service-to-service authentication. If a queue processor is deployed next to Fire Arrow, the queue processor can fetch an authentication token via Azure Identity and use it to access Fire Arrow's GraphQL API.

Configuration requires specifying the deployment's tenant ID as well as the ID of the application exposing Fire Arrow's API permissions:

Azure Identity configuration object
{
    "type": "azure_identity",
    "parameters": {
        "tenant_id": "8a0d55a8-3deb-40a8-b5b4-e598f9448aef",
        "application_id": "7c8807a2-7855-4386-bea0-69e0738dbe37"
    }
}

Exposing an API can be achieved by following Microsoft's Azure documentation. A client application needs to be assigned permissions to access the API (for example by assigning corresponding roles to its managed identity) and needs to retrieve an access token by using the Azure Identity SDK / API.

Any client authenticating this way will be assigned the Device role.