aws-s3-aidbox-integration

AWS S3 Aidbox integration example

This guide demonstrates how to integrate AWS S3 with Aidbox using a front-end application exclusively.

The application enables saving and retrieving a patient's photo in an AWS S3 bucket via Aidbox, which acts as a middleware between the front-end and AWS S3. Aidbox manages the Access Key ID and Secret Access Key for an IAM user or role through an AwsAccount resource.

Saving a File to the Bucket: Workflow

1. Send a POST request from the front-end to Aidbox with the desired filename:

POST /aws/storage/<your-account-id-in-aidbox>/<your-bucket-name>

filename: patient.png

2. Receive a pre-signed URL from Aidbox:

{
  "url": "https://<your-bucket-name>.s3.amazonaws.com/patient.png?..."
}

3. Upload the file directly to AWS S3 by sending a POST request to the pre-signed URL. The file content (e.g., the patient's photo) is sent in the request body and saved in the bucket.

Retrieving a File from the Bucket: Workflow

1. Send a GET request from the front-end to Aidbox with the filename:

GET /aws/storage/<your-account-id-in-aidbox>/<your-bucket-name>/<filename>

2. Receive a presigned URL from Aidbox:

{
  "url": "https://<your-bucket-name>.s3.amazonaws.com/<filename>?..."
}

3. Use GET request to the URL to retrieve the file. For images, an HTML tag can be used to render the image directly:

<img
  src="https://<your-bucket-name>.s3.amazonaws.com/<filename>?..."
/>

FHIR & binary files

In this example, the Attachment FHIR datatype is used to store the file's URL. Specifically, the Patient.photo field contains an attachment representing the saved photo.

Example: Patient Resource

{
  "resourceType": "Patient",
  "id": "e5ca087b-ec71-40a7-8c9b-e6093e8f1fdc",
  "photo": [
    {
      "url": "https://thebucket.s3.amazonaws.com/john_smith_20000101.png",
      "title": "john_smith_20000101.png",
      "contentType": "image/png"
    }
  ],
  "name": [
    {
      "given": [
        "john"
      ],
      "family": "smith"
    }
  ],
  "birthDate": "2000-01-01"
}

Additionally, a DocumentReference resource can be created to store metadata about the image. See DocumentReference's scope and usagee.

Example: DocumentReference Resource

{
  "resourceType": "DocumentReference",
  "id": "f2473702-99eb-4efd-be07-8fa8ff21828c",
  "status": "current",
  "content": [
    {
      "attachment": {
        "url": "https://thebucket.s3.amazonaws.com/john_smith_20000101.png",
        "title": "john_smith_20000101.png",
        "contentType": "image/png"
      }
    }
  ]
}

Setting Up Aidbox

0. Start Aidbox and log in using the Aidbox Portal (See Getting Started Guide):

docker compose up

1. Create an AwsAccount resource to store AWS credentials and region settings:

PUT /AwsAccount

id: my-account
access-key-id: <your-key-id> # e.g. AKIAIOSFODNN7EXAMPLE
secret-access-key: <your-secret-access-key> # e.g. wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region: us-east-1

2. Set up a Basic Client to allow front-end requests:

PUT /Client/basic?_pretty=true
content-type: application/json
accept: application/json

{
 "secret": "secret",
 "grant_types": [
  "basic"
 ]
}

3. Define an Access Policy to permit basic authentication:

PUT /AccessPolicy/basic-policy?_pretty=true
content-type: application/json
accept: application/json

{
 "engine": "allow",
 "link": [
  {
   "id": "basic",
   "resourceType": "Client"
  }
 ]
}

Now we can use Basic Authorization header in the front-end:

"Authorization": "Basic YmFzaWM6c2VjcmV0"

4. Configure CORS on AWS side: Use this page to allow front-end to interact with the bucket. Here's how your configuration JSON file should look like:

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST",
            "GET",
            "DELETE"
        ],
        "AllowedOrigins": [
            "http://localhost:3000"
        ],
        "ExposeHeaders": []
    }
]

Running the application

1. Install dependencies:

npm install

2. Start the development server:

npm run dev

3. Go to http://localhost:3000.

To save Patient and DocumentReference resources and the photo in the bucket:

• Fill the patient form,
• Attach the patient photo,
• Press submit button. To get Patient photo by the id, type the id and press Get Photo button.