Integrating SMART on FHIR with AWS HealthLake

A Substitutable Medical Applications and Reusable Technologies (SMART) on FHIR enabled HealthLake data store allows SMART on FHIR compliant applications to access data stored in a HealthLake data store. HealthLake data is accessed by authenticating and authorizing requests using a third-party authorization server, and by setting up additional resources in AWS.

To use the SMART on FHIR with your HealthLake data store you must provide the following in your CreateFHIRDatastore API request.

You can make a SMART on FHIR enabled data store using the AWS Command Line Interface (AWS CLI) or via one of the AWS supported SDKs. Creating a SMART on FHIR enabled HealthLake data store is not supported using the HealthLake console. To learn more, see Create a SMART on FHIR enabled data store.

To prescribe these parameters in the request, you need to set up resources in other AWS services (AWS Secrets Manager and AWS Lambda), create new IAM service roles, and set up a SMART on FHIR compliant authorization server. Use the section Setting up the required resources to implement a SMART on FHIR compliant data store to learn more about setting up the required resources and to see a high-level overview of how a SMART on FHIR Application interacts with HealthLake.

This means that instead of managing user credentials via AWS Identity and Access Management you are doing so using a SMART on FHIR compliant authorization server.

HealthLake supports SMART on FHIR 1.0. To learn more about this framework, see SMART Application Launch Framework Implementation Guide Release 1.0.

To authorize and authenticate requests for data store using SMART on FHIR, HealthLake supports using:

Setting up resources needed to implement a SMART on FHIR compliant data store

This topic describes the resources that you need to provision in your AWS account outside HealthLake, creating a SMART on FHIR enabled HealthLake data store, and how a SMART on FHIR client application would interact with an authorization server and a HealthLake data store.

The steps in this workflow define the basic steps for how SMART on FHIR requests are handled, and what resources are needed for them to succeed.

In a SMART on FHIR request process, three applications work together:

For these application to work together you need to create the following resources.

We recommend creating the SMART on FHIR enabled HealthLake data store after you have set up the authorization server, defined the neccessary scopes on it, and created a AWS Lambda function to handle token introspection.

1. Setting up an authorization server endpoint — Authorization server

To use the SMART on FHIR framework you need to set up an third-party authorization server that can validate FHIR REST requests made on a data store. To learn more about setting up an authorization server endpoint that will work with HealthLake, see Authentication requirements for SMART on FHIR.

2. Define scopes to control who can access what data in your HealthLake data store on your authorization server — Authorization server

The SMART on FHIR framework uses OAuth scopes to determine what FHIR resources an authenticated request has access to and to what extent. Defining scopes are a way to design for least-privilege. To learn more about scopes defined by the SMART on FHIR framework and supported by HealthLake see, Supported SMART on FHIR OAuth scopes by HealthLake.

3. Setup a AWS Lambda function capable of performing token introspection —your AWS account

A FHIR REST request sent by the client application on a SMART on FHIR enabled data store will contain a JSON Web Token (JWT). To learn more about setting up a Lambda function capable decoding and validating it, see Decoding a JWT.

4. Create a SMART on FHIR enabled HealthLake data store — your AWS account

To create a SMART on FHIR HealthLake data store you need to provide an IdentityProviderConfiguration. To learn more the required IdentityProviderConfiguration parameters in a CreateFHIRDatastore request, see Creating a SMART on FHIR enabled HealthLake data store.

How a client application launches and requests data from a SMART on FHIR enable HealthLake data store

This section explain how a client application launches with in the SMART on FHIR context, and is able to make a sucessful FHIR REST request on an HealthLake data store.

1. Client application makes a GET request to Well-Known Uniform Resource Identifier

A SMART enabled client application needs to make a GET request to find the authorization endpoints of your HealthLake data store. This is done via a Well-Known Uniform Resource Identifier (URI) request. To learn more about this, see Fetching a SMART on FHIR enabled HealthLake data store's Discovery Document.

2. Requesting access and Scopes

The client application uses the authorization endpoint of the authorization server, so that the user can login. This process authenticates the user. Scopes are used to define what FHIR resources in your HealthLake data store a client application can access. To learn more about defining scopes, see Supported SMART on FHIR OAuth scopes by HealthLake.

3. Access tokens

Now that the user has been authenticated, a client application receives a JWT access token from the authorization server. This token is provided when the client application sends a FHIR REST request to HealthLake. To learn more about how the JWT is decoded using a Lambda function, see Performing token validation.

4. Making a FHIR REST Request on SMART on FHIR enabled HealthLake data store

Now, the client application can send a FHIR REST request to a HealthLake data store endpoint using the access token provided by the authorization server. To see an example FHIR REST request, see Making a FHIR REST API request on a SMART enabled HealthLake data store.

5. Validating the JWT access token

To validate the access token sent in the FHIR REST request, use a Lambda function. To see how to create a Lambda function that can perform token introspection, see Creating an AWS Lambda function.