AWS for Industries

Enhanced interoperability with SMART on FHIR support in Amazon HealthLake


From its launch in July 2021, Amazon HealthLake has provided secure access through AWS Identity and Access Management (IAM). AWS recently launched new FHIR API capabilities on Amazon HealthLake including support for SMART on FHIR 1.0.0. With the support for SMART on FHIR, HealthLake now offers authorization based on the SMART framework using FHIR scopes and launch context. In this article we will discuss how to implement SMART on FHIR on HealthLake using Okta as an Identity Provider (IdP).

Developers innovating to give patients and clinicians secure access to health data face multiple challenges due to varying formats and standards. The ONC Cures Act Final Rule encourages healthcare industry to adopt standards that enable developers create novel applications to support provider workflows and enable patients access to their own health records. One of the standards, SMART on FHIR proposes an architectural solution that enables developers to write applications once and allows health organizations to test applications from various developers until they find a suitable fit. The term “SMART” refers to Substitutable Medical Applications and Reusable Technologies, while “on FHIR” indicates the utilization of Fast Healthcare Interoperability Resources (FHIR) standard.

Overview of the SMART framework

The framework for deploying a SMART application plays a crucial role in connecting external applications to electronic health records (EHR) systems, enabling the launch of applications both within and outside of the EHR system. This framework supports a range of applications designed for use by doctors, patients, and other individuals or systems using FHIR APIs. Users can grant permissions to applications to access their health data, ensuring a secure and reliable protocol across various architectural setups, whether the applications runs on end-user devices or servers. SMART on FHIR 1.0.0 encompasses the following four use cases:

  1. Standalone patient applications that can be launched independently.
  2. Patient applications that can be launched from an EHR portal.
  3. Standalone provider applications that can be launched independently.
  4. Provider applications that can be launched from an EHR portal.

SMART authorization and FHIR access

The following diagram shows the steps that make up the standalone launch and authorization of a SMART on FHIR application utilizing HealthLake as FHIR resource server. We will dive deep in these steps and understand the workflow.

SMART App Launch Sequence Diagram

Step 1:  The application requests authorization 

At the time of launch, in order to obtain authorization to access FHIR resources, the SMART on FHIR client application issues an HTTP GET request without any identity information to the discovery URL [base]/.well-known/smart-configuration for the FHIR server’s SMART configuration metadata, including OAuth authorization_endpoint and token_endpoint URLs.  The application then creates an authorization request by adding the following parameters to the query component of the endpoint URL used by the FHIR server to “authorize”

  • response_type: This is a fixed value – code
  • client_id: the client’s identifier
  • redirect_uri: must match one of the redirection URIs that the registered client has.
  • launch: when using the EHR launch flow, it must match the launch value received from the EHR. This is an optional parameter which is not required for a standalone launch workflow.
  • scope: must describe the access that the app needs, including scopes of clinical, context and identity data

As described in the SMART application launch framework IG, the scope for data is formed as follows.

SMART on FHIR scopes

Examples of the most commonly used scopes are

  • patient/*.read – permission to read any resource related to the current patient
  • user/*.* – permission to read/write all the resources the current user can access

The other commonly used non clinical scopes are

  • launch– permission to get the launch context when the app is launched from an EHR
  • launch/patient – when the app is launched outside the EHR and needs the context of the patient, the authorization server provides a list of patients to select from
  • offline_access – request a refresh token to replace the expired access token even when the user is offline after access token expires
  • online_access – request a refresh token to replace the expired access token that can be used while the user is online.
  • state : an opaque value used to maintain the state between the request and the callback
  • aud : This refers to the ‘audience’ which is the URL of the FHIR resource server from which the app fetches the data.

Step 2: Evaluate the authorization request

The authorization process depends on the authorization server, which can ask the user for permission. The server then decides whether to allow or deny access based on factors like the client_id, configured policy, and sometimes even the user’s input. The application receives this decision when the authorization server sends back an authorization code or an error response if access is denied.

Step 3: Exchange the authorization code for the access token

Once the application acquires an authorization code, it proceeds to exchange this code for an access token. This exchange occurs by making an HTTP POST request to the EHR authorization server’s token URL endpoint, using the content-type application/x-www-form-urlencoded.

Step 4: Access to clinical data through the FHIR API

Once the application possesses a valid access token, it gains the ability to retrieve the data by making a FHIR API call to the endpoint of the FHIR server. The API request includes an authorization header that carries the access_token as a “Bearer” token in the following format: Authorization: Bearer {{access_token}}. Here, the placeholder {{access_token}} is replaced with the actual value of the token obtained in the previous step.

Step 5: Refresh Tokens

The application uses a refresh token to obtain a new token. Refresh tokens are issued to allows sessions to last longer than the validity period of an access token.

An example implementation of SMART on FHIR on Amazon HealthLake

Now that we have discussed specifications and standards defining SMART on FHIR, we will demonstrate how to implement it on HealthLake using Okta as an Identity Provider (IdP). Please note that customers can use any other OAuth 2.0 IdP with HealthLake.

Setting up SMART access on Amazon HealthLake

Step 1: Set up the third party Authorization Server and obtain the ‘well-known’ configuration

While authorization servers may operate with slight variations, it is crucial to have the base URI and sufficient metadata obtained from the “well-known” configuration from authorization servers. The following screenshot of Okta shows the default authorization server configuration with the metadata URI in Okta IDP.

Okta IDP Default Authorization Server Settings

The metadata information from identity providers include an authorization endpoint, token endpoint, supported grant types and scopes among other details. This information is used when creating the HealthLake data store with SMART capabilities, as emphasized in the following section.

Figure 4 Establish the communication between HealthLake and Auth Server

Step 2: Establish the communication between HealthLake and Auth Server

When you create an Amazon HealthLake data store with SMART on FHIR support, you need to specify the ARN of an AWS Lambda function that will return certain claims and an IAM service role with permissions to perform the FHIR API request. See Amazon HealthLake Developer Guide for more information on creation of the Lambda function. This Lambda function will return the necessary elements to the Amazon HealthLake service in response to a FHIR API request.

The following diagram shows the communication between SMART on FHIR application, IDP, Amazon HealthLake and the Lambda function.

SMART on FHIR authentication flow with HealthLake_rev

Step 3: Store the IdP configuration when creating the HealthLake datastore

The HealthLake data store owner decides

  1. The IAM role associated with the FHIR interactions
  2. The decryption and token validation method (local validation or token introspection with an IDP ) and
  3. Configuration of the identity provider.    After creating the introspection Lambda function, users can invoke the create data store API, which is now enhanced with the ability to store IdentityProviderConfiguration.  This parameter configures the authorization strategy, discovery API metadata, and enables the fine grained authorization. Please note that this configuration is only available while creating a new datastore, and cannot be enabled on an existing data store. Additionally, this configuration is only accessible through the command line interface (CLI) and software development kit (SDK), and not through the console.

This new structure of CreateFHIRDatastoreRequest has IdentityProviderConfiguration as an optional parameter when creating new data stores.

This configuration accepts following fields:

  • AuthorizationStrategy: Specify SMART_on_FHIR_V1 for SMART authorization and AWSAuth for non SMART authorization. If value is SMART_on_FHIR_V1 all the following fields are required.
  • FineGrainedAuthorizationEnabled: If customer wishes to use HealthLake provided fine grained authorization then select true, else false
  • Metadata – stores the authorization server metadata that is returned on receiving a discovery API request call. The SmartConfigurationMetadata is a json object similar to what is shown in the FHIR specification, which includes the authorization_endpoint and token_endpoint.
  • IDPLambdaARN: this is the ARN for the custom Lambda which performs the token introspection.

After completing these configurations, HealthLake can decode the bearer tokens sent by SMART applications as well as perform authentication and authorization on those requests.

Key Features and benefits of SMART on FHIR support in Amazon HealthLake

  • Applicability and Flexibility: It empowers healthcare providers to seamlessly integrate third-party applications into existing systems. This allows for customization and enhancement of clinical workflows, leading to improved efficiency and usability.
  • Patient-Centered Care: SMART on FHIR support in HealthLake enables patients to securely access and interact with their health data through patient-facing applications. This fosters active patient engagement, empowerment, and better self-management of health conditions.
  • Enhanced Interoperability: By leveraging FHIR standard data format, SMART on FHIR enables the exchange of structured health data among disparate systems, ensuring compatibility and consistency. This promotes efficient care coordination, research, and population health management.
  • Developer-friendly Environment: SMART open-source platform fosters innovation and encourages the creation of new healthcare solutions.


SMART on FHIR represents a transformative approach to healthcare interoperability, empowering healthcare providers, developers, and patients alike. Its ability to seamlessly integrate applications, enhance care coordination, and promote patient engagement positions Smart on FHIR as a key enabler of the digital transformation in healthcare. By supporting this standard, Amazon HealthLake enables interoperability, innovation, and ultimately, better patient outcomes. To get started with Amazon HealthLake and learn more about how you can securely store, transform, transact and analyze health data in minutes, please check following links to previous blogs.

Links to previous blogs on Amazon HealthLake

Yogesh Dhimate

Yogesh Dhimate

Yogesh Dhimate is a Senior Partner Solutions Architect at AWS. Yogesh supports global healthcare ISVs to build interoperability solutions on AWS. Prior to joining AWS, Yogesh worked as a technical leader and product manager for healthcare industry solutions at MuleSoft (now Salesforce).

Bakha Nurzhanov

Bakha Nurzhanov

Bakha Nurzhanov is an Interoperability Solutions Architect at AWS, and is a technical leader for healthcare interoperability and innovation. Bakha supports global healthcare customers, builds healthcare interoperability depth in our global technical team, and leads healthcare innovation development. Prior to joining AWS, Bakha spent over 20 years working as an integration architect and developer at various healthcare provider organizations.

Mirza Baig

Mirza Baig

Mirza Baig is a Principal Solutions Architect in Health AI. primarily focused on driving adoption of Health AI solutions. Prior to joining Amazon, Mirza held technical & leadership roles in Software Development, Data Foundation, CyberSecurity, Network Engineering with large organizations like Envision Healthcare, Cisco, The Executive Office of The President (of US) among others.