S3 Integration Overview:
#

The Amazon S3 REST API provides a comprehensive set of HTTP operations for managing and interacting with objects and buckets in Amazon S3. Amazon S3 API Reference Link
Authentication: Supports AWS Signature Version 4 for secure request authentication.

---

⚠️ General restrictions: This integration allows you to use an Amazon S3 bucket as the backend virtual file system (VFS) in CrushFTP. However, since S3 is not a true hierarchical file system, folder structures are simulated using object key prefixes. As a result, renaming folders is not supported. These are not limitations imposed by CrushFTP, but inherent to S3’s object storage architecture, which is optimized for static content access, not for dynamic file manipulation.

---

⚠️ Proxy Configuration: If your server accesses the internet through a proxy, ensure that the necessary S3 domains are whitelisted to allow successful communication with the S3 REST API.

---

1. Amazon S3 Configuration.
#

Amazon S3 can be configured in CrushFTP using Access Key Authentication Link, EC2 IAM Authentication Link, or Assume Role authentication Link.

1.1 Access Key Authentication
#

The URL should be structured as follows (replace placeholders with your actual values):

General S3 : s3://ACCESS_KEY_ID:SEECRET_ACCESS_KEY@SERVER/BUCKET/

Amazon S3 Example: s3://AKIAEXAMPLE:abcd1234example@s3.amazonaws.com/my-bucket/

To access S3, you must authenticate using standard AWS credentials:
• Access Key ID – Your AWS access key.
• Secret Access Key – The corresponding secret key.

The Access Key ID and Secret Access Key are generated and offered for download when creating an S3 user (IAM user) in the AWS Management Console (More info: Manage access keys for IAM users Link). ⚠️ Make sure to save them securely, as the secret key will not be shown again.

The S3 Server Endpoint and Bucket Name can be found in the AWS Console under: S3 -> Buckets. This information is required to correctly configure your S3 integration.



Ensure that your S3 permissions are correctly configured as described in 1.3 Required S3 IAM Policy Permissions, and then configure the S3 Remote VFS item as described in 1.4 S3 Remote VFS Settings.

1.2 Amazon EC2 IAM Authentication Support
#

CrushFTP supports S3 authentication using IAM roles assigned to EC2 instances. This allows secure access without embedding static credentials.
To use this mode:
• Set the S3 Remote VFS -> Username to: iam_lookup
• Set the S3 Remote VFS -> Password to: lookup

This instructs CrushFTP to automatically retrieve temporary credentials from the EC2 instance’s IAM role via the instance metadata service. Use this approach to securely avoid hardcoding static credentials in environments where IAM roles are configured properly.

General EC2-Related Settings (Admin -> Preferences -> Misc -> S3 Configuration):

• Enable IMDSv2: IMDS (Instance Metadata Service) V2 is the more secure version of the metadata endpoint used by EC2 instances to retrieve IAM role credentials. Enabling this option ensures that CrushFTP uses token-based access to the metadata service, protecting against SSRF attacks and adhering to AWS security best practices.
⚠️ Important: Always enable IMDSv2 unless your instance or security policies require legacy IMDSv1.

• EC2 Use relative URL: When enabled, CrushFTP uses a relative URI path instead of an absolute path when communicating with the EC2 metadata service (http://169.254.169.254). This setting may be required in hardened environments or with certain proxy configurations that restrict full URL usage for local metadata requests. ⚠️ Note: Only enable this setting if you are encountering metadata access issues or are instructed to do so by AWS or your network/security administrator.



Ensure that your S3 permissions are correctly configured as described in 1.3 Required S3 IAM Policy Permissions, and then configure the S3 Remote VFS item as described in 1.4 S3 Remote VFS Settings.

1.3 Required S3 IAM Policy Permissions
#

---

❗Troubleshooting: An AccessDenied error in the logs typically indicates missing permissions. Verify that all required IAM policies are correctly attached to the user or role.

---

To allow proper integration with Amazon S3, ensure that your IAM user or role has the following permissions assigned:

"s3:GetBucketLocation",
"s3:ListAllMyBuckets",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts",
"s3:DeleteObject",
"s3:GetObject",
"s3:GetObjectAttributes"

Permission	Description	Why It’s Needed
s3:GetBucketLocation	Retrieves the AWS region of a specified bucket.	Required to validate bucket location and endpoint.
s3:ListAllMyBuckets	Lists all buckets owned by the requester.	Required for bucket verification.
s3:ListBucket	Lists objects within a specific bucket.	Allows viewing file/folder listings in a bucket.
s3:ListBucketMultipartUploads	Lists ongoing multipart uploads in a bucket.	Enables resuming or cleaning up incomplete multipart uploads.
s3:PutObject	Uploads an object to a bucket.	Required for writing (uploading) files.
s3:AbortMultipartUpload	Cancels an in-progress multipart upload.	Used to clean up failed or canceled large file uploads.
s3:ListMultipartUploadParts	Lists parts of a multipart upload.	Required when managing multipart uploads for large files.
s3:DeleteObject	Deletes an object from a bucket.	Allows file deletion capabilities.
s3:GetObject	Downloads or retrieves an object.	Required to read or download files.
s3:GetObjectAttributes	Retrieves metadata and properties of an object (e.g., size, last-modified).	Useful for showing detailed file info without downloading the entire object.

You may scope the "Resource" field to specific buckets or prefixes for more secure and limited access (e.g., "arn:aws:s3:::your-bucket-name/*").
⚠️ Important: In the CrushFTP S3 Remote item configuration, be sure to check the Don’t check the Bucket at login flag if the user does not have permission to list or access the bucket root directly.

1.4 S3 Remote VFS settings
#

Select the S3 remote item type.

Server: The base domain of the S3-compatible server (s3.us-east-1.amazonaws.com for Amazon S3). To use a non-Amazon provider, enter the provider’s endpoint hostname in the URL field.
Bucket: The S3 bucket name where files will be stored.
Path: Optional folder path within the bucket to restrict or set as the default working directory.

Accelerate: (For AWS only) Enables S3 Transfer Acceleration — faster uploads/downloads using AWS edge locations. Amazon S3 Transfer Acceleration – AWS Docs Link
Fast S3 item lookup: Enables a faster way to resolve S3 items. ⚠️ Must be enabled! Without this option, CrushFTP may perform slower lookups, especially on buckets with a large number of objects.
SHA256 enabled on signing (Signing Version 4): ⚠️ Uses AWS Signature Version 4 for authentication (required in most regions now).
Show Partial Uploads: When enabled, incomplete (multipart) uploads will appear in the file listing. Useful for debugging or managing failed uploads. Usually disabled to avoid cluttering the file list.
Use Bucket in Path: Includes the bucket name as part of the S3 object key/path. This is typically not required unless working with a non-standard or custom S3-compatible backend that expects this behavior.
Don’t check bucket at login: Skips checking if the bucket exists on login. Useful if your credentials lack s3:ListBucket permissions or the bucket is very large. Useful for non-Amazon providers too.
List Version 2: Enables S3 ListObjectsV2 API, which is more efficient and recommended over the legacy ListObjects (v1). Supports better pagination and consistent performance.Should be enabled for all modern S3 services unless the backend only supports the older version.

User Name: Your S3 Access Key ID or for Amazon EC2 IAM Authentication: iam_lookup.
Password: Your Secret Access Key or for Amazon EC2 IAM Authentication: lookup

Server Side Encrypt?: When checked, files uploaded to S3 will use Amazon S3 Server-Side Encryption (SSE-S3). This tells S3 to encrypt objects at rest using AWS-managed keys. If you want to use KMS keys instead, leave this unchecked and provide a key in the KMS Key Id field. See the Using Server-Side Encryption with Amazon S3 Link
Supported types: AES256,AWS_KMS
Canned ACL: Sets default Access Control for uploaded files: private, public-read, authenticated-read See the Canned ACLs – Amazon S3 Link
Storage Class: S3 storage tier. Like: STANDARD, GLACIER, INTELLIGENT_TIERING See the Storage Classes – Amazon S3 Link
KMS Key Id: Optional: If using AWS KMS encryption, provide the full ARN of the key here. See the Using Server-Side Encryption with AWS KMS (SSE-KMS) Link
Assume Role ARN: Optional. For cross-account access using IAM Role with sts:AssumeRole. See the 3. Assume role Access Link
Assume Role Region: AWS region where the IAM role resides (needed with Assume Role ARN).

Multithreaded S3 Uploads?, Multithreaded S3 Downloads?: Configure parallel upload/download parts for large files. Default settings: Admin -> Preferences -> Misc -> S3 Configuration
Add meta data: MD5 and uploaded by user: If enabled, CrushFTP will automatically add two pieces of metadata to each uploaded file:
• md5 – The MD5 checksum of the file content (used for integrity verification).
• uploaded_by – The username of the CrushFTP user who uploaded the file.

---

2. Access Amazon S3 using Assume Role
#

IAM roles in AWS allow you to delegate access to resources without sharing credentials. Instead of hardcoding access keys, you can configure trusted entities to assume a role with specific permissions. (Official Docs for Deeper Understanding: Amazon ID Roles Create for User Link, and Amazon API Assume Role Link )

Create the assume role at Identity and Access Management (IAM):









Attach a permission policy to the specified user that allows assuming the previously created IAM role.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::XXXXX:role/AssumeRoleS3"
        }
    ]
}

Use the specified user’s Access Key and Secret Key together with the Assume Role ARN to obtain credentials for accessing S3.



Ensure that your S3 permissions are correctly configured as described in 1.3 Required S3 IAM Policy Permissions, and then configure the S3 Remote VFS item as described in 1.4 S3 Remote VFS Settings.

---

3. Access other cloud storage through S3 REST API
#

Google Cloud - ⚠️ Important: Check the SHA256 enabled on signing (Signing Version 4) flag. Google Cloud Storage Access Through S3 REST API

BackBlaze(b2) - ⚠️ Important: SHA256 enabled on signing (Signing Version 4) and Include SHA256 to request headers (Signing Version 4 related) flags must be checked. BackBlaze(b2) Access Through S3 REST API

Yandex - ⚠️ Important: Ensure that the Server Side Encryption option is unchecked.

---