AWS Transfer Family provides a fully managed SFTP service for accessing S3 buckets securely. However, misconfigurations can result in frustrating issues like Permission Denied errors during SFTP operations. I encountered such an issue recently and resolved it by debugging and troubleshooting several aspects, from role trust relationships to bucket policies.
This guide explains how I resolved and fixed the problem while covering potential root causes and solutions for anyone facing similar challenges.
TL;DR
If you’re encountering Permission Denied errors on AWS Transfer Family, follow these steps:
- Verify the IAM role trust relationship and IAM Policies associated with your AWS Transfer Family server.
- Ensure bucket policies grant the required permissions.
- Check the user’s home directory mapping and logical directory settings.
- Debug further using CloudWatch Logs.
The Problem
After setting up an AWS Transfer Family server and configuring an SFTP user, I attempted to list files in the assigned S3 bucket. Despite configuring the bucket policy, the user’s logical directory mapping, and the IAM role, the connection resulted in the following error:
Can't ls: "/my-bucket/my-folder/" not found Initially, everything appeared to be correctly set up. The bucket existed, the user was configured with the right home directory, and the IAM role had the necessary permissions. However, the error persisted.
The Solution
Through step-by-step debugging, I discovered that the issue stemmed from the IAM role’s trust relationship. Here’s how I resolved it and other steps to verify your configuration.
1. Check the IAM Role Trust Relationship
The AWS Transfer Family server assumes an IAM role to access the S3 bucket. If the trust relationship for the role is incorrect, the server cannot assume the role, resulting in access errors.
Steps to Fix:
- Navigate to the IAM Console and select the role associated with your Transfer Family server.
- Go to the Trust Relationships tab.
- Verify that the trust relationship allows the Transfer Family service to assume the role. The policy should look like this:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "transfer.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}Note the principal for the transfer.amazonaws.com service.
If the trust policy is incorrect or missing, edit it to match the example above and save the changes.
2. Verify the Bucket Policy
The S3 bucket policy must explicitly grant permissions for the IAM role associated with the Transfer Family server.
Required Actions:
- s3:ListBucket: To list objects in the bucket.
- s3:GetObject and s3:PutObject: To download and upload files.
- s3:ListObjects: To navigate the directory structure.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/transfer-family-role"
},
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::my-bucket"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/transfer-family-role"
},
"Action": [
"s3:GetObject",
"s3:PutObject"
],
"Resource": "arn:aws:s3:::my-bucket/*"
}
]
}
- Replace
123456789012with your AWS account ID. - Replace
my-bucketwith the name of your S3 bucket.
3. Check User Configuration
The SFTP user must be configured with the correct home directory and logical directory mapping.
Steps to Verify:
1. Go to the AWS Transfer Family console and select your SFTP server.
2. Navigate to the Users tab and check the user’s settings.
3. Confirm the Home Directory field is set to the desired S3 path:
s3://my-bucket/my-folder/ 4. If you are using logical directories, verify the mappings:
Logical Directory Mapping Example:
{
"Entry": "/",
"Target": "arn:aws:s3:::my-bucket/my-folder/"
}5. Save the configuration and retest the SFTP connection.
4. Use CloudWatch Logs for Debugging
CloudWatch logs provide detailed insights into the operations and errors of AWS Transfer Family servers.
Steps to Enable Logging:
- Go to the AWS Transfer Family console and edit your server settings.
- Enable CloudWatch Logging and specify a log group.
- Attempt the SFTP connection again and review the logs in CloudWatch for error messages.
5. Verify Directory Structure in S3
Ensure the directory structure in S3 matches the paths configured in the user’s home directory or logical mapping.
Common Issues:
- Case sensitivity mismatch in directory names.
- Missing directories or files in the specified path.
Command to Verify S3 Path:
aws s3 ls s3://my-bucket/my-folder/ 6. Test and Validate Configuration
Once all configurations are updated:
1. Test the SFTP connection:
sftp -i ~/.ssh/id_ed25519 sftp-user@<sftp-endpoint> 2.Verify file listing:
ls / 
