Amazon HealthLake

(1)

Amazon HealthLake

Amazon HealthLake Developer Guide

(2)

Amazon HealthLake: Amazon HealthLake Developer Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is Amazon HealthLake?

Amazon HealthLake is a HIPAA-eligible service that healthcare providers, health insurance companies, and pharmaceutical companies can use to store, transform, query, and analyze large-scale health data.

Health data is frequently incomplete and inconsistent. It's also often unstructured, with information contained in clinical notes, lab reports, insurance claims, medical images, recorded conversations, and time-series data (for example, heart ECG or brain EEG traces).

Healthcare providers can use HealthLake to store, transform, query, and analyze data in the AWS Cloud. Using the HealthLake integrated medical natural language processing (NLP) capabilities, you can analyze unstructured clinical text from diverse sources. HealthLake transforms unstructured data using natural language processing models, and provides powerful query and search capabilities. You can use HealthLake to organize, index, and structure patient information in a secure, compliant, and auditable manner.

Beneﬁts of Amazon HealthLake

With Amazon HealthLake, you can:

• Quickly and easily ingest health data – You can bulk import on-premises Fast Healthcare

Interoperability Resources (FHIR ) ﬁles, including clinical notes, lab reports, insurance claims, and more, to an Amazon Simple Storage Service (Amazon S3) bucket. You can then use the data in downstream applications or workﬂows.

• Store your data in the AWS Cloud in a secure, HIPAA-eligibile manner that can be audited– You can store data in FHIR format, so it can be easily queried. HealthLake creates a complete, chronological view of each patient’s medical history, and structures it in the R4 FHIR standard format.

• Transform unstructured data using specialized ML models – Integrated medical natural language processing (NLP) transforms all of the raw medical text data using specialized ML models that have been trained to understand and extract meaningful information from unstructured healthcare data.

With integrated medical NLP, you can automatically extract entities (for example, medical procedures and medications), entity relationships (for example, a medication and its dosage), and entity traits (for example, positive or negative test result or time of procedure) data from your medical text.

• Use powerful query and search capabilities – HealthLake supports FHIR CRUD (Create/Read/

Update/Delete) and FHIR Search operations.

Amazon HealthLake use cases

You can use Amazon HealthLake for the following healthcare applications:

• Population health management – HealthLake helps healthcare organizations analyze population health trends, outcomes, and costs. This helps organization to identify the most appropriate intervention for a patient population, and choose better care management options.

• Improving quality of care – HealthLake aids hospitals, health insurance companies, and life sciences organizations close gaps in care, improve quality of care, and reduce cost by compiling a complete view of a patient’s medical history.

• Optimize hospital efficiency – HealthLake offers hospitals key analytics and machine learning tools to improve efficiency and reduce hospital waste.

(7)

Accessing Amazon HealthLake

You can access Amazon HealthLake through the AWS Management Console, AWS Command Line Interface (AWS CLI), or the AWS SDKs.

1. AWS Management Console – Provides a web interface that you can use to access HealthLake.

2. AWS Command Line Interface (AWS CLI) – Provides commands for a broad set of AWS services, including HealthLake, and is supported on Windows, macOS, and Linux. For more information about installing the AWS CLI, see AWS Command Line Interface

3. AWS SDKs – AWS provides SDKs (software development kits) that consist of libraries and sample code for various programming languages and platforms (Java, Python, Ruby, .NET, iOS, Android, and so on).

The SDKs provide a convenient way to create programmatic access to HealthLake and AWS. For more information, see the AWS SDK for Python

HIPAA eligibility and data security

This is a HIPAA Eligible Service. For more information about AWS, U.S. Health Insurance Portability and Accountability Act of 1996 (HIPAA), and using AWS services to process, store, and transmit protected health information (PHI), see HIPAA Overview.

Connections to HealthLake containing PHI or personally identiﬁable information (PII) must be encrypted.

By default, all connections to HealthLake use HTTPS over TLS. HealthLake stores encrypted customer content and operates by the AWS Shared Responsibility principle.

Pricing

For information about HealthLake pricing, see the Amazon HealthLake pricing page.

(8)

Creating and monitoring Data Stores

How Amazon HealthLake works

Amazon HealthLake maintains Data Stores of health records in FHIR-compliant format. You can perform the following tasks using the Amazon HealthLake console, AWS Command Line Interface (AWS CLI), or APIs:

• Create, monitor, and delete a Data Store

• Import your data from an Amazon Simple Storage Service (Amazon S3) bucket into the Data Store

• Query data using Create, Read, Update, and Delete functions

• Use FHIR search functionality

• Transform your data using integrated medical natural language processing (NLP)

Creating and monitoring Data Stores

With Amazon HealthLake, you can create and manage Data Stores for storing R4 FHIR Resources.

Use create-fhir-datastore to create a new Data Store, describe-fhir-datastore to learn more about the properties of a Data Store, and list-fhir-datastore to see all Data Stores associated with your account and their status. When a Data Store is no longer needed, you can delete it using delete-fhir-datastore.

Create, Read, Update, Delete (CRUD) operations

Manage and query data using the CreateResource, ReadResource, UpdateResource, and DeleteResource operations for 71 diﬀerent FHIR resource types. For a list of FHIR resource types supported by , see Managing FHIR resources (p. 48). These operations are all handled through an HTTP client.

Integrated medical natural language processing (NLP)

HealthLake has integrated medical natural language processing for the DocumentReference resource type. HealthLake automatically runs the integrated medical NLP on all DocumentReference resources as they are written to the system in an Import operation, during a Create operation, or during an Update operation. The original resource stays unchanged, and the extracted medical information is automatically appended as custom ﬁelds. These ﬁelds are indexed and queryable after extraction.

FHIR search functionality

You can search health records that are stored in the Data Store either through a speciﬁc resource type with supported search parameters or for resource IDs in the server without specifying the resource type.

When a FHIR record is created, it is ﬁrst saved into a FHIR Data Store, where it can be read, updated, queried, or deleted. After the data is ingested, it is indexed using OpenSearch Service, which makes the data searchable. HealthLake operates with eventual consistency with the Data Store, meaning that there might be a brief latency before the data is searchable within the Data Store.

(9)

Import data

Amazon HealthLake enables you to bulk import your ﬁles from an Amazon S3 bucket. Use either the console or start-fhir-import-job to begin an import job. Afterwards, you can use describe-fhir-import- job to monitor the status of the job and discover its properties. After the import job is complete, the data can then be added to a Data Store, transformed, or analyzed and used in downstream applications.

Export data

Amazon HealthLake enables you to bulk export your ﬁles to an Amazon S3 bucket. Use either the console or start-fhir-export-job to begin an export job. Afterwards, you can use describe-fhir-export-job to monitor the status of the job and discover its properties. After the export job is complete, the data can then be visualized using AWS Quicksight or accessed by other AWS services.

(10)

Getting started

Getting started with Amazon HealthLake

To get started using Amazon HealthLake, set up an AWS account and create an AWS Identity and Access Management (IAM) user. To use the AWS Command Line Interface, AWS SDK for Python, or the AWS SDK for Java, download and conﬁgure them.

Account set up with Amazon HealthLake

Sign up for AWS

When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all AWS services. For access to Amazon HealthLake during the public preview, you need to request access through the AWS Management Console ﬁrst.

If you are a new AWS customer, you can get started with Amazon HealthLake for free. For more information, see AWS Free Usage Tier.

If you already have an AWS account, skip to the next section.

To create an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Record your AWS account ID because you'll need it for the next task.

Create an IAM User

Services in AWS, such as Amazon HealthLake, require that you provide credentials to access them. This allows the service to determine whether you have permissions to access the service's resources.

We strongly recommend that you access AWS using AWS Identity and Access Management (IAM), not the credentials for your AWS account. To use IAM to access AWS, create an IAM user, add the user to an IAM group with administrative permissions, and then grant administrative permissions to the IAM user. You can then access AWS using a special URL and the IAM user's credentials.

The getting started exercises in this guide assume that you have a user with administrator privileges, adminuser.

To create an administrator and sign in to the console

1. Create a user named adminuser in your AWS account. For instructions, see Creating Your First IAM User and Administrators Group in the IAM User Guide.

2. Sign in to the AWS Management Console using a special URL. For more information, see How Users Sign In to Your Account in the IAM User Guide.

3. To ensure that all necessary users and roles have access to HealthLake, attach a permission policy to grant access to the service. The following is an example granting access to HealthLake.

(11)

Next step: Setting up the AWS CLI

{ "Version": "2012-10-17", "Statement": [

{

"Action": [

"healthlake:*"

],

"Resource": "*", "Effect": "Allow"

} ] }

For more information about IAM, see the following:

• AWS Identity and Access Management (IAM)

• Getting started

• IAM User Guide

Next step: Setting up the AWS CLI

Set up the AWS Command Line Interface (AWS CLI)

You don't need the AWS CLI to perform the steps in all the getting started exercises. However, some of the other exercises in this guide do require it.

To set up the AWS CLI

1. Download and conﬁgure the AWS CLI. For instructions, see the following topics in the AWS Command Line Interface User Guide:

• Getting Set Up with the AWS Command Line Interface

• Conﬁguring the AWS Command Line Interface

2. In the AWS CLI config ﬁle, add a named proﬁle for the administrator.

[profile adminuser]

aws_access_key_id = adminuser access key ID

aws_secret_access_key = adminuser secret access key region = aws-region

You use this profile when running the AWS CLI commands. Under the security principle of least privilege, we recommend that you create a separate IAM role with privileges specific to the tasks being performed. For more information about named profiles, see Named Profiles in the AWS Command Line Interface User Guide. For a list of AWS Regions, see Regions and Endpoints in the Amazon Web Services General Reference.

3. Verify the setup by typing the following help command at the command prompt.

aws healthlake help

If the AWS CLI is conﬁgured correctly, you will see a brief description of Amazon HealthLake and a list of available commands.

(12)

Creating a FHIR Data Store using the AWS Command Line Interface

4. Amazon HealthLake is available only in the US East Northern Virginia (us-east-1) Region. You don't need to specify the "--endpoint" option when using the AWS CLI, but you can if necessary. The endpoint is https://aws68918.us-east-1.amazonaws.com/.

For example, to list all of the HealthLake FHIR Data Stores that you own, you use the following command.

$ aws healthlake list-fhir-datastores \

Creating a FHIR Data Store using the AWS Command Line Interface

The following example demonstrates using the CreateFHIRDatastore operation with the AWS CLI. To run the example, you must install the AWS CLI.

The example is formatted for Unix, Linux, and macOS. For Windows, replace the backslash (\) Unix continuation character at the end of each line with a caret (^).

aws healthlake create-fhir-datastore \ --datastore-type-version R4 \

--preload-data-config PreloadDataType="SYNTHEA" \ --datastore-name "FhirTestDatastore"

Creating a FHIR Data Store using the SDK for Python

The following example demonstrates using the CreateFHIRDatastore operation using the AWS SDK for Python.

import boto3

healthlake = boto3.client(service_name='healthlake', region_name='us-east-1', use_ssl=True)

DataStore_type_version = "R4"

DataStore_name = "TestDatastore123"

preload_type = "SYNTHEA"

preload_option = {'PreloadDataType': preload_type}

print('Calling CreateFHIRDatastore\n')

create_response = healthlake.create_fhir_datastore(

DatastoreTypeVersion=DataStore_type_version, DatastoreName=DataStore_name,

PreloadDataConfig=preload_option)

print("Create FHIR Datastore response: \n", create_response) print('End of CreateFHIRDatastore\n')

Creating a FHIR Data Store using the AWS SDK for Java

The following example uses the CreateFHIRDatastore operation with Java. To run the example, install the AWS SDK for Java. For instructions on installing the AWS SDK for Java, see Set up the AWS SDK for Java.

(13)

Amazon HealthLake FHIR APIs

import com.amazonaws.auth.AWSCredentials;

import com.amazonaws.auth.AWSCredentialsProvider;

import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;

import com.amazonaws.services.HealthLake.AWSHealthLake;

import com.amazonaws.services.HealthLake.AWSHealthLakeClient;

import com.amazonaws.services.HealthLake.model.CreateFHIRDatastoreRequest;

import com.amazonaws.services.HealthLake.model.CreateFHIRDatastoreResult;

import com.amazonaws.services.HealthLake.model.DescribeFHIRDatastoreRequest;

import com.amazonaws.services.HealthLake.model.DescribeFHIRDatastoreResult;

import com.amazonaws.services.HealthLake.model.FHIRVersion;

import com.amazonaws.services.HealthLake.model.ListFHIRDatastoresRequest;

import com.amazonaws.services.HealthLake.model.ListFHIRDatastoresResult;

import com.amazonaws.services.HealthLake.model.PreloadDataConfig;

import com.amazonaws.services.HealthLake.model.PreloadDataType;

public class App{

public static void main( String[] args ) {

// Create credentials using a provider chain. For more information, see

// https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html AWSCredentialsProvider awsCreds = DefaultAWSCredentialsProviderChain.getInstance();

AWSHealthLake awsHealthLake = AWSHealthLakeClient.builder()

.withRegion("us-east-1").withCredentials(awsCreds).defaultClient();

CreateFHIRDatastoreRequest createFHIRDatastoreRequest = new CreateFHIRDatastoreRequest()

.withData StoreName("TestDatastore123") .withData StoreTypeVersion(FHIRVersion.R4) .withPreloadDataConfig(new PreloadDataConfig() .withPreloadDataType(PreloadDataType.SYNTHEA));

} }

Getting started with an HTTP client

The Amazon HealthLake FHIR APIs used to create, read, update, and delete FHIR resources aren’t

supported by the AWS SDK for Python (Boto). You must use these Representational State Transfer (REST) APIs through a REST HTTP client.

Preloaded datatypes

HealthLake supports only SYNTHEA as a preloaded data type. Synthea is a synthetic patient generator that models the medical history of model-generated patients. It’s an open-source Git repository that allows HealthLake to generate FHIR R4-compliant resource bundles so that users can test models without using actual patient data.

The following resource types are available as preloaded Data Stores.

Supported Synthea resource types

AllergyIntolerance Location

CarePlan MedicationAdministration

CareTeam MedicationRequest

(14)

Preloaded datatypes

Claim Observation

Condition Organization

Device Patient

DiagnosticReport Practitioner

Encounter PractitionerRole

ExplanationofBeneﬁt Procedure

ImagingStudy Provenance

Immunization

(15)

Data Protection

Security in Amazon HealthLake

Cloud security at AWS is the highest priority. As an AWS customer, you beneﬁt from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.

Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud:

• Security of the cloud AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the eﬀectiveness of our security as part of the AWS Compliance Programs.

To learn about the compliance programs that apply to HealthLake, see AWS Services in Scope by Compliance Program.

• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations.

This documentation helps you understand how to apply the shared responsibility model when using HealthLake. The following topics show you how to conﬁgure HealthLake to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your HealthLake resources.

Topics

• Data Protection in Amazon HealthLake (p. 10)

• Encryption at rest for Amazon HealthLake (p. 11)

• Encryption in transit for Amazon HealthLake (p. 17)

• Identity and Access Management for Amazon HealthLake (p. 17)

• Logging Amazon HealthLake API Calls with AWS CloudTrail (p. 30)

• Compliance Validation for Amazon HealthLake (p. 32)

• Resilience in Amazon HealthLake (p. 33)

• Infrastructure Security in Amazon HealthLake (p. 33)

• Security best practices in Amazon HealthLake (p. 33)

Data Protection in Amazon HealthLake

The AWS shared responsibility model applies to data protection in Amazon HealthLake. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud.

You are responsible for maintaining control over your content that is hosted on this infrastructure. This content includes the security conﬁguration and management tasks for the AWS services that you use. For more information about data privacy, see the Data Privacy FAQ. For information about data protection in Europe, see the AWS Shared Responsibility Model and GDPR blog post on the AWS Security Blog.

For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management (IAM). That way each user is given only the permissions necessary to fulﬁll their job duties. We also recommend that you secure your data in the following ways:

(16)

Encryption at rest

• Use multi-factor authentication (MFA) with each account.

• Use SSL/TLS to communicate with AWS resources. We recommend TLS 1.2 or later.

• Set up API and user activity logging with AWS CloudTrail.

• Use AWS encryption solutions, along with all default security controls within AWS services.

• Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3.

• If you require FIPS 140-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see Federal Information Processing Standard (FIPS) 140-2.

We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form fields such as a Name field. This includes when you work with HealthLake or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form fields used for names may be used for billing or diagnostic logs.

If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server.

Encryption at rest for Amazon HealthLake

HealthLake provides encryption by default to protect sensitive customer data at rest by using a service owned AWS Key Management Service (AWS KMS) key. Customer-managed KMS keys are also supported and are required for both importing and exporting files from a Data Store. To learn more about Customer-managed KMS Key, see Amazon Key Management Service. Customers can choose an AWS owned KMS key or a Customer-managed KMS key when creating a Data Store. The encryption configuration cannot be changed after a Data Store has been created. If a Data Store is using an AWS owned KMS Key, it will be denoted as AWS_OWNED_KMS_KEY and you will not see the specific key used for encryption at rest.

AWS owned KMS key

HealthLake uses these keys by default to automatically encrypt potentially sensitive information such as personally identiﬁable or Private Health Information(PHI) data at rest. AWS owned KMS keys aren't stored in your account. They're part of a collection of KMS keys that AWS owns and manages for use in multiple AWS accounts. AWS services can use AWS owned KMS keys to protect your data. You can't view, manage, use AWS owned KMS keys, or audit their use. However, you don't need to do any work or change any programs to protect the keys that encrypt your data.

You're not charged a monthly fee or a usage fee if you use AWS owned KMS keys, and they don't count against AWS KMS quotas for your account. For more information, see AWS owned keys.

Customer managed KMS keys

HealthLake supports the use of a symmetric customer managed KMS key that you create, own, and manage to add a second layer of encryption over the existing AWS owned encryption. Because you have full control of this layer of encryption, you can perform such tasks as:

• Establishing and maintaining key policies, IAM policies, and grants

• Rotating key cryptographic material

• Enabling and disabling key policies

• Adding tags

• Creating key aliases

(17)

Create a customer managed key

• Scheduling keys for deletion

You can also use CloudTrail to track the requests that HealthLake sends to AWS KMS on your behalf.

Additional AWS KMS charges apply.For more information, see customer owned keys.

Create a customer managed key

You can create a symmetric customer managed key by using the AWS Management Console, or the AWS KMS APIs.

Follow the steps for Creating symmetric customer managed key in the AWS Key Management Service Developer Guide.

Key policies control access to your customer managed key. Every customer managed key must have exactly one key policy, which contains statements that determine who can use the key and how they can use it. When you create your customer managed key, you can specify a key policy. For more information, see Managing access to customer managed keys in the AWS Key Management Service Developer Guide.

To use your customer managed key with your HealthLake resources, kms:CreateGrant operations must be permitted in the key policy. This adds a grant to a customer managed key which controls access to a speciﬁed KMS key, which gives a user access to the kms:grant operations HealthLake requires. See Using grantsfor more information.

To use your customer managed KMS key with your HealthLake resources, the following API operations must be permitted in the key policy:

• kms:CreateGrant adds grants to a speciﬁc customer managed KMS key which allows access to grant operations.

• kms:DescribeKey provides the customer managed key details needed to validate the key. This is required for all operations.

• kms:GenerateDataKey provides access to encrypt resources at rest for all write operations.

• kms:Decrypt provides access to read or search operations for encrypted resources.

The following is a policy statement example that allows a user to create and interact with a Data Store in Amazon HealthLake which is encrypted by that key:

"Statement": [ {

"Sid": "Allow access to create data stores and do CRUD/search in Amazon HealthLake",

"Effect": "Allow", "Principal": {

"AWS": "arn:aws:iam::111122223333:HealthLakeFullAccessRole"

},

"Action": [

"kms:DescribeKey", "kms:CreateGrant", "kms:GenerateDataKey", "kms:Decrypt"

],

"Resource": "*", "Condition": { "StringEquals": {

"kms:ViaService": "healthlake.amazonaws.com", "kms:CallerAccount": "111122223333"

}

(18)

Required IAM permissions for using a customer managed KMS key }

} ]

Required IAM permissions for using a customer managed KMS key

When creating a Data Store with AWS KMS encryption enabled using a customer managed KMS key, there are required permissions for both the key policy and the IAM policy for the user or role creating the HealthLake Data Store.

You can use the kms:ViaService condition key to limit use of the KMS key to only requests that originate from HealthLake.

For more information about key policies, see Enabling IAM policies in the AWS Key Management Service Developer Guide.

The IAM user, IAM role, or AWS account creating your repositories must have the

kms:CreateGrant,kms:GenerateDataKey, and kms:DescribeKey permissions plus the necessary HealthLake permissions.

How HealthLake uses grants in AWS KMS

HealthLake requires a grant to use your customer managed KMS key. When you create a Data Store encrypted with a customer managed KMS key, HealthLake creates a grant on your behalf by sending a CreateGrant request to AWS KMS. Grants in AWS KMS are used to give HealthLake access to a KMS key in a customer account.

The grants that HealthLake creates on your behalf should not be revoked or retired. If you revoke or retire the grant that gives HealthLake permission to use the AWS KMS keys in your account, HealthLake cannot access this data, encrypt new FHIR resources pushed to the Data Store, or decrypt them when they are pulled. When you revoke or retire a grant for HealthLake, the change occurs immediately. To revoke access rights, you should delete the Data Store rather than revoking the grant. When a Data Store is deleted, HealthLake retires the grants on your behalf.

Monitoring your encryption keys for HealthLake

You can use CloudTrail to track the requests that HealthLake sends to AWS KMS on your behalf when using a customer managed KMS key. The log entries in the CloudTrail log show

healthlake.amazonaws.com in the userAgent ﬁeld to clearly distinguish requests made by HealthLake.

The following examples are CloudTrail events for CreateGrant, GenerateDataKey, Decrypt, and DescribeKey to monitor AWS KMS operations called by HealthLake to access data encrypted by your customer managed key.

The following shows how to use CreateGrant to allow HealthLake to access a customer provided KMS key, enabling HealthLake to use that KMS key to encrypt all customer data at rest.

Users are not required to create their own grants. HealthLake creates a grant on your behalf by sending a CreateGrant request to AWS KMS. Grants in AWS KMS are used to give HealthLake access to a AWS KMS key in a customer account.

{

"eventVersion": "1.08", "userIdentity": {

(19)

Required IAM permissions for using a customer managed KMS key "type": "AssumedRole",

"principalId": "EXAMPLEROLE:Sampleuser01",

"arn": "arn:aws:sts::111122223333:assumed-role/Sampleuser01, "accountId": "111122223333",

"accessKeyId": "EXAMPLEKEYID", "sessionContext": {

"sessionIssuer": { "type": "Role",

"principalId": "EXAMPLEROLE",

"arn": "arn:aws:iam::111122223333:role/Sampleuser01", "accountId": "111122223333",

"userName": "Sampleuser01"

},

"webIdFederationData": {}, "attributes": {

"creationDate": "2021-06-30T19:33:37Z", "mfaAuthenticated": "false"

} },

"invokedBy": "healthlake.amazonaws.com"

},

"eventTime": "2021-06-30T20:31:15Z", "eventSource": "kms.amazonaws.com", "eventName": "CreateGrant",

"awsRegion": "us-east-1",

"sourceIPAddress": "healthlake.amazonaws.com", "userAgent": "healthlake.amazonaws.com", "requestParameters": {

"operations": [ "CreateGrant", "Decrypt", "DescribeKey", "Encrypt",

"GenerateDataKey",

"GenerateDataKeyWithoutPlaintext", "ReEncryptFrom",

"ReEncryptTo", "RetireGrant"

],

"granteePrincipal": "healthlake.us-east-1.amazonaws.com",

"keyId": "arn:aws:kms:us-east-1:111122223333:key/EXAMPLE_KEY_ARN", "retiringPrincipal": "healthlake.us-east-1.amazonaws.com"

},

"responseElements": {

"grantId": "EXAMPLE_ID_01"

},

"requestID": "EXAMPLE_ID_02", "eventID": "EXAMPLE_ID_03", "readOnly": false,

"resources": [ {

"accountId": "111122223333", "type": "AWS::KMS::Key",

"ARN": "arn:aws:kms:us-east-1:111122223333:key/EXAMPLE_KEY_ARN"

} ],

"eventType": "AwsApiCall", "managementEvent": true,

"recipientAccountId": "111122223333", "eventCategory": "Management"

}

The following examples shows how to use GenerateDataKey to ensure the user has necessary permissions to encrypt data before storing it.

(20)

Required IAM permissions for using a customer managed KMS key

{

"type": "AssumedRole", "principalId": "EXAMPLEUSER",

"arn": "arn:aws:sts::111122223333:assumed-role/Sampleuser01", "accountId": "111122223333",

},

} },

},

"eventTime": "2021-06-30T21:17:37Z", "eventSource": "kms.amazonaws.com", "eventName": "GenerateDataKey", "awsRegion": "us-east-1",

"keySpec": "AES_256",

"keyId": "arn:aws:kms:us-east-1:111122223333:key/EXAMPLE_KEY_ARN"

},

"responseElements": null, "requestID": "EXAMPLE_ID_01", "eventID": "EXAMPLE_ID_02", "readOnly": true,

"resources": [ {

} ],

}

The following example shows how HealthLake calls the Decrypt operation to use the stored encrypted data key to access the encrypted data.

{

(21)

Required IAM permissions for using a customer managed KMS key "accessKeyId": "EXAMPLEKEYID",

"sessionContext": { "sessionIssuer": { "type": "Role",

},

} },

},

"eventTime": "2021-06-30T21:21:59Z", "eventSource": "kms.amazonaws.com", "eventName": "Decrypt",

"encryptionAlgorithm": "SYMMETRIC_DEFAULT",

},

"resources": [ {

} ],

}

The following example shows how HealthLake uses the DescribeKey operation to verify if the AWS KMS customer owned AWS KMS key is in a usable state and to help a user troubleshoot if it is not functional.

{

(22)

Encryption in transit

},

} },

},

"eventTime": "2021-07-01T18:36:36Z", "eventSource": "kms.amazonaws.com", "eventName": "DescribeKey",

},

"resources": [ {

} ],

}

Learn more

The following resources provide more information about data at rest encryption.

For more information about AWS Key Management Service basic concepts, see the AWS KMS documentation.

For more information about Security best practices in the AWS KMS documentation.

Encryption in transit for Amazon HealthLake

Amazon HealthLake uses TLS 1.2 to encrypt data in transit through the public endpoint and through backend services.

Identity and Access Management for Amazon HealthLake

AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and

(23)

Audience

authorized (have permissions) to use HealthLake resources. IAM is an AWS service that you can use with no additional charge.

Topics

• Audience (p. 18)

• Authenticating with identities (p. 18)

• Managing access using policies (p. 20)

• How Amazon HealthLake works with IAM (p. 22)

• Identity-based policy examples for Amazon HealthLake (p. 26)

• Troubleshooting Amazon HealthLake identity and access (p. 28)

Audience

How you use AWS Identity and Access Management (IAM) diﬀers, depending on the work that you do in HealthLake.

Service user – If you use the HealthLake service to do your job, then your administrator provides you with the credentials and permissions that you need. As you use more HealthLake features to do your work, you might need additional permissions. Understanding how access is managed can help you request the right permissions from your administrator. If you cannot access a feature in HealthLake, see Troubleshooting Amazon HealthLake identity and access (p. 28).

Service administrator – If you're in charge of HealthLake resources at your company, you probably have full access to HealthLake. It's your job to determine which HealthLake features and resources your employees should access. You must then submit requests to your IAM administrator to change the permissions of your service users. Review the information on this page to understand the basic concepts of IAM. To learn more about how your company can use IAM with HealthLake, see How Amazon HealthLake works with IAM (p. 22).

IAM administrator – If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to HealthLake. To view example HealthLake identity-based policies that you can use in IAM, see Identity-based policy examples for Amazon HealthLake (p. 26).

Authenticating with identities

Authentication is how you sign in to AWS using your identity credentials. For more information about signing in using the AWS Management Console, see Signing in to the AWS Management Console as an IAM user or root user in the IAM User Guide.

You must be authenticated (signed in to AWS) as the AWS account root user, an IAM user, or by assuming an IAM role. You can also use your company's single sign-on authentication or even sign in using Google or Facebook. In these cases, your administrator previously set up identity federation using IAM roles.

When you access AWS using credentials from another company, you are assuming a role indirectly.

To sign in directly to the AWS Management Console, use your password with your root user email address or your IAM user name. You can access AWS programmatically using your root user or IAM users access keys. AWS provides SDK and command line tools to cryptographically sign your request using your credentials. If you don't use AWS tools, you must sign the request yourself. Do this using Signature Version 4, a protocol for authenticating inbound API requests. For more information about authenticating requests, see Signature Version 4 signing process in the AWS General Reference.

Regardless of the authentication method that you use, you might also be required to provide additional security information. For example, AWS recommends that you use multi-factor authentication (MFA) to increase the security of your account. To learn more, see Using multi-factor authentication (MFA) in AWS in the IAM User Guide.

(24)

Authenticating with identities

AWS account root user

When you ﬁrst create an AWS account, you begin with a single sign-in identity that has complete access to all AWS services and resources in the account. This identity is called the AWS account root user and is accessed by signing in with the email address and password that you used to create the account. We strongly recommend that you do not use the root user for your everyday tasks, even the administrative ones. Instead, adhere to the best practice of using the root user only to create your ﬁrst IAM user. Then securely lock away the root user credentials and use them to perform only a few account and service management tasks.

IAM users and groups

An IAM user is an identity within your AWS account that has speciﬁc permissions for a single person or application. An IAM user can have long-term credentials such as a user name and password or a set of access keys. To learn how to generate access keys, see Managing access keys for IAM users in the IAM User Guide. When you generate access keys for an IAM user, make sure you view and securely save the key pair. You cannot recover the secret access key in the future. Instead, you must generate a new access key pair.

An IAM group is an identity that speciﬁes a collection of IAM users. You can't sign in as a group. You can use groups to specify permissions for multiple users at a time. Groups make permissions easier to manage for large sets of users. For example, you could have a group named IAMAdmins and give that group permissions to administer IAM resources.

Users are diﬀerent from roles. A user is uniquely associated with one person or application, but a role is intended to be assumable by anyone who needs it. Users have permanent long-term credentials, but roles provide temporary credentials. To learn more, see When to create an IAM user (instead of a role) in the IAM User Guide.

IAM roles

An IAM role is an identity within your AWS account that has speciﬁc permissions. It is similar to an IAM user, but is not associated with a speciﬁc person. You can temporarily assume an IAM role in the AWS Management Console by switching roles. You can assume a role by calling an AWS CLI or AWS API operation or by using a custom URL. For more information about methods for using roles, see Using IAM roles in the IAM User Guide.

IAM roles with temporary credentials are useful in the following situations:

• Temporary IAM user permissions – An IAM user can assume an IAM role to temporarily take on diﬀerent permissions for a speciﬁc task.

• Federated user access – Instead of creating an IAM user, you can use existing identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These are known as federated users. AWS assigns a role to a federated user when access is requested through an identity provider. For more information about federated users, see Federated users and roles in the IAM User Guide.

• Cross-account access – You can use an IAM role to allow someone (a trusted principal) in a diﬀerent account to access resources in your account. Roles are the primary way to grant cross-account access.

However, with some AWS services, you can attach a policy directly to a resource (instead of using a role as a proxy). To learn the diﬀerence between roles and resource-based policies for cross-account access, see How IAM roles diﬀer from resource-based policies in the IAM User Guide.

• Cross-service access – Some AWS services use features in other AWS services. For example, when you make a call in a service, it's common for that service to run applications in Amazon EC2 or store objects in Amazon S3. A service might do this using the calling principal's permissions, using a service role, or using a service-linked role.

(25)

Managing access using policies

• Principal permissions – When you use an IAM user or role to perform actions in AWS, you are considered a principal. Policies grant permissions to a principal. When you use some services, you might perform an action that then triggers another action in a diﬀerent service. In this case, you must have permissions to perform both actions. To see whether an action requires additional dependent actions in a policy, see Actions, resources, and condition keys for Amazon HealthLake in the Service Authorization Reference.

• Service role – A service role is an IAM role that a service assumes to perform actions on your behalf.

An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.

• Service-linked role – A service-linked role is a type of service role that is linked to an AWS service.

The service can assume the role to perform an action on your behalf. Service-linked roles appear in your IAM account and are owned by the service. An IAM administrator can view, but not edit the permissions for service-linked roles.

• Applications running on Amazon EC2 – You can use an IAM role to manage temporary credentials for applications that are running on an EC2 instance and making AWS CLI or AWS API requests.

This is preferable to storing access keys within the EC2 instance. To assign an AWS role to an EC2 instance and make it available to all of its applications, you create an instance proﬁle that is attached to the instance. An instance proﬁle contains the role and enables programs that are running on the EC2 instance to get temporary credentials. For more information, see Using an IAM role to grant permissions to applications running on Amazon EC2 instances in the IAM User Guide.

To learn whether to use IAM roles or IAM users, see When to create an IAM role (instead of a user) in the IAM User Guide.

Managing access using policies

You control access in AWS by creating policies and attaching them to IAM identities or AWS resources. A policy is an object in AWS that, when associated with an identity or resource, deﬁnes their permissions.

You can sign in as the root user or an IAM user, or you can assume an IAM role. When you then make a request, AWS evaluates the related identity-based or resource-based policies. Permissions in the policies determine whether the request is allowed or denied. Most policies are stored in AWS as JSON documents. For more information about the structure and contents of JSON policy documents, see Overview of JSON policies in the IAM User Guide.

Administrators can use AWS JSON policies to specify who has access to what. That is, which principal can perform actions on what resources, and under what conditions.

Every IAM entity (user or role) starts with no permissions. In other words, by default, users can do nothing, not even change their own password. To give a user permission to do something, an administrator must attach a permissions policy to a user. Or the administrator can add the user to a group that has the intended permissions. When an administrator gives permissions to a group, all users in that group are granted those permissions.

IAM policies deﬁne permissions for an action regardless of the method that you use to perform the operation. For example, suppose that you have a policy that allows the iam:GetRole action. A user with that policy can get role information from the AWS Management Console, the AWS CLI, or the AWS API.

Identity-based policies

Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see Creating IAM policies in the IAM User Guide.

Identity-based policies can be further categorized as inline policies or managed policies. Inline policies are embedded directly into a single user, group, or role. Managed policies are standalone policies that

(26)

Managing access using policies

you can attach to multiple users, groups, and roles in your AWS account. Managed policies include AWS managed policies and customer managed policies. To learn how to choose between a managed policy or an inline policy, see Choosing between managed policies and inline policies in the IAM User Guide.

Resource-based policies

Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource- based policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resource- based policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must specify a principal in a resource-based policy.

Principals can include accounts, users, roles, federated users, or AWS services.

Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy.

Access control lists (ACLs)

Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.

Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about ACLs, see Access control list (ACL) overview in the Amazon Simple Storage Service Developer Guide.

Other policy types

AWS supports additional, less-common policy types. These policy types can set the maximum permissions granted to you by the more common policy types.

• Permissions boundaries – A permissions boundary is an advanced feature in which you set the maximum permissions that an identity-based policy can grant to an IAM entity (IAM user or role).

You can set a permissions boundary for an entity. The resulting permissions are the intersection of entity's identity-based policies and its permissions boundaries. Resource-based policies that specify the user or role in the Principal ﬁeld are not limited by the permissions boundary. An explicit deny in any of these policies overrides the allow. For more information about permissions boundaries, see Permissions boundaries for IAM entities in the IAM User Guide.

• Service control policies (SCPs) – SCPs are JSON policies that specify the maximum permissions for an organization or organizational unit (OU) in AWS Organizations. AWS Organizations is a service for grouping and centrally managing multiple AWS accounts that your business owns. If you enable all features in an organization, then you can apply service control policies (SCPs) to any or all of your accounts. The SCP limits permissions for entities in member accounts, including each AWS account root user. For more information about Organizations and SCPs, see How SCPs work in the AWS Organizations User Guide.

• Session policies – Session policies are advanced policies that you pass as a parameter when you programmatically create a temporary session for a role or federated user. The resulting session's permissions are the intersection of the user or role's identity-based policies and the session policies.

Permissions can also come from a resource-based policy. An explicit deny in any of these policies overrides the allow. For more information, see Session policies in the IAM User Guide.

Multiple policy types

When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see Policy evaluation logic in the IAM User Guide.

(27)

How Amazon HealthLake works with IAM

Before you use IAM to manage access to HealthLake, learn what IAM features are available to use with HealthLake.

IAM features you can use with Amazon HealthLake

IAM feature HealthLake support

Identity-based policies (p. 22) Yes Resource-based policies (p. 23) Yes

Policy actions (p. 23) Yes

Policy resources (p. 24) Yes

Policy condition keys (p. 24) Yes

ACLs (p. 25) No

ABAC (tags in policies) (p. 25) Yes

Temporary credentials (p. 25) Yes

Principal permissions (p. 25) Yes

Service roles (p. 26) Yes

Service-linked roles (p. 26) No

To get a high-level view of how HealthLake and other AWS services work with most IAM features, see AWS services that work with IAM in the IAM User Guide.

Identity-based policies for Amazon HealthLake

Supports identity-based policies Yes

Identity-based policies are JSON permissions policy documents that you can attach to an identity, such as an IAM user, group of users, or role. These policies control what actions users and roles can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see Creating IAM policies in the IAM User Guide.

With IAM identity-based policies, you can specify allowed or denied actions and resources as well as the conditions under which actions are allowed or denied. You can't specify the principal in an identity-based policy because it applies to the user or role to which it is attached. To learn about all of the elements that you can use in a JSON policy, see IAM JSON policy elements reference in the IAM User Guide.

Identity-based policy examples for Amazon HealthLake

To view examples of HealthLake identity-based policies, see Identity-based policy examples for Amazon HealthLake (p. 26).

(28)

Resource-based policies within Amazon HealthLake

Supports resource-based policies Yes

Resource-based policies are JSON policy documents that you attach to a resource. Examples of resource- based policies are IAM role trust policies and Amazon S3 bucket policies. In services that support resource- based policies, service administrators can use them to control access to a specific resource. For the resource where the policy is attached, the policy defines what actions a specified principal can perform on that resource and under what conditions. You must specify a principal in a resource-based policy.

Principals can include accounts, users, roles, federated users, or AWS services.

To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. Adding a cross-account principal to a resource-based policy is only half of establishing the trust relationship. When the principal and the resource are in diﬀerent AWS accounts, an IAM administrator in the trusted account must also grant the principal entity (user or role) permission to access the resource. They grant permission by attaching an identity-based policy to the entity. However, if a resource-based policy grants access to a principal in the same account, no additional identity-based policy is required. For more information, see How IAM roles diﬀer from resource-based policies in the IAM User Guide.

Policy actions for Amazon HealthLake

Supports policy actions Yes

The Action element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Policy actions usually have the same name as the associated AWS API operation. There are some exceptions, such as permission-only actions that don't have a matching API operation. There are also some operations that require multiple actions in a policy. These additional actions are called dependent actions.

Include actions in a policy to grant permissions to perform the associated operation.

To see a list of HealthLake actions, see Actions deﬁned by Amazon HealthLake in the Service Authorization Reference.

Policy actions in HealthLake use the following preﬁx before the action:

healthlake

To specify multiple actions in a single statement, separate them with commas.

"Action": [

"healthlake:action1", "healthlake:action2"

]

(29)

Policy resources for Amazon HealthLake

Supports policy resources Yes

The Resource JSON policy element speciﬁes the object or objects to which the action applies.

Statements must include either a Resource or a NotResource element. As a best practice, specify a resource using its Amazon Resource Name (ARN). You can do this for actions that support a speciﬁc resource type, known as resource-level permissions.

For actions that don't support resource-level permissions, such as listing operations, use a wildcard (*) to indicate that the statement applies to all resources.

"Resource": "*"

To see a list of HealthLake resource types and their ARNs, see Resources deﬁned by Amazon HealthLake in the Service Authorization Reference. To learn with which actions you can specify the ARN of each resource, see Actions deﬁned by Amazon HealthLake.

Policy condition keys for Amazon HealthLake

Supports policy condition keys Yes

The Condition element (or Condition block) lets you specify conditions in which a statement is in eﬀect. The Condition element is optional. You can create conditional expressions that use condition operators, such as equals or less than, to match the condition in the policy with values in the request.

If you specify multiple Condition elements in a statement, or multiple keys in a single Condition element, AWS evaluates them using a logical AND operation. If you specify multiple values for a single condition key, AWS evaluates the condition using a logical OR operation. All of the conditions must be met before the statement's permissions are granted.

You can also use placeholder variables when you specify conditions. For example, you can grant an IAM user permission to access a resource only if it is tagged with their IAM user name. For more information, see IAM policy elements: variables and tags in the IAM User Guide.

AWS supports global condition keys and service-speciﬁc condition keys. To see all AWS global condition keys, see AWS global condition context keys in the IAM User Guide.

To see a list of HealthLake condition keys, see Condition keys for Amazon HealthLake in the Service Authorization Reference. To learn with which actions and resources you can use a condition key, see Actions deﬁned by Amazon HealthLake.

(30)

Access control lists (ACLs) in Amazon HealthLake

Supports ACLs No

Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format.

Attribute-based access control (ABAC) with Amazon HealthLake

Supports ABAC (tags in policies) Yes

Attribute-based access control (ABAC) is an authorization strategy that deﬁnes permissions based on attributes. In AWS, these attributes are called tags. You can attach tags to IAM entities (users or roles) and to many AWS resources. Tagging entities and resources is the ﬁrst step of ABAC. Then you design ABAC policies to allow operations when the principal's tag matches the tag on the resource that they are trying to access.

ABAC is helpful in environments that are growing rapidly and helps with situations where policy management becomes cumbersome.

To control access based on tags, you provide tag information in the condition element of a policy using the aws:ResourceTag/key-name, aws:RequestTag/key-name, or aws:TagKeys condition keys.

For more information about ABAC, see What is ABAC? in the IAM User Guide. To view a tutorial with steps for setting up ABAC, see Use attribute-based access control (ABAC) in the IAM User Guide.

Using temporary credentials with Amazon HealthLake

Supports temporary credentials Yes

Some AWS services don't work when you sign in using temporary credentials. For additional information, including which AWS services work with temporary credentials, see AWS services that work with IAM in the IAM User Guide.

You are using temporary credentials if you sign in to the AWS Management Console using any method except a user name and password. For example, when you access AWS using your company's single sign-on (SSO) link, that process automatically creates temporary credentials. You also automatically create temporary credentials when you sign in to the console as a user and then switch roles. For more information about switching roles, see Switching to a role (console) in the IAM User Guide.

You can manually create temporary credentials using the AWS CLI or AWS API. You can then use those temporary credentials to access AWS. AWS recommends that you dynamically generate temporary credentials instead of using long-term access keys. For more information, see Temporary security credentials in IAM.

Cross-service principal permissions for Amazon HealthLake

Supports principal permissions Yes

Amazon HealthLake

Amazon HealthLake

Amazon HealthLake Developer Guide

Amazon HealthLake: Amazon HealthLake Developer Guide

Table of Contents

What is Amazon HealthLake?

Beneﬁts of Amazon HealthLake

Amazon HealthLake use cases

Accessing Amazon HealthLake

HIPAA eligibility and data security

Pricing

How Amazon HealthLake works

Creating and monitoring Data Stores

Create, Read, Update, Delete (CRUD) operations

Integrated medical natural language processing (NLP)

FHIR search functionality

Import data

Export data

Getting started with Amazon HealthLake

Account set up with Amazon HealthLake

Sign up for AWS

Create an IAM User

Next step: Setting up the AWS CLI

Set up the AWS Command Line Interface (AWS CLI)

Creating a FHIR Data Store using the AWS Command Line Interface

Creating a FHIR Data Store using the SDK for Python

Creating a FHIR Data Store using the AWS SDK for Java

Getting started with an HTTP client

Preloaded datatypes

Security in Amazon HealthLake

Data Protection in Amazon HealthLake

Encryption at rest for Amazon HealthLake

AWS owned KMS key

Customer managed KMS keys

Create a customer managed key

Required IAM permissions for using a customer managed KMS key

How HealthLake uses grants in AWS KMS

Monitoring your encryption keys for HealthLake

Learn more

Encryption in transit for Amazon HealthLake

Identity and Access Management for Amazon HealthLake

Audience

Authenticating with identities

AWS account root user

IAM users and groups

IAM roles

Managing access using policies

Identity-based policies

Resource-based policies

Access control lists (ACLs)

Other policy types

Multiple policy types

How Amazon HealthLake works with IAM

Identity-based policies for Amazon HealthLake

Identity-based policy examples for Amazon HealthLake

Resource-based policies within Amazon HealthLake

Policy actions for Amazon HealthLake

Policy resources for Amazon HealthLake

Policy condition keys for Amazon HealthLake

Access control lists (ACLs) in Amazon HealthLake

Attribute-based access control (ABAC) with Amazon HealthLake

Using temporary credentials with Amazon HealthLake

Cross-service principal permissions for Amazon HealthLake