# Prerequisites
The following sections describe the prerequisites required to use the AWS Transfer Family service. At a minimum, you need to create an Amazon Simple Storage Service (Amazon S3) bucket and provide access to that bucket through an AWS Identity and Access Management (IAM) role. Your role also needs to establish a trust relationship. This trust relationship allows Transfer Family to assume the IAM role to access your bucket so that it can service your users' file transfer requests.
For information about IPv6 support for AWS Transfer Family servers, see [IPv6 support for Transfer Family servers](ipv6-support.md) in the Managing servers chapter.
**Topics**
+ [Supported AWS Regions, endpoints and quotas for Transfer Family servers](#regions)
+ [Sign up for AWS](requirements-aws-signup.md)
+ [Configure storage to use with AWS Transfer Family servers](configure-storage.md)
+ [Create an IAM role and policy](requirements-roles.md)
## Supported AWS Regions, endpoints and quotas for Transfer Family servers
To connect programmatically to an AWS service, you use an endpoint. For example, the endpoint for customers in US East (Ohio) region (`us-east-2`), is `transfer.us-east-2.amazonaws.com`. Service quotas, also referred to as limits, are the maximum number of service resources or operations for your AWS account. In this guide, you can find quotas in [AS2 quotas](create-b2b-server.md#as2-quotas) and [Quotas for SFTP connectors](scale-and-limits-sftp-connector.md#limits-sftp-connector).
For more information about supported AWS Regions, endpoints, and service quotas, see [AWS Transfer Family endpoints and quotas](https://docs.aws.amazon.com//general/latest/gr/transfer-service.html) in the *Amazon Web Services General Reference*.
For Transfer Family web apps, the supported regions are listed in [AWS Regions for Transfer Family web apps](web-app.md#webapp-regions). For quotas that pertain to Transfer Family web apps, see [Web app quotas](webapp-end-users.md#end-user-quotas).
# Sign up for AWS
When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including AWS Transfer Family. You are charged only for the services that you use.
If you have an AWS account already, skip to the next task. If you don't have an AWS account, use the following procedure to create one.
If you do not have an AWS account, complete the following steps to create one.
**To sign up for an AWS account**
1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup).
1. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad.
When you sign up for an AWS account, an *AWS account root user* is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks).
For information about pricing and to use AWS Pricing Calculator to get an estimate of the cost to use Transfer Family, see [AWS Transfer Family pricing](https://aws.amazon.com/sftp/pricing/).
For information about AWS Region availability, see the [AWS Transfer Family endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html) in the *AWS General Reference*.
# Configure storage to use with AWS Transfer Family servers
This topic describes the storage options that you can use with AWS Transfer Family. You can use either Amazon S3 or Amazon EFS as storage for your Transfer Family servers.
**Contents**
+ [Configure an Amazon S3 bucket](#requirements-S3)
+ [Amazon S3 access points](#access-points)
+ [Amazon S3 HeadObject behavior](#head-object-behavior)
+ [Grant ability to only write and list files](#headobject-access-denied)
+ [Large number of zero-byte objects causing latency issues](#headobject-latency)
+ [Configure an Amazon EFS file system](#requirements-efs)
+ [Amazon EFS file ownership](#efs-file-ownership)
+ [Set up Amazon EFS users for Transfer Family](#configure-efs-users-permissions)
+ [Configure Transfer Family users on Amazon EFS](#set-up-efs-home-folders)
+ [Create an Amazon EFS root user](#create-root-user-efs)
+ [Supported Amazon EFS commands](#efs-commands)
## Configure an Amazon S3 bucket
AWS Transfer Family accesses your Amazon S3 bucket to service your users' transfer requests, so you need to provide an Amazon S3 bucket as part of setting up your file transfer protocol-enabled server. You can use an existing bucket, or you can create a new one.
**Note**
You don't have to use a server and Amazon S3 bucket that are in the same AWS Region, but we recommend this as a best practice.
When you set up your users, you assign them each an IAM role. This role determines the level of access that they have to your Amazon S3 bucket.
For information on creating a new bucket, see [How do I create an S3 bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket-overview.html) in the *Amazon Simple Storage Service User Guide*.
**Note**
You can use Amazon S3 Object Lock to prevent objects from being overwritten for a fixed amount of time or indefinitely. This works the same way with Transfer Family as with other services. If an object exists and is protected, writing to that file or deleting it is not allowed. For more details on Amazon S3 Object Lock, see [Using Amazon S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/object-lock.html) in the *Amazon Simple Storage Service User Guide*.
### Amazon S3 access points
AWS Transfer Family supports [Amazon S3 Access Points](https://aws.amazon.com/s3/features/access-points/), a feature of Amazon S3 that allows you to easily manage granular access to shared data sets. You can use S3 Access Point aliases anywhere you use an S3 bucket name. You can create hundreds of access points in Amazon S3 for users who have different permissions to access shared data in an Amazon S3 bucket.
For example, you can use access points to allow three different teams to have access to the same shared dataset where one team can read data from S3, a second team can write data to S3, and the third team can read, write, and delete data from S3. To implement a granular access control as mentioned above, you can create an S3 access point that contains a policy that gives asymmetrical access to different teams. You can use S3 access points with your Transfer Family server to achieve a fine-grained access control, without creating a complex S3 bucket policy that spans hundreds of use cases. To learn more about how to use S3 access points with a Transfer Family server, refer to the [ Enhance data access control with AWS Transfer Family and Amazon S3](https://aws.amazon.com/blogs/storage/enhance-data-access-control-with-aws-transfer-family-and-amazon-s3-access-points/) blog post.
**Note**
AWS Transfer Family does not currently support Amazon S3 Multi-Region Access Points.
### Amazon S3 HeadObject behavior
**Note**
When you create or update a Transfer Family server, you can optimize performance for your Amazon S3 directories, which eliminates `HeadObject` calls.
In Amazon S3, buckets and objects are the primary resources, and objects are stored in buckets. Amazon S3 can mimic a hierarchical file system, but can sometimes behave differently than a typical file system. For example, directories are not a first-class concept in Amazon S3 but instead are based on object keys. AWS Transfer Family infers a directory path by splitting an object's key by the forward slash character (**/**), treating the last element as the file name, then grouping file names which have the same prefix together under the same path. Zero-byte objects are created to represent a folder's path when you create an empty directory using `mkdir` or by using the Amazon S3 console. The key for these objects ends in a trailing forward slash. These zero-byte objects are described in [Organizing objects in the Amazon S3 console using folders](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-folders.html) in the *Amazon S3 User Guide*.
When you run an `ls` command, and some results are Amazon S3 zero-byte objects (these objects have keys that end in the forward slash character), Transfer Family issues a `HeadObject` request for each of these objects (see [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) in the *Amazon Simple Storage Service API Reference* for details). This can result in the following problems when using Amazon S3 as your storage with Transfer Family.
#### Grant ability to only write and list files
In some cases, you might want to offer only write access to your Amazon S3 objects. For example, you might want to provide access to write (or upload) and list objects in a bucket, but not to read (download) objects. To perform `ls` and `mkdir` commands by using file transfer clients, you must have the Amazon S3 `ListObjects` and `PutObject` permissions. However, when Transfer Family needs to make a `HeadObject` call to either write or list files, the call fails with an error of **Access denied**, because this call requires the `GetObject` permission.
**Note**
When you create or update a Transfer Family server, you can optimize performance for your Amazon S3 directories, which eliminates `HeadObject` calls.
In this case, you can grant access by adding an AWS Identity and Access Management (IAM) policy condition that adds the `GetObject` permission only for objects that end in a slash (`/`). This condition prevents `GetObject` calls on files (so that they can't be read), but allows the user to list and traverse folders. The following example policy offers only write and list access to your Amazon S3 buckets. To use this policy, replace `amzn-s3-demo-bucket` with the name of your bucket.
**Note**
To address WinSCP's upload behavior, make sure to add the `"arn:aws:s3:::amzn-s3-demo-bucket/*.filepart"` line as listed in the following example policy. This line ensures proper handling of .filepart objects to prevent failures.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowListing",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
},
{
"Sid": "AllowReadWrite",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
},
{
"Sid": "DenyIfNotFolder",
"Effect": "Deny",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"NotResource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*/",
"arn:aws:s3:::amzn-s3-demo-bucket/*.filepart"
]
}
]
}
```
**Note**
This policy doesn't allow users to append files. In other words, a user who is assigned this policy can't open files to add content to them, or to modify them. Additionally, if your use case requires a `HeadObject` call before uploading a file, this policy won't work for you.
#### Large number of zero-byte objects causing latency issues
If your Amazon S3 buckets contain a large number of these zero-byte objects, Transfer Family issues a lot of `HeadObject` calls, which can result in processing delays. The recommended solution for this issue is to enable **Optimized Directories** to reduce latency.
For example, suppose that you go into your home directory, and you have 10,000 subdirectories. In other words, your Amazon S3 bucket has 10,000 folders. In this scenario, if you run the `ls` (list) command, the list operation takes between six and eight minutes. However, if you optimize your directories, this operation takes only a few seconds. You set this option in the **Configure additional details** screen during the server creation or update procedure. These procedures are detailed under the [Configuring an SFTP, FTPS, or FTP server endpoint](sftp-for-transfer-family.md) topic.
**Note**
GUI clients may issue an `ls` command outside your control, so it is important to enable this setting if you can.
If you don't or can't optimize your directories, an alternate solution to this problem is to delete all of your zero-byte objects. Note the following:
+ Empty directories will no longer exist. Directories only exist as a result of their names being in the key of an object.
+ Doesn’t prevent someone from calling `mkdir` and breaking things all over again. You could mitigate this by crafting a policy which prevents directory creation.
+ Some scenarios make use of these 0-byte objects. For example, you have a structure like **/inboxes/customer1000** and the inbox directory gets cleaned every day.
Finally, one more possible solution is to limit the number of objects visible through a policy condition to reduce the number of `HeadObject` calls. For this to be a workable solution, you need to accept that you might only be able to view a limited set of all of your sub-directories.
## Configure an Amazon EFS file system
AWS Transfer Family accesses Amazon Elastic File System (Amazon EFS) to service your users' transfer requests. So you must provide an Amazon EFS file system as part of setting up your file transfer protocol-enabled server. You can use an existing file system, or you can create a new one.
Note the following:
+ When you use a Transfer Family server and an Amazon EFS file system, the server and the file system must be in the same AWS Region.
+ The server and the file system don't need to be in the same account. If the server and file system are not in the same account, the file system policy must give explicit permission to the user role.
For information about how to set up multiple accounts, see [Managing the AWS accounts in your organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts.html) in the *AWS Organizations User Guide*.
+ When you set up your users, you assign them each an IAM role. This role determines the level of access that they have to your Amazon EFS file system.
+ For details on mounting an Amazon EFS file system, see [Mounting Amazon EFS file systems](https://docs.aws.amazon.com//efs/latest/ug/mounting-fs.html).
For more details on how AWS Transfer Family and Amazon EFS work together, see [Using AWS Transfer Family to access files in your Amazon EFS file system](https://docs.aws.amazon.com//efs/latest/ug/using-aws-transfer-integration.html) in the *Amazon Elastic File System User Guide*.
### Amazon EFS file ownership
Amazon EFS uses the Portable Operating System Interface (POSIX) file permission model to represent file ownership.
In POSIX, users in the system are categorized into three distinct permission classes: When you allow a user to access files stored in an Amazon EFS file system using AWS Transfer Family, you must assign them a “POSIX profile.” This profile is used to determine their access to files and directories in the Amazon EFS file system.
+ User (u): Owner of the file or directory. Usually, the creator of a file or directory is also the owner.
+ Group (g): Set of users that need identical access to files and directories that they share.
+ Others (o): All other users that have access to the system except for the owner and group members. This permission class is also referred to as "Public."
In the POSIX permission model, every file system object (files, directories, symbolic links, named pipes, and sockets) is associated with the previously mentioned three sets of permissions. Amazon EFS objects have a Unix-style mode associated with them. This mode value defines the permissions for performing actions on that object.
Additionally, on Unix-style systems, users and groups are mapped to numeric identifiers, which Amazon EFS uses to represent file ownership. For Amazon EFS, objects are owned by a single owner and a single group. Amazon EFS uses the mapped numeric IDs to check permissions when a user attempts to access a file system object.
### Set up Amazon EFS users for Transfer Family
Before you set up your Amazon EFS users, you can do either of the following:
+ You can create users and set up their home folders in Amazon EFS. See [Configure Transfer Family users on Amazon EFS](#set-up-efs-home-folders) for details.
+ If you are comfortable adding a root user, you can [Create an Amazon EFS root user](#create-root-user-efs).
**Note**
Transfer Family servers do not support Amazon EFS access points to set POSIX permissions. Transfer Family users' POSIX profiles (described in the preceding section) offer the ability to set POSIX permissions. These permissions are set at a user level, for granular access, based on UID, GID, and secondary GIDs.
#### Configure Transfer Family users on Amazon EFS
Transfer Family maps the users to the UID/GID and directories you specify. If the UID/GID/directories do not already exist in EFS, then you should create them before assigning them in Transfer to a user. The details for creating Amazon EFS users is described in [Working with users, groups, and permissions at the Network File System (NFS) Level](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs-nfs-permissions.html) in the *Amazon Elastic File System User Guide*.
**Steps to set up Amazon EFS users in Transfer Family**
1. Map the EFS UID and GID for your user in Transfer Family using the [https://docs.aws.amazon.com/transfer/latest/APIReference/API_PosixProfile.html](https://docs.aws.amazon.com/transfer/latest/APIReference/API_PosixProfile.html) fields.
1. If you want the user to start in a specific folder upon login, you can specify the EFS directory under the [https://docs.aws.amazon.com/transfer/latest/APIReference/API_CreateUser.html#TransferFamily-CreateUser-request-HomeDirectory](https://docs.aws.amazon.com/transfer/latest/APIReference/API_CreateUser.html#TransferFamily-CreateUser-request-HomeDirectory) field.
You can automate the process, by using a CloudWatch rule and Lambda function. For an example Lambda function that interacts with EFS, see [Using Amazon EFS for AWS Lambda in your serverless applications](https://aws.amazon.com/blogs/compute/using-amazon-efs-for-aws-lambda-in-your-serverless-applications).
Additionally, you can configure logical directories for your Transfer Family users. For details, see the [Configure logical directories for Amazon EFS](logical-dir-mappings.md#logical-dir-efs) section in the [Using logical directories to simplify your Transfer Family directory structures](logical-dir-mappings.md) topic.
#### Create an Amazon EFS root user
If your organization is comfortable for you to enable root user access via SFTP/FTPS for the configuration of your users, you can create a user who's UID and GID are 0 (root user), then use that root user to create folders and assign POSIX ID owners for rest of the users. The advantage of this option is that there is no need to mount the Amazon EFS file system.
Perform the steps described in [Adding Amazon EFS service-managed users](service-managed-users.md#add-efs-user), and for both the User ID and Group ID, enter 0 (zero).
**Tip**
Don't let this superuser account exist for longer than necessary. Or, if you do keep the root user account, make sure that you keep it well protected.
### Supported Amazon EFS commands
The following commands are supported for Amazon EFS for AWS Transfer Family.
+ `cd`
+ `ls`/`dir`
+ `pwd`
+ `put`
+ `get`
+ `rename`
+ `chown`: Only root (that is, users with uid=0) can change ownership and permissions of files and directories.
+ `chmod`: Only root can change ownership and permissions of files and directories.
+ `chgrp`: Supported either for root or for the file's owner who can only change a file's group to be one of their secondary groups.
+ `ln -s`/`symlink`
+ `mkdir`
+ `rm`/`delete`
+ `rmdir`
+ `chmtime`
# Create an IAM role and policy
This topic describes the types of policies and roles that can be used with AWS Transfer Family, and walks through the process of creating a user role. It also describes how session policies work and provides an example user role.
AWS Transfer Family uses the following types of roles:
+ **User role** – Allows service-managed users to access the necessary Transfer Family resources. AWS Transfer Family assumes this role in the context of a Transfer Family user ARN.
+ **Access role** – Provides access to only the Amazon S3 files that are being transferred. For inbound AS2 transfers, the access role uses the Amazon Resource Name (ARN) for the agreement. For outbound AS2 transfers, the access role uses the ARN for the connector.
+ **Invocation role** – For use with Amazon API Gateway as the server's custom identity provider. Transfer Family assumes this role in the context of a Transfer Family server ARN.
+ **Logging role** – Used to log entries into Amazon CloudWatch. Transfer Family uses this role to log success and failure details along with information about file transfers. Transfer Family assumes this role in the context of a Transfer Family server ARN. For outbound AS2 transfers, the logging role uses the connector ARN.
+ **Execution role** – Allows a Transfer Family user to call and launch workflows. Transfer Family assumes this role in the context of a Transfer Family workflow ARN.
In addition to these roles, you can also use *session policies*. A session policy is used to limit access when necessary. Note that these policies are stand-alone: that is, you don't add these polices to a role. Rather, you add a session policy directly to a Transfer Family user.
**Note**
When you are creating a service-managed Transfer Family user, you can select **Auto-generate policy based on home folder**. This is a useful shortcut if you want to limit user access to their own folders. Also, you can view details about session policies and an example in [How session policies work](#session-policy). You can also find more information about session policies in [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*.
**Topics**
+ [Create a user role](#role-create-procedure)
+ [How session policies work](#session-policy)
+ [Example read/write access policy](#read-write-access)
## Create a user role
When you create a user, you make a number of decisions about user access. These decisions include which Amazon S3 buckets or Amazon EFS file systems that the user can access, what portions of each Amazon S3 bucket and which files in the file system are accessible, and what permissions the user has (for example, `PUT` or `GET`).
To set access, you create an identity-based AWS Identity and Access Management (IAM) policy and role that provide that access information. As part of this process, you provide access for your user to the Amazon S3 bucket or Amazon EFS file system that is the target or source for file operations. To do this, take the following high-level steps, described in detail later:
**Create a user role**
1. Create an IAM policy for AWS Transfer Family. This is described in [To create an IAM policy for AWS Transfer Family](#iam-policy-procedure).
1. Create an IAM role and attach the new IAM policy. For an example, see [Example read/write access policy](#read-write-access).
1. Establish a trust relationship between AWS Transfer Family and the IAM role. This is described in [To establish a trust relationship](#establish-trust-transfer).
The following procedures describe how to create an IAM policy and role.
**To create an IAM policy for AWS Transfer Family**
1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane, choose **Policies**, and then choose **Create policy**.
1. On the **Create Policy** page, choose the **JSON** tab.
1. In the editor that appears, replace the contents of the editor with the IAM policy that you want attach to the IAM role.
You can grant read/write access or restrict users to their home directory. For more information, see [Example read/write access policy](#read-write-access).
1. Choose **Review policy** and provide a name and description for your policy, and then choose **Create policy**.
Next, you create an IAM role and attach the new IAM policy to it.
**To create an IAM role for AWS Transfer Family**
1. In the navigation pane, choose **Roles**, and then choose **Create role**.
On the **Create role** page, make sure that **AWS service** is chosen.
1. Choose **Transfer** from the service list, and then choose **Next: Permissions**. This establishes a trust relationship between AWS Transfer Family and AWS.
1. In the **Attach permissions policies** section, locate and choose the policy that you just created, and choose **Next: Tags**.
1. (Optional) Enter a key and value for a tag, and choose **Next: Review**.
1. On the **Review** page, enter a name and description for your new role, and then choose **Create role**.
Next, you establish a trust relationship between AWS Transfer Family and AWS.
**To establish a trust relationship**
**Note**
In our examples, we use both `ArnLike` and `ArnEquals`. They are functionally identical, and therefore you may use either when you construct your policies. Transfer Family documentation uses `ArnLike` when the condition contains a wildcard character, and `ArnEquals` to indicate an exact match condition.
1. In the IAM console, choose the role that you just created.
1. On the **Summary** page, choose **Trust relationships**, and then choose **Edit trust relationship**.
1. In the **Edit Trust Relationship** editor, make sure **service** is `"transfer.amazonaws.com"`. The access policy is shown following.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "transfer.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
We recommend that you use the `aws:SourceAccount` and `aws:SourceArn` condition keys to protect yourself against the confused deputy problem. The source account is the owner of the server and the source ARN is the ARN of the user. For example:
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account_id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:transfer:region:account_id:user/*"
}
}
```
You can also use the `ArnLike` condition if you are looking to restrict to a particular server instead of any server in the user account. For example:
```
"Condition": {
"ArnLike": {
"aws:SourceArn": "arn:aws:transfer:region:account-id:user/server-id/*"
}
}
```
**Note**
In the examples above, replace each *user input placeholder* with your own information.
For details on the confused deputy problem and more examples, see [Cross-service confused deputy prevention](confused-deputy.md).
1. Choose **Update Trust Policy** to update the access policy.
You have now created an IAM role that allows AWS Transfer Family to call AWS services on your behalf. You attached to the role the IAM policy that you created to give access to your user. In the [Getting started with AWS Transfer Family server endpoints](getting-started.md) section, this role and policy are assigned to your user or users.
**See also**
+ For more general information about IAM roles, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*.
+ To learn more about identity-based policies for Amazon S3 resources, see [Identity and access management in Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html) in the *Amazon Simple Storage Service User Guide*.
+ To learn more about identity-based policies for Amazon EFS resources, see [Using IAM to control file system data access](https://docs.aws.amazon.com/efs/latest/ug/iam-access-control-nfs-efs.html) in the *Amazon Elastic File System User Guide*.
## How session policies work
When an administrator creates a role, the role often includes broad permissions to cover multiple use cases or team members. If an administrator configures a [console URL](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html), they can reduce permissions for the resulting session by using a *session policy*. For example, if you create a role with [read/write access](#read-write-access), you can set up a URL that limits users’ access to only their home directories.
Session policies are advanced policies that you pass as a parameter when you programmatically create a temporary session for a role or user. Session policies are useful for locking down users so that they have access only to portions of your bucket where object prefixes contain their username. The following diagram shows that the session policy's permissions are the intersection of the session policies and the resource-based policies plus the intersection of the session policies and identity-based policies.
![\[Session policy permissions Venn diagram. Shows how effective permissions lie in the intersections of resource-based policies, identity-based polices, and session policies.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/EffectivePermissions-session-rbp-id.png)
For more details, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*.
In AWS Transfer Family, a session policy is supported only when you are transferring to or from Amazon S3. The following example policy is a session policy that limits users' access to their `home` directories only. Note the following:
+ The `GetObjectACL` and `PutObjectACL` statements are only required if you need to enable Cross Account Access. That is, your Transfer Family server needs to access a bucket in a different account.
+ The maximum length of a session policy is 2048 characters. For more details, see the [Policy request parameter](https://docs.aws.amazon.com/transfer/latest/APIReference/API_CreateUser.html#API_CreateUser_RequestSyntax) for the `CreateUser` action in the *API reference*.
+ If your Amazon S3 bucket is encrypted using AWS Key Management Service (AWS KMS), you must specify additional permissions in your policy. For details, see [Data protection and encryption](encryption-at-rest.md).
+ To use session policies to create access permissions based on user attributes without creating separate IAM roles for each user, see [Dynamic permission management approaches](dynamic-permission-management.md).
****
```
{
"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:DeleteObject",
"s3:DeleteObjectVersion",
"s3:GetObjectVersion",
"s3:GetObjectACL",
"s3:PutObjectACL"
],
"Resource": "arn:aws:s3:::${transfer:HomeDirectory}/*"
}
]
}
```
**Note**
The preceding policy example assumes 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](https://docs.aws.amazon.com/transfer/latest/APIReference/API_CreateUser.html#TransferFamily-CreateUser-request-HomeDirectory) and [Implementing your API Gateway method](authentication-api-gateway.md#authentication-api-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.
**Note**
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/`.
## Example read/write access policy
**Grant read/write access to Amazon S3 bucket**
The following example policy for AWS Transfer Family grants read/write access to objects in your Amazon S3 bucket.
Note the following:
+ Replace `amzn-s3-demo-bucket` with the name of your Amazon S3 bucket.
+ The `GetObjectACL` and `PutObjectACL` statements are only required if you need to enable Cross Account Access. That is, your Transfer Family server needs to access a bucket in a different account.
+ The `GetObjectVersion` and `DeleteObjectVersion` statements are only required if versioning is enabled on the Amazon S3 bucket that is being accessed.
**Note**
If you have *ever* enabled versioning for your bucket, then you need these permissions, as you can only suspend versioning in Amazon S3, and not turn it off completely. For details, see [Unversioned, versioning-enabled, and versioning-suspended buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html#versioning-states).
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowListingOfUserFolder",
"Action": [
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket"
]
},
{
"Sid": "HomeDirObjectAccess",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:GetObjectTagging",
"s3:DeleteObject",
"s3:DeleteObjectVersion",
"s3:GetObjectVersion",
"s3:GetObjectVersionTagging",
"s3:GetObjectACL",
"s3:PutObjectACL"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*"
}
]
}
```
**Grant file system access to files in Amazon EFS file system**
**Note**
In addition to the policy, you must also make sure your POSIX file permissions are granting the appropriate access. For more information, see [Working with users, groups, and permissions at the Network File System (NFS) Level](https://docs.aws.amazon.com/efs/latest/ug/accessing-fs-nfs-permissions.html) in the *Amazon Elastic File System User Guide*.
The following example policy grants root file system access to files in your Amazon EFS file system.
**Note**
In the following examples, replace *region* with your region, *account-id* with the account the file is in, and *file-system-id* with the ID of your Amazon Elastic File System (Amazon EFS).
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "RootFileSystemAccess",
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientRootAccess",
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": "arn:aws:elasticfilesystem:us-east-1:123456789012:file-system/file-system-id"
}
]
}
```
The following example policy grants user file system access to files in your Amazon EFS file system.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "UserFileSystemAccess",
"Effect": "Allow",
"Action": [
"elasticfilesystem:ClientMount",
"elasticfilesystem:ClientWrite"
],
"Resource": "arn:aws:elasticfilesystem:us-east-1:123456789012:file-system/file-system-id"
}
]
}
```