SMART on FHIR

Azure Health Data Services (AHDS) FHIR service supports Substitutable Medical Applications and Reusable Technologies (SMART on FHIR) by implementing the key server-side behaviors required for SMART clients to securely access FHIR data by using OAuth 2.0 and OpenID Connect. SMART on FHIR is an implementation guide through which applications can access clinical information through a data store. It adds a security layer based on open standards including OAuth2 and OpenID Connect, to FHIR® interfaces to enable integration with EHR systems. Using SMART on FHIR provides at least three important benefits:

• Applications have a known method for obtaining authentication and authorization to a FHIR repository.
• Users accessing a FHIR repository with SMART on FHIR are restricted to resources associated with the user, rather than having access to all data in the repository.
• Users have the ability to grant applications access to a limited set of their data by using SMART clinical scopes.

Prerequisites

Before you begin, make sure you have:

1. An AHDS FHIR service instance.
2. Permissions to configure FHIR authentication settings.
3. An identity provider strategy: Microsoft Entra ID plus an orchestration layer, or A SMART-aware third-party identity provider.
4. A test patient in your FHIR store.
5. A SMART client application (or the SmartLauncher sample for validation).

End to end flow

A SMART client typically performs these steps:

1. Discover: Call /.well-known/smart-configuration on the FHIR server to find endpoints and capabilities.
2. Authorize: Redirect the user to the authorization endpoint with requested SMART scopes.
3. Token: Exchange authorization code for an access token, then call FHIR APIs with the bearer token.
4. Call FHIR APIs: Send the bearer token to the FHIR endpoint. Access is constrained by scopes and context.

Configure access for end users

Assign users to the FHIR SMART user role by using Azure role assignment guidance: Assign Users to Role. Users in this role can access the FHIR service when requests satisfy SMART requirements. Access is limited by fhirUser context and SMART clinical scopes.

Identity provider support

FHIR service provides integration with Microsoft Entra ID or third-party identity providers (IDP) that understand SMART launch context and SMART scope semantics.

The SMART on FHIR specification defines launch context as a set of parameters that are conveyed during the authorization flow and returned as part of the token response. These parameters typically include identifiers such as the patient ID, encounter ID, and the FHIR user (for example, a practitioner or patient), along with optional fields. Technically, this context is passed into the SMART workflow through a parameter called launch, which is intentionally opaque to the application. The application simply receives and forwards this value during the authorization process. This launch parameter maps to a stored context record, which contains the actual patient and encounter identifiers. During the token exchange step, this context is resolved and returned alongside the access token so that the application can make correctly scoped API calls. This mechanism ensures that when an app accesses FHIR data, it operates within a clearly defined clinical boundary.

Identity providers are responsible for authenticating users and issuing tokens, but they don't have visibility into clinical workflows. The application must determine an appropriate patient context, either by prompting the user, selecting a patient from a list, or retrieving it from another system. Regardless of how this context is established, the application must include it in the token that it uses to call the FHIR service.

This architecture provides an orchestration layer that acts as the bridge between the identity provider, the clinical system (such as an EHR), and the FHIR service.

Sample integration

Use the Azure Health Data and AI Samples open source repo to set up the SMART on FHIR experience. The repository provides the sample SMART on FHIR v2 — Native IdP-Agnostic Sample.

This sample demonstrates the creation of an orchestration layer that acts as the bridge between the identity provider, the clinical system (such as an EHR), and the FHIR service. It supports both Microsoft Entra ID or an external identity provider (for example, Okta). See the sample repository for detailed instructions on how to configure and run the sample.

Microsoft Entra ID integration

Microsoft Entra ID is a full-featured OAuth 2.0 and OpenID Connect identity provider. To integrate Microsoft Entra ID as the identity provider, you need extra components to complete the end-to-end SMART on FHIR experience. This requirement exists because SMART on FHIR introduces behaviors that enterprise identity providers like Entra ID don't natively support. To bridge this gap, Microsoft provides reference solutions (samples). The sample provides an orchestration layer between SMART clients and Entra ID.

The sample supports the following scenarios for Microsoft Entra ID:

1. A scope value such as patient/Patient.rs isn't a registered Entra ID permission, so Entra ID rejects the authorize request.
2. It doesn't offer a per-request scope picker for the SMART resource verbs. Entra's consent screen reflects pre-registered application permissions, not the dynamic patient/<Resource>.<verbs> the SMART app sends on each launch.
3. It doesn't advertise a SMART discovery document — smart-configuration is FHIR-server territory, not IdP territory.

SMART on FHIR v1/v2 support

AHDS FHIR service supports SMART v1.0.0 and SMART v2.0.0. You can't mix and match SMART v1.0.0 and SMART v2.0.0 scopes in the same client app registration. You must choose one or the other.

Migrate from SMART on FHIR Proxy to SMART on FHIR

Next steps

Now that you understand how to enable SMART on FHIR functionality, see the search samples page for details about how to search by using search parameters, modifiers, and other FHIR search methods.