OpenEMR Simple Storage Solution (AWS S3)

Offsite patient document storage for OpenEMR using Amazon S3. Supports access keys (encrypted at rest), EC2 instance profiles, and the AWS default credential chain.

Module Manager name: AWS Simple Storage Solution v1.1.0
Package version: 1.1.0 (version.php)
Namespace: Juggernaut\SimpleStorageSolution\Module
Author: Sherwin Gaddis

Compatibility

Target	Status
OpenEMR 8.0+ (including 8.2.x)	Supported — uses SessionWrapperFactory / session-aware CSRF
OpenEMR 7.0.x	Not the primary target; may work partially but is not certified

• PHP 8.1+
• Dependency: aws/aws-sdk-php ^3.231 (install with Composer in the module directory)
• Composer conflict: openemr/openemr < 8.0.0

Features

• Hooks OpenEMR offsite document events to upload/retrieve objects in S3
• Settings UI with connection test and bucket discovery/manual entry
• Auth modes: DEFAULT provider chain, IP instance profile, KS key/secret (CryptoGen encrypted in DB)
• Menu: Modules → AWS S3
• Presigned GET helper and staff-only upload probe

Installation

1. Clone into custom modules:

   cd /path/to/openemr/interface/modules/custom_modules
   git clone https://github.com/juggernautsei/oe-simple-storage-solution.git
   cd oe-simple-storage-solution
   composer install --no-dev

2. In OpenEMR Module Manager: register, install (table.sql), enable.

3. Open Modules → AWS S3 (requires patients/docs or admin super).

4. Configure region + auth mode, test connection, select bucket.

Database

table.sql creates module_s3_credentials (encrypted key/secret columns, region, bucket, bucket_type).
Upgrade script: sql/1_0_0-to1_1_0_upgrade.sql adds bucket_type.
Unregister drops the credentials table.

Security

• AWS secrets encrypted with OpenEMR CryptoGen before DB storage; never re-displayed in the UI
• Settings, credential POST, upload test, and presign helper require ACL
• CSRF on credential save and bucket AJAX
• Upload temp files use $OE_SITE_DIR/documents/temp (not a hardcoded host path)
• Prefer instance profile or default chain on AWS over long-lived access keys
• Enable S3 SSE, block public access, least-privilege IAM

Operations notes

• After composer install, ensure the web user can read vendor/
• Offsite document events require OpenEMR core support for remote document store/retrieve
• Presigned links: public/getObjectFromBucket.php?key=relative/object-key (5 minutes)
• Manual probe: public/index.php uploads bundled text.txt

---

This module connects OpenEMR to Amazon S3 for secure, scalable cloud storage of patient files and documents.

AWS Authentication Methods

OpenEMR's S3 Storage Solution module supports two authentication methods for connecting to Amazon S3:

1. AWS Access Key ID and Secret Access Key - Direct credential authentication
2. IAM Instance Profile - For OpenEMR installations running on AWS EC2 instances

This guide explains how to set up both methods.

Method 1: Using AWS Access Keys

Step 1: Create an IAM User

1. Log in to the AWS Management Console
2. Navigate to the IAM service
3. In the left navigation pane, choose "Users" and then "Add user"
4. Enter a username (e.g., openemr-s3-user)
5. Select "Programmatic access" as the access type
6. Click "Next: Permissions"

Step 2: Set Permissions

1. Choose "Attach existing policies directly"
2. You can either:
   • Create and attach a custom policy (recommended, see below)
   • Use the built-in AmazonS3FullAccess policy (less secure, not recommended for production)

Creating a Custom Policy

1. In the IAM service, go to "Policies" in the left navigation
2. Click "Create policy"
3. Select the JSON tab and paste the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR-BUCKET-NAME"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR-BUCKET-NAME/*"
            ]
        }
    ]
}

4. Replace YOUR-BUCKET-NAME with your actual S3 bucket name
5. Click "Review policy", give it a name (e.g., OpenEMR-S3-Policy), and create it
6. Attach this policy to your IAM user

Step 3: Complete User Creation

1. Click through the "Tags" page (optional)
2. Review the user details and click "Create user"
3. IMPORTANT: This is the only time you'll see the Secret Access Key. Download the CSV file or copy both the Access Key ID and Secret Access Key to a secure location.

Step 4: Configure the OpenEMR S3 Module

1. In OpenEMR, navigate to Modules > Manage Modules
2. Enable the "S3 Storage Solution" module if not already enabled
3. Go to Modules > S3 Module
4. Enter the following information:
   • AWS Region (e.g., us-east-1)
   • AWS Key: Your Access Key ID
   • AWS Secret: Your Secret Access Key
   • Select "Key and Secret" for the authentication type
5. Click "Test Connection" to verify your settings
6. Select your S3 bucket from the dropdown
7. Save your settings

Method 2: Using IAM Instance Profile

This method is more secure as it doesn't require storing AWS credentials in the database. It only works when OpenEMR is hosted on an AWS EC2 instance.

Step 1: Create an IAM Role

1. Log in to the AWS Management Console
2. Navigate to the IAM service
3. In the left navigation pane, choose "Roles" and then "Create role"
4. Select "AWS service" as the trusted entity
5. Choose "EC2" as the service that will use this role
6. Click "Next: Permissions"

Step 2: Attach Permissions

1. Attach the same S3 permissions as described in Method 1 (either custom policy or AmazonS3FullAccess)
2. Click through "Tags" (optional)
3. Give the role a name (e.g., OpenEMR-EC2-S3-Role) and description
4. Click "Create role"

Step 3: Attach the Role to Your EC2 Instance

1. Go to the EC2 service in the AWS Console
2. Select your instance running OpenEMR
3. Choose "Actions" > "Security" > "Modify IAM role"
4. Select the role you created
5. Click "Save"

Step 4: Configure the OpenEMR S3 Module

1. In OpenEMR, navigate to Modules > Manage Modules
2. Enable the "S3 Storage Solution" module if not already enabled
3. Go to Modules > S3 Module
4. Enter the following information:
   • AWS Region (e.g., us-east-1) - this is still required
   • Select "Instance Profile" for the authentication type
   • Leave the Key and Secret fields blank
5. Click "Test Connection" to verify your settings
6. Select your S3 bucket from the dropdown
7. Save your settings

Creating an S3 Bucket

If you haven't created an S3 bucket yet:

1. Go to the S3 service in the AWS Console
2. Click "Create bucket"
3. Enter a unique bucket name (e.g., openemr-files-{your-organization})
4. Select the appropriate region (should match the region in your OpenEMR settings)
5. Configure bucket settings:
   • Enable versioning (recommended)
   • Enable server-side encryption (recommended)
   • Block all public access (recommended for healthcare data)
6. Click "Create bucket"

Security Best Practices

1. Least Privilege: Give your IAM user or role only the permissions it needs
2. Use Instance Profiles: When running on EC2, use IAM roles instead of access keys
3. Rotate Keys: If using access keys, rotate them regularly
4. Enable MFA: Require multi-factor authentication for the AWS account
5. Enable S3 Encryption: Always use server-side encryption for S3 buckets containing PHI
6. Enable S3 Versioning: Helps protect against accidental deletion or corruption
7. Enable Access Logging: Monitor all access to your S3 bucket

Troubleshooting

Common Issues

1. Connection Failed: Verify your region, credentials, and internet connectivity
2. Access Denied: Check that your IAM permissions include the necessary S3 actions
3. No Buckets Listed: Ensure your IAM policy includes the s3:ListAllMyBuckets permission
4. Cannot Upload/Download: Verify bucket permissions and that your policy includes the appropriate object actions

Logs to Check

1. OpenEMR error logs: /var/log/openemr/errors.log
2. AWS CloudTrail logs (for auditing AWS API calls)
3. S3 Access Logs (if enabled on your bucket)

Need Help?

If you need assistance with AWS configuration, please consult:

• AWS IAM Documentation
• AWS S3 Documentation
• OpenEMR Forums