AWS Transfer for SFTP
User Guide

Creating a Scope-Down Policy

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

You can use a scope-down policy when you need to give the same access to a group of users to a particular portion of your 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.

To create a scope-down policy, use the following policy variables in your IAM policy:

  • ${transfer:UserName}

  • ${transfer:HomeBucket}

  • ${transfer:HomeDirectory}


You cannot use the above variables as a policy variable in an IAM role definition. These variables will need to be created in an IAM policy and supplied directly when setting up your user. Also note that ${aws:Username} cannot be used in this scope down policy. This assignment refers to an IAM username and not the username required by the AWS SFTP service.

An example of a scope-down policy is shown in the code example following. For the scope-down policy to lock SFTP users to their home directory, you will need to make sure the path you assign for their home directory contains the username. For e.g. if username="bob", then the home directory needs to contain “bob”.

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

With the preceding policy in place, when the user logs in they can access only objects within their home directory. We defined that previously as /my-bucket/home/username. At connection time, AWS SFTP 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.

Another use case of scope down policy is customizing access for each of your users based on your business requirements. See Permissions for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity for more information on this topic.