Managing access controls - Amazon Transfer Family
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Managing access controls

You can control a user's access to Amazon Transfer Family resources by using an Amazon Identity and Access Management (IAM) policy. An IAM policy is a statement, typically in JSON format, that allows a certain level of access to a resource. You use an IAM policy to define what file operations that you want to allow your users to perform and not perform. You can also use an IAM policy to define what Amazon S3 bucket or buckets that you want to give your users access to. To specify these policies for users, you create an IAM role for Amazon Transfer Family that has the IAM policy and trust relationship associated with it.

Each user is assigned an IAM role. When a user logs in to your server, Amazon Transfer Family assumes the IAM role mapped to the user. To learn about creating an IAM role that provides a user access to an Amazon S3 bucket, see following. For information about how to create a role and delegate permissions, see Creating a role to delegate permissions to an Amazon service in the IAM User Guide.

The type of IAM role that Amazon Transfer Family uses is called a service role.


If your Amazon S3 bucket is encrypted using Amazon Key Management Service (Amazon KMS), you must specify additional permissions in your policy. For details, see Data encryption. Additionally, you can see more information about session policies in the IAM User Guide.

Allowing read and write access to an Amazon S3 bucket

Following, you can see how to create an IAM policy that allows read and write access to a specific Amazon S3 bucket. Assigning an IAM role that has this IAM policy to your user gives that user read/write access to the specified Amazon S3 bucket.

The following policy provides programmatic read and write access to an Amazon S3 bucket.

{ "Version": "2012-10-17", "Statement": [ { "Sid":"ReadWriteS3", "Action": [ "s3:ListBucket" ], "Effect": "Allow", "Resource": ["arn:aws-cn:s3:::bucketname"] }, { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:DeleteObjectVersion", "s3:GetObjectVersion", "s3:GetObjectACL", "s3:PutObjectACL" ], "Resource": ["arn:aws-cn:s3:::bucketname/*"] } ] }

The ListBucket action requires permission to the bucket itself. The PUT, GET, and DELETE actions require object permissions. Because these are different entities, they are specified using different Amazon Resource Names (ARNs).

If your bucket is enabled for Amazon Key Management Service (Amazon KMS) encryption, you need to enable additional actions in the policy. For more information about Amazon KMS, see What is Amazon Key Management Service?

To further restrict your users' access to only the home directory of the specified Amazon S3 bucket, see Creating a session policy for an Amazon S3 bucket.

Creating a session policy for an Amazon S3 bucket

A session policy is an Amazon Identity and Access Management (IAM) policy that restricts users to certain portions of an Amazon S3 bucket. It does so by evaluating access in real time.


Session policies are only used with Amazon S3. For Amazon EFS, you use POSIX file permissions to limit access.

You can use a session policy when you need to give the same access to a group of users to a particular portion of your Amazon S3 bucket. For example, a group of users might need access to only the home directory. That group of users share the same IAM role.


The maximum length of a session policy is 2048 characters. For more details, see the Policy request parameter for the CreateUser action in the API reference.

To create a session policy, use the following policy variables in your IAM policy:

  • ${transfer:HomeBucket}

  • ${transfer:HomeDirectory}

  • ${transfer:HomeFolder}

  • ${transfer:UserName}


You can't use the variables listed preceding in Managed Policies. Nor can you use them as policy variables in an IAM role definition. You create these variables in an IAM policy and supply them directly when setting up your user. Also, you can't use the ${aws:Username} variable in this session policy. This variable refers to an IAM user name and not the user name required by Amazon Transfer Family.

An example of a session policy is shown in the code example following.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListingOfUserFolder", "Action": [ "s3:ListBucket" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::${transfer:HomeBucket}" ], "Condition": { "StringLike": { "s3:prefix": [ "${transfer:HomeFolder}/*", "${transfer:HomeFolder}" ] } } }, { "Sid": "HomeDirObjectAccess", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObjectVersion", "s3:DeleteObject", "s3:GetObjectVersion", "s3:GetObjectACL", "s3:PutObjectACL" ], "Resource": "arn:aws-cn:s3:::${transfer:HomeDirectory}*" } ] }

In the policy above, it is assumed that users have their home directories set to include a trailing slash, to signify that it is a directory. If, on the other hand, you set a user's HomeDirectory without the trailing slash, then you should include it as part of your policy.

In the previous example policy, note the use of the transfer:HomeFolder, transfer:HomeBucket, and transfer:HomeDirectory policy parameters. These parameters are set for the HomeDirectory that is configured for the user, as described in HomeDirectory and Implementing your API Gateway method. These parameters have the following definitions:

  • The transfer:HomeBucket parameter is replaced with the first component of HomeDirectory.

  • The transfer:HomeFolder parameter is replaced with the remaining portions of the HomeDirectory parameter.

  • The transfer:HomeDirectory parameter has the leading forward slash (/) removed so that it can be used as part of an S3 Amazon Resource Name (ARN) in a Resource statement.


If you are using Logical directories—that is, the user's homeDirectoryType is LOGICAL—these policy parameters (HomeBucket, HomeDirectory, and HomeFolder) are not supported.

For example, assume that the HomeDirectory parameter that is configured for the Transfer Family user is /home/bob/amazon/stuff/.

  • transfer:HomeBucket is set to /home.

  • transfer:HomeFolder is set to /bob/amazon/stuff/.

  • transfer:HomeDirectory becomes home/bob/amazon/stuff/.

The first "Sid" allows the user to list all directories starting from /home/bob/amazon/stuff/.

The second "Sid" limits the user'put and get access to that same path, /home/bob/amazon/stuff/.

With the preceding policy in place, when a user logs in, they can access only objects in their home directory. At connection time, Amazon Transfer Family replaces these variables with the appropriate values for the user. Doing this makes it easier to apply the same policy documents to multiple users. This approach reduces the overhead of IAM role and policy management for managing your users' access to your Amazon S3 bucket.

You can also use a session policy to customize access for each of your users based on your business requirements. For more information, see Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity in the IAM User Guide.


Amazon Transfer Family stores the policy JSON, instead of the Amazon Resource Name (ARN) of the policy. So when you change the policy in the IAM console, you need to return to Amazon Transfer Family console and update your users with the latest policy contents. You can update the user under Policy Info tab in the User configuration section. For more information, see Managing access controls.

If you are using the Amazon CLI, you can use the following command to update the policy.

aws transfer update-user --server-id server --user-name user --policy \ "$(aws iam get-policy-version --policy-arn policy --version-id version --output json)"

Preventing users from running mkdir in an S3 bucket

You can limit users ability to create a directory in an Amazon S3 bucket. To do so, you create an IAM policy that allows the s3:PutObject action but also denies it when the key ends with a "/" (forward slash). The following example policy allows users to upload files to an Amazon S3 bucket but denies the mkdir command in the Amazon S3 bucket.

{ "Sid":"DenyMkdir", "Action":[ "s3:PutObject" ], "Effect":"Deny", "Resource":"arn:aws-cn:s3:::my-sftp-bucket/*/" }

Granting ability to only write and list files

In some cases, customers want to only offer write access to their Amazon S3 objects. They want to provide access to write/upload and list objects in a bucket, but not read/download. This translates to the Amazon S3 permissions ListObjects and PutOjbect to perform ls and mkdir commands using file transfer clients. However, when Transfer Family needs to make a HeadObject call to either write or list files, it fails with an error of Access denied, because this call requires the GetObject permission.

In this case, you can grant access by adding a policy condition that adds the GetObject permission for any objects that end in a /. This prevents GetObject on files so they cannot be read, while allowing the user to list and traverse folders. The following example policy offers only write and list access to their Amazon S3 buckets (replace DOC-EXAMPLE-BUCKET with the actual name of your bucket).

{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListing", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET" }, { "Sid": "AllowReadWrite", "Effect": "Allow", "Action": [ "s3:Put*", "s3:Get*" ], "Resource": [ "arn:aws-cn:s3:::{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListing", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET" }, { "Sid": "AllowReadWrite", "Effect": "Allow", "Action": [ "s3:Put*", "s3:Get*" ], "Resource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*" ] }, { "Sid": "DenyIfNotFolder", "Effect": "Deny", "Action": [ "s3:Get*" ], "NotResource": [ "arn:aws-cn:s3:::{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListing", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:::DOC-EXAMPLE-BUCKET" }, { "Sid": "AllowReadWrite", "Effect": "Allow", "Action": [ "s3:Put*", "s3:Get*" ], "Resource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*" ] }, { "Sid": "DenyIfNotFolder", "Effect": "Deny", "Action": [ "s3:Get*" ], "NotResource": [ "arn:aws-cn:s3:::{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListing", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET" }, { "Sid": "AllowReadWrite", "Effect": "Allow", "Action": [ "s3:Put*", "s3:Get*" ], "Resource": [ "arn:aws-cn:s3:::{ "Version": "2012-10-17", "Statement": [ { "Sid": "AllowListing", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET" }, { "Sid": "AllowReadWrite", "Effect": "Allow", "Action": [ "s3:Put*", "s3:Get*" ], "Resource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*" ] }, { "Sid": "DenyIfNotFolder", "Effect": "Deny", "Action": [ "s3:Get*" ], "NotResource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*/" ] } ] }/*" ] }, { "Sid": "DenyIfNotFolder", "Effect": "Deny", "Action": [ "s3:Get*" ], "NotResource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*/" ] } ] }/*/" ] } ] }/*/" ] } ] }/*" ] }, { "Sid": "DenyIfNotFolder", "Effect": "Deny", "Action": [ "s3:Get*" ], "NotResource": [ "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*/" ] } ] }

This policy does not allow for appending to a file. That is, a user that is assigned to this policy cannot open files to add content to them, or to modify them. Also, if your use case involves issuing a HeadObject call before uploading a file, this policy won't work for you.