How To Implement SMART-on-FHIR with AWS HealthLake Using Terraform

Last updated: November 2025

Healthcare applications need authentication to protect sensitive patient data. This is a clear fact, but putting authentication into practice can be challenging.

As FHIR expert Darren Devitt wrote in his post about 10 hard truths you won’t learn in the FHIR documentation:

You will almost certainly have to build a proxy in front of your FHIR server.

It’s a common use case that your proxy or backend must authorize with a lot of FHIR servers for data exchange and interoperability purposes. Having a common protocol simplifies it significantly.

This is where SMART-on-FHIR comes in — a standardized approach for healthcare applications to authenticate and access patient data securely. By implementing this with AWS HealthLake, we can create applications that comply with healthcare standards while leveraging AWS services working alongside HealthLake.

SMART-on-FHIR represents a streamlined OAuth 2.0 implementation that sits on top of the FHIR server.

When choosing a FHIR server provider, it’s important to remember that implementations vary significantly between major cloud providers and open-source alternatives. Before making your selection, carefully evaluate whether specific features you need, such as FHIR subscriptions or SMART-on-FHIR, are supported by your chosen provider.

HealthLake offers a comprehensive suite of services, including machine learning integration, data export capabilities to S3, and default encryption with both AWS-managed and customer-provided keys, as well as REST API functionality and numerous other features. For a more detailed understanding, I strongly recommend reviewing the documentation, which, although lengthy, provides extensive guides and implementation details.

Getting this right at the infrastructure level is exactly the kind of work we cover in our EHR and FHIR integration service, where we build authorization layers, connect to systems like Epic and Cerner, and handle the compliance requirements that come with exchanging patient data.

{{lead-magnet}}

Scheme

This diagram illustrates the workflow of a SMART-on-FHIR application interfacing with Amazon HealthLake.

The sequence follows these steps:

• The application initiates communication through a discovery endpoint (1)
• It receives metadata in response (2)
• The application requests and obtains an authentication token from the Cognito user pool (3,4)
• Using the received token, it submits a data request (5)

The token validation process includes:

• Submission of request to HealthLake (5)
• HealthLake initiates validation through Lambda (6)
• Optional public key exchange with Cognito (7,8)
• Lambda returns the validation outcome (9)
• Upon successful validation, HealthLake transmits FHIR data to the application (10)

The AWS infrastructure is compatible with both on-premises and AWS-hosted Electronic Health Record (EHR) systems.

If you prefer to skip the complete tutorial and use the modularized solution instead, you can find it in the HealthStack repository.

Prerequisites

• Terraform installed on your system (version 1.9 was used for this tutorial)
• AWS admin access credentials (access key and secret key) configured for authentication

Chapter 1: HealthLake

AWS HealthLake is a HIPAA-eligible service that provides a fully managed FHIR server. It stores medical data in NDJSON format and offers a REST API for interacting with health data. While its API handles basic queries, complex analysis requires exporting data to S3 and using tools like Athena or Amazon Comprehend Medical.

First step is to create an AWS HealthLake datastore (awscc_healthlake_fhir_datastore) using Terraform with basic configuration:

‍Notice it uses the awscc provider, not the regular aws one.

It provides us with basic HealthLake configuration with AWS managed key encryption, supported R4 (the only one supported standard) and preloaded test data by SYNTHEA which provides quality healthcare data. You can also use AWS Customer managed keys and initialize without preloaded data.

To provide Customer-Managed keys you need to create a KMS resource with appropriate roles to manage it. Neither this nor the S3 configuration for exporting will be covered in the scope of this article but to do so you can use this HeathLake module.

Chapter 2: Cognito

AWS Cognito is a managed authentication service that handles user management and authentication for web and mobile applications. In this tutorial, it’s used to implement SMART-on-FHIR authentication, which is an OAuth2-based protocol specifically designed for healthcare applications. Cognito provides essential features like user pools for managing user directories, resource servers for defining access scopes, and client applications that can authenticate users — all crucial components for securing access to healthcare data through FHIR APIs.

An Amazon Cognito User Pool (aws_cognito_user_pool) is a secure user directory that manages authentication and authorization for web and mobile applications. It handles essential user management tasks like registration, sign-in, and access control.

This Cognito User Pool configuration creates a user directory with email-based authentication, password requirements, email verification, and other general capabilities that can be adjusted.

Next we create Cognito User Pool Domain (aws_cognito_user_pool_domain) which provides a dedicated URL endpoint where users can sign in and manage their authentication.

At this point, we have defined the user pool and its domain, which we will use to access authentication services.

Going further, we need to define resource servers. A Resource Server in OAuth 2.0 and Cognito is a server that hosts protected resources and handles requests using access tokens. It determines the available “scopes” which define specific permissions for accessing these resources.

The next step is to define the client for your user pool.

A Cognito User Pool client (aws_cognito_user_pool_client) represents an application that needs to authenticate users through your Cognito User Pool. It acts as a registered application that can access the authentication services.

Note: The commented section allows you to define authentication code-based flow, but we’ll use client credentials in this tutorial.

For testing purposes, you can add a test user (aws_cognito_user) to your user domain.

Chapter 3: Lambda

AWS Lambda is one of the most popular services, and I assume most of you have encountered or heard about it. For those unfamiliar with it, AWS Lambda is a service that essentially runs code — specifically, a function. We need to validate credentials with Cognito and encode them in a JWT token that we will return to our service. AWS Lambda is perfectly suited for this task.

Now we’ll create a Lambda function to handle token generation and authentication using Python.
Here’s the project structure:

Required dependencies in requirements.txt:

Here’s a sample Python script we can use for authentication:

To deploy the lambda function, we need to install additional packages and prepare a package directory for zipping and uploading. Use these commands:

Next, we’ll configure Lambda by defining the zip process, function settings, and required roles and privileges.

Chapter 4: Update HealthLake resource

Update you first resource with provided identity config:

Chapter 5: Deployment

To make the Terraform configuration more useful, add these outputs:

Follow these steps to ensure your Terraform configuration is properly formatted and validated:

It’s time to deploy our infrastructure by running:

As I mentioned it will take a while, in my case it was 28 minutes. So you can take a break and have a cup of coffee.

This is a log from my deployment:

You should see something like this in outputs:

Note datastore_endpoint and cognito_oauth_endpoints.token. You will also need cognito_client_credentials, but as it is sensitive variable you have to:

Chapter 6: Testing

Postman

If you want to test SMART, you can use Postman to do soo. (have a look at screens below)

Here is what you need to do:

• Open Postman and check “Authorization” tab (under URL placeholder)
• Choose OAuth 2.0 in Auth Type
• Scroll down and under “Configure New Token” fill credentials:
  - Token Name — ex. “test-token”
  - Grant Type — Client Credentials
  - Access Token URL — ex. https://smart-fhir-test.auth.us-east-1.amazoncognito.com/oauth2/token — you get it from cognito_oauth_endpoints.token Terraform output
  - Client ID — 401…st9 — sensitive value you’ve printed out
  — Client Secret — 1j3…2nf — sensitive value you’ve printed out
  — Scope — ex. system/*.*
  — State — ex. 1231234
• Click “Get New Access Token button”
• You should get JWT token, click button to use it
• Make a a test request for instance GET https://healthlake.us-east-1.amazonaws.com/datastore/<YOUR_DATASTORE_ID>/r4/Patient

VSCode HTTP

I like to use VSCode REST Client extension and it is perfectly valid for testing authentication:

Summary

This guide walked through implementing SMART-on-FHIR authentication with AWS HealthLake using Terraform. We covered:

1. Setting up AWS HealthLake with basic configuration and encryption
2. Implementing authentication using AWS Cognito:
   -Creating user pools for managing users
   -Configuring resource servers for SMART-on-FHIR scopes
   -Setting up client applications
3. Building a Lambda function for token validation and authentication, including:
   -JWT token validation
   -SMART-on-FHIR specific claim validation
   -Error handling and security controls
4. Deploying the infrastructure with proper IAM roles and permissions

Full code is available in this Github Gist 🚀

For a ready-to-use implementation, check out the Momentum’s HealthStack repository.
‍
Remember that AWS HealthLake deployment takes 20–30 minutes, so plan accordingly.

I hope this article helped you! By following this guide, you've equipped your healthcare application with a robust, standardized authentication mechanism, enhancing both security and interoperability.

So you're looking to elevate your healthcare solutions?

At Momentum, we specialize in integrating cutting-edge technologies to streamline healthcare operations and enhance patient outcomes. Whether you're implementing SMART on FHIR or exploring other innovative solutions, our team is here to guide you every step of the way.