Automated deployment - FHIR Works on AWS

Automated deployment

Before you launch the solution, review the architecture, configuration, and other considerations discussed in this guide. Follow the step-by-step instructions in this section to configure and deploy the solution into your account.

Time to deploy: Approximately 30 minutes

Prerequisites

To generate a Cognito ID token with FHIR Works requires the AWS Command Line Interface (AWS CLI) to be available in your environment. This ID token is required for all reads or writes on FHIR resources. For installation instructions, refer to What Is the AWS Command Line Interface in the AWS CLI User Guide.

Deployment overview

Use the following steps to deploy this solution on AWS. For detailed instructions, follow the links for each step.

Step 1. Launch the stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Enter values for required parameters:

    • Stage

    • CognitoOAuthDefaultRedirectURL

Step 2. Post-configuration tasks

  • Obtain the Amazon API Gateway API key.

  • Create an Amazon Cognito user and obtain an authentication domain.

  • Generate a Cognito ID token where a password change is required.

  • Generate another Cognito ID token that does not require a password change.

Step 1. Launch the stack

This automated AWS CloudFormation template deploys FHIR Works on AWS in the AWS Cloud.

Note

You are responsible for the cost of the AWS services used while running this solution. For more details, visit to the Cost section in this guide, and refer to the pricing webpage for each AWS service used in this solution.

  1. Sign in to the AWS Management Console and select the button to launch the fhir-works-on-aws.template AWS CloudFormation template.

    
                  FHIR Works on AWS launch button

    Alternatively, you can download the template as a starting point for your own implementation.

  2. The template launches in the US East (N. Virginia) Region by default. To launch the solution in a different AWS Region, use the Region selector in the console navigation bar.

    Note

    This solution uses the AWS Cognito service, which is not currently available in all AWS Regions. You must launch this solution in an AWS Region where AWS Cognito is available. For the most current availability by Region, refer to the AWS Regional Services List.

  3. On the Create stack page, verify that the correct template URL is in the Amazon S3 URL text box and choose Next.

  4. On the Specify stack details page, assign a name to your solution stack. For information about naming character limitations, refer to IAM and STS Limits in the AWS Identity and Access Management User Guide.

  5. Under Parameters, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.

    Parameter Default Description
    Stage dev

    A short name for identifying the stage. dev is the only option.

    Note: dev results in a lower-capacity, hence lower cost Amazon OpenSearch Service cluster than if you were to choose a non-dev stage. For details, refer to the GitHub code explanation.

    CognitoOAuthDefaultRedirectURL http://localhost The authorization endpoint. For details, refer to Configuring a User Pool App Client. If using Postman, consider using https://oauth.pstmn.io/v1/browser-callback. If not applicable, use the default.
    EnableMultiTenancy false To turn on multi-tenancy, refer to the Multi-tenancy section.
    ExportGlueNumberWorkers 5 Number of Glue workers to be used during bulk data export.
    ExportGlueWorkerType G.2X Glue worker type to be used for bulk data export. Valid values are G.2X and G.1X.
    logLevel error

    Log level for CloudWatch logs. Valid values are: debug, info, warn, and error.

  6. Choose Next.

  7. On the Configure stack options page, choose Next.

  8. On the Review page, review and confirm the settings. Check the box acknowledging that the template will create AWS Identity and Access Management (IAM) resources.

  9. Choose Create stack to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation Console in the Status column. You should receive a CREATE_COMPLETE status in approximately 30 minutes.

  10. From the CloudFormation Stacks page, choose the Outputs tab and record the value for ServiceEndpoint. This is the URL for FHIR Works on AWS.

Step 2. Post-configuration tasks

Obtain the API Gateway API key

FHIR Works on AWS requires an API key to authorize access.

  1. Sign in to the Amazon API Gateway console.

  2. Under APIs, select the <stage>-fhir-service API created by this solution.

  3. In the left navigation pane, choose API Keys.

  4. Select the API key for the API.

  5. In the main panel, choose Show and record the API key for making FHIR API calls.

Create an Amazon Cognito user and obtain authentication domain

FHIR Works on AWS implements role-based access control (RBAC) to health data using Amazon Cognito user pools and ID tokens. Create a test user in Amazon Cognito to provision an ID token.

When multi-tenancy is enabled:

  1. Create a new user by running the following command:

    aws cognito-idp admin-create-user --user-pool-id <user-pool-id> --username <user-name> --user-attributes Name="custom:tenantId",Value="<tenant-id>" Name="email",Value="<user-email>" --temporary-password <temp-password> --message-action SUPPRESS
  2. Sign in to the Amazon Cognito console.

  3. Choose the Groups tab, then practitioner from the list.

  4. Choose Add users. Choose the + to add the new user to the practitioner group. This ensures that ID tokens generated for this user can access FHIR resources.

  5. Choose App client settings in the menu and record the App client ID necessary for future Cognito API calls.

  6. Choose App Integration in the menu and record the Domain if you plan to use Postman to make calls to the FHIR API.

When multi-tenancy is disabled:

  1. Sign in to the Amazon Cognito console.

  2. Choose Manage User Pools.

  3. Choose the user pool created by this solution. It has the same name as the CloudFormation stack that was used to deploy the solution.

  4. Choose Users and groups, then Create user.

  5. Create a user with a temporary password.

  6. Choose the Groups tab, then practitioner from the list.

  7. Choose Add users. Choose the + to add the new user to the practitioner group. This ensures that ID tokens generated for this user can access FHIR resources.

  8. Choose App client settings in the menu and record the App client ID necessary for future Cognito API calls.

  9. Choose App Integration in the menu and record the Domain if you plan to use Postman to make calls to the FHIR API.

Generate a Cognito ID token (password change required)

When a user authenticates to Amazon Cognito, a temporary ID token is provided. The ID token is required for API calls to FHIR Works on AWS.

  1. Launch a command line session in an environment with the AWS CLI configured.

    Note

    Ensure that the AWS CLI environment is using the same account and Region where FHIR Works on AWS is deployed.

  2. Run the following initiate-auth command for the user, providing the username, temporary password, and App client ID:

    aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --client-id <App-client-ID> --auth-parameters USERNAME=<Username>,PASSWORD=<Temporary password> --region <Your-Region>

    Replace <App-client-ID> with the ID from the Amazon Cognito user pool, under App client settings.

  3. The new user requires a password change. Amazon Cognito responds with a NEW_PASSWORD_REQUIRED challenge. Record the session ID.

  4. Run the following respond-to-auth-challenge command to select a permanent password:

    aws cognito-idp respond-to-auth-challenge --client-id <App-client-ID> --challenge-name NEW_PASSWORD_REQUIRED --challenge-responses USERNAME=<Username>,NEW_PASSWORD=<Permanent-Password> --session <Session-ID> --region <Your-Region>

    Replace <Session-ID> with the session ID recorded from the CLI response in the previous step.

  5. Amazon Cognito responds with an ID token that can be used to make FHIR API calls to FHIR Works on AWS. For details, refer to Accessing the FHIR API.

Note

ID tokens expire after 60 minutes by default.

Generate a Cognito ID token (no password change required)

When the ID token expires, it can no longer be used in requests to FHIR Works on AWS.

To generate a new token, run the following initiate-auth command with the permanent password:

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --client-id <App-client-ID> --auth-parameters USERNAME=<Username>,PASSWORD=<Permanent-password>

The response includes a new ID token.

FHIR Works on AWS is now ready to receive API calls.