Amazon Web Services

Connecting your Study Tracker instance with S3 and EventBridge

Aside from being the recommended cloud hosting provider for deploying Study Tracker, several of AWS's services are also supported integrations. Connecting Study Tracker to AWS can happen either through the Admin Dashboard (v0.9 and above) or using the application.properties file.

Configuring Study Tracker Access in AWS

Study Tracker accesses AWS through the official Java SDK libraries and can authenticate & authorize access to your environment in one of two ways: IAM user access keys or EC2 IAM roles. In either case, you will likely want to create an IAM role that has the following attached policies to ensure Study Tracker can perform the necessary tasks with the required services:

// For event publishing to EventBridge
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "events:PutEvents",
            "Resource": "arn:aws:events:us-east-1:999999999:event-bus/my-study-tracker-bus"
        }
    ]
}

// For reading and writing to S3
// Note: You can and should restrict this to certain buckets for better security
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucketVersions",
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor2",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucketMultipartUploads",
                "s3:PutBucketPublicAccessBlock",
                "s3:AbortMultipartUpload",
                "s3:DeleteObject",
                "s3:PutObjectAcl",
                "s3:GetObjectVersion",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": "arn:aws:s3:::*"
        }
    ]
}

If you are hosting Study Tracker on Amazon EC2, the preferred method for auth is to attach the above role to the EC2 instance you are running and install the AWS Command Line Interface. This will allow the application to interact with your AWS environment within the bounds set by the attached role.

Alternatively, you can attach the above role to an IAM user and generate an Access Key that will grant the user of that key all of the privileges of the associated user. This is less than ideal, because it opens-up the possibility that the Study Tracker application can be granted permissions it does not need and increases the damage that a credential leak could do.

Admin Dashboard Configuration (v0.9.0 and above)

To connect AWS to your tenant using the Admin Dashboard, take the following steps:

• Log into the the Study Tracker Admin Dashboard and go to the 'Amazon Web Services' settings.

• Click 'Register AWS Integration'

• Fill in the required information in the form:

  • Name: Provide a display name for your AWS tenant

  • Account Number: Optional. Provide the AWS account number, for identification purposes.

  • Region: Enter the region that contains the services you would like to connect to.

  • Access Key ID: If using an access key to authenticate, provide the key ID.

  • Secret Access Key: If using an access key to authenticate, provide the secret key.

  • Use IAM for Authentication: If you would prefer to authenticate using the IAM role assigned to the host machine, select this option. If this is selected, you do not need to provide your access key details.

After clicking 'Submit', Study Tracker will attempt to connect to AWS and verify the provided credentials. If the connection fails, a notification will prompt you to try again with different credentials.

Access keys are stored in an encrypted format in the Study Tracker database and cannot be retrieved through the UI. If you need to make any modifications to your AWS integration settings after the initial registration, you will be required to provide your access keys before you can save the changes.

Property File Configuration

To connect Study Tracker to AWS using the application.properties file, you can use the following properties:

### AWS ###

# Optional
# If the instance running Study Tracker has an IAM role that assigns it access to EventBridge and
# S3, then these properties can be left blank. Otherwise, provide the region, access key and secret
# key for the account you are running Study Tracker in.

aws.region=
aws.access-key-id=
aws.secret-access-key=


### Events ###

# Determines where to dispatch events.
# Options: [eventbridge, local]
# Default: local

events.mode=

# If events.mode is set to 'eventbridge', then you must provide the name of the event bus to use.

aws.eventbridge.bus-name=

In Study Tracker v0.9.0 and above, the application.properties file can be used to register an AWS integration on initial startup, after which the connection must be managed in the Admin Dashboard and further changes to the AWS properties in the properties file will be ignored.

Adding S3 Buckets

Once you have connected Study Tracker to your AWS account, you can add S3 Buckets in the same Admin Dashboard window. Click the 'Add S3 Bucket' button and a popup will appear:

S3 bucket selection dialog

Select one of the available S3 buckets (access is managed be the above configured IAM role) and provide a display name for it. After clicking click 'Submit', the bucket will be displayed in the AWS configuration page and you will be able to add a Storage Folder for this bucket, granting users access.