AWS Documentation » Amazon Simple Storage Service (S3) » Developer Guide » Access Control » Using IAM Policies	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Using IAM Policies

Topics

AWS Identity and Access Management (IAM) enables you to create multiple users within your AWS account, assign them security credentials, and manage their permissions. You manage user permissions via IAM policies. These policies are attached to the users, enabling centralized control of permissions for users under your AWS account.

Amazon S3 supports resource-based permissions on objects and buckets using access control list (ACL) and bucket policies. The ACLs and bucket policies are attached to buckets and objects defining which AWS accounts (or other groups of actors) have access and the type of access.

You can use both of these in conjunction with IAM user policies to control access to your Amazon S3 resources. The following table summarizes similarities and differences between ACLs, bucket policies, and IAM policies.

Type of Access Control	AWS Account-Level Control?	User-Level Control?	Format
ACLs	Yes	No	Special XML-based format defined by Amazon S3
Bucket policies	Yes	Yes	Access policy language
IAM policies	No	Yes	Access policy language

With ACLs, you can only grant other AWS accounts access to your Amazon S3 resources. With IAM policies, you can only grant users within your own AWS account permission to your Amazon S3 resources. With bucket policies, you can do both.

This section describes how IAM works with bucket policies and ACLs.

IAM and Bucket Policies Together

When someone sends a request to use your AWS account's Amazon S3 resources, we evaluate all applicable ACLs, bucket policies, and IAM policies together to determine whether to give the requester access.

Although you can still use ACLs to grant permission, this section focuses on how to use IAM policies and bucket policies to give users in your AWS account permissions to access your Amazon S3 resources. You can use bucket policies, IAM policies, or both. For the most part, you can achieve the same results with either. For example, the following diagram shows an IAM policy and a bucket policy that are equivalent. The IAM policy (on the left) allows the Amazon S3 PutObject action for the bucket called bucket_xyz in your AWS account, and it's attached to the users Bob and Susan (which means Bob and Susan have the permissions stated in the policy).

The bucket policy (on the right) is attached to bucket_xyz. As with the IAM policy, the bucket policy gives Bob and Susan permission to access PutObject on bucket_xyz.

Note

The preceding example shows simple policies with no conditions. You could specify a particular condition in either policy and get the same result.

IAM policies lets you manage access to your Amazon S3 resources based on user; whereas bucket policies let you manage access based on the specific resources. The following examples further illustrate how the two policy systems work together.

Example 1

In this example, Bob has both an IAM policy and a bucket policy that apply to him. The IAM policy gives him permission to use PutObject on bucket_xyz, whereas the bucket policy gives him permission to use ListBucket on that same bucket. The following diagram illustrates the concept.

If Bob were to send a request to put an object into bucket_xyz, the IAM policy would allow the action. If Bob were to send a request to list the objects in bucket_xyz, the bucket policy would allow the action.

Example 2

In this example, we build on the previous example (where Bob has two policies that apply to him). Let's say that Bob abuses his access to bucket_xyz, so you want to remove his entire access to that bucket. The easiest thing to do is add a policy that denies him access to all actions on the bucket. This third policy overrides the other two, because an explicit deny always overrides an allow (for more information about policy evaluation logic, see Evaluation Logic). The following diagram illustrates the concept.

Alternatively, you could add an additional statement to the bucket policy that denies Bob any type of access to the bucket. It would have the same effect as adding a IAM policy that denies him access to the bucket.

For examples of policies that cover Amazon S3 actions and resources, see Example Policies for Amazon S3. For more information about writing S3 policies, go to the Amazon Simple Storage Service Developer Guide.

Permissions for Resource Creator

Amazon S3 by default gives the AWS account that created the bucket or object full permissions on that resource. However, if a user (not the AWS account) creates a bucket or object, that user doesn't by default have permission to perform other actions on that resource. The user must be granted the additional permissions in an IAM policy.

Amazon S3 ARNs

For Amazon S3, the resources you can specify in a policy are buckets and objects. The Amazon Resource Name (ARN) follows this format:

arn:aws:s3:::bucket_name/key_name

where arn:aws:s3:::bucket_name refers only to the bucket, and the entire string arn:aws:s3:::bucket_name/key_name refers to the object.

For example:

arn:aws:s3:::example_bucket/developers/design_info.doc

The Region and AWS Account ID portions of the ARN must be empty because bucket names are global.

You can also use policy variables in Amazon S3 ARNs. For example, suppose your Amazon S3 bucket contains one folder for each IAM user. By using policy variables, you can grant each user a private folder with a single ARN :

arn:aws:s3:::bucket_name/developers/${aws:username}/

When the policy is evaluated, the variable ${aws:username} is substituted with the user name of the principal making the request. For more information about policy variables, go to Policy Variables in the AWS Identity and Access Management Using IAM guide.

Amazon S3 Actions

The Amazon S3 actions that you can specify in a policy are divided into groups based on the type of resource.

Actions Related to Objects

s3:GetObject (covers REST GET Object, REST HEAD Object, REST GET Object torrent, SOAP GetObject, and SOAP GetObjectExtended)
s3:GetObjectVersion (covers REST GET Object, REST HEAD Object, REST GET Object torrent, SOAP GetObject, and SOAP GetObjectExtended)
s3:PutObject (covers the REST PUT Object, REST POST Object, REST Initiate Multipart Upload, REST Upload Part, REST Complete Multipart Upload, SOAP PutObject, and SOAP PutObjectInline)
s3:GetObjectAcl
s3:GetObjectVersionAcl
s3:PutObjectAcl
s3:PutObjectVersionAcl
s3:DeleteObject
s3:DeleteObjectVersion
s3:ListMultipartUploadParts
s3:AbortMultipartUpload
s3:GetObjectTorrent
s3:GetObjectVersionTorrent
s3:RestoreObject

Actions Related to Buckets

s3:CreateBucket
s3:DeleteBucket
s3:ListBucket
s3:ListBucketVersions
s3:ListAllMyBuckets (covers REST GET Service and SOAP ListAllMyBuckets)
s3:ListBucketMultipartUploads

Actions Related to Bucket Sub-Resources

s3:GetBucketAcl
s3:PutBucketAcl
s3:GetBucketCORS
s3:PutBucketCORS
s3:GetBucketVersioning
s3:PutBucketVersioning
s3:GetBucketRequestPayment
s3:PutBucketRequestPayment
s3:GetBucketLocation
s3:GetBucketPolicy
s3:DeleteBucketPolicy
s3:PutBucketPolicy
s3:GetBucketNotification
s3:PutBucketNotification
s3:GetBucketLogging
s3:PutBucketLogging
s3:GetBucketWebsite
s3:PutBucketWebsite
s3:DeleteBucketWebsite
s3:GetLifecycleConfiguration
s3:PutLifecycleConfiguration

You can delete objects by explicitly calling the DELETE Object API or configure its lifecycle (see Object Expiration) to enable Amazon S3 to remove them for you. If you want to block users or accounts from removing or deleting objects from your bucket you must deny them s3:DeleteObject, s3:DeleteObjectVersion and s3:PutLifecycleConfiguration actions.

Amazon S3 Policy Keys

Policy keys, conditions, let you restrict access to resources based on information other than just the API action being requested. They let you restrict access based on contextual information about the request, such as the IP address of the requester, the time and date of the request, etc. Conditions are constructed with key-value pairs, where the key specifies the condition. For more information about conditions and common AWS conditions, go to Condition in the AWS Identity and Access Management Using IAM guide.

Amazon S3 has its own set of conditions, in addition to the common AWS conditions. For example, you can restrict access based on values of general HTTP headers or Amazon S3-specific headers in the request.

For all conditions, you can specify a placeholder for any value of a key-value pair. When the policy is evaluated, the placeholder is replaced with information from the request. For example, you can specify a variable, such as ${aws:username}, as part of the resource name or condition key in order to specify permissions for a specific path. For more information, see Policy Variables in the AWS Identity and Access Management Using IAM guide.

This section lists the policy keys that you can use to restrict access to your AWS account's Amazon S3 resources .

Available Keys

AWS provides a set of common keys supported by all AWS products that adopt the access policy language. For a list of these keys, go to Available Keys in the AWS Identity and Access Management Using IAM guide.

Amazon S3 also has action-specific policy keys. They're grouped by resource type and applicable action in the following tables. Some policy keys are applicable to more than one resource type or action.

Important

IAM cannot evaluate a policy for validity within Amazon S3. If you specify an invalid key/action combination, IAM doesn't throw an exception when you upload the policy to IAM. Also, you will not receive an error message from Amazon S3. Amazon S3 can determine only that the policy doesn't apply because it cannot fulfill the conditions. However, if you use a policy condition in an unexpected way (for example, you use a string field as a numeric comparison), Amazon S3 will throw an exception on the request and access will be denied.

Unless otherwise noted, each key is for use with the access policy language's string conditions. For more information, go to Condition in the AWS Identity and Access Management Using IAM guide.

Object Keys in Amazon S3 Policies

The following list shows the keys related to objects that can be in Amazon S3 policies.

Action	Applicable Keys	Description
`s3:PutObject`	`s3:x-amz-acl`	The Amazon S3 canned ACL that is applied to the object. A canned ACL represents a predefined permission that can be applied to the object being PUT to Amazon S3. Valid values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` \| `log-delivery-write`. Example value: `public-read`
	`s3:x-amz-copy-source`	The header that specifies the name of the source bucket and key name of the source object, separated by a slash (/). Used when copying an object. Example value: `/bucketname/keyname`
	`s3:x-amz-grant-read, s3:x-amz-grant-write, s3:x-amz-grant-read-acp, s3:x-amz-grant-write-acp, s3:x-amz-grant-full-control`	These conditions relate to the ACL-specific request headers the action supports. You can add a condition in your bucket policy to deny or grant the action based on the presence of these headers headers with specific values. For more information about the API and the request headers, go to PUT Object. For an example policy that uses these condition keys, see Granting Cross-Account Permissions to Upload Objects While Ensuring the Bucket Owner Has Full Control .
	`s3:x-amz-server-side-encryption`	Allow the specific action only if `x-amz-server-side-encryption` header is present in the request and its value matches the specified condition. with Valid values: AES256 Example value: `AES256`
	`s3:x-amz-metadata-directive`	The header that specifies whether the metadata is copied from the source object or replaced with metadata provided in the request. If copied, the metadata, except for the version ID, remains unchanged. Otherwise, all original metadata is replaced by the metadata you specify. Used when copying an object. Valid values: `COPY` \| `REPLACE`. The default is `COPY`. Example value: `REPLACE`
`s3:PutObjectAcl`	`s3:x-amz-acl`	The Amazon S3 canned ACL that is applied to the object. A canned ACL represents a predefined permission that can be applied to the object being PUT to Amazon S3. Valid values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` \| `log-delivery-write`. Example value: `public-read`
`s3:PutObjectAcl`	`s3:x-amz-grant-read, s3:x-amz-grant-write, s3:x-amz-grant-read-acp, s3:x-amz-grant-write-acp, s3:x-amz-grant-full-control`	These conditions relate to the ACL-specific request headers the action supports. You can add a condition in your bucket policy to deny or grant the action based on the presence of these headers headers with specific values. For more information about the API and the request headers, go to PUT Object acl. For an example policy that uses these condition keys, see Granting Cross-Account Permissions to Upload Objects While Ensuring the Bucket Owner Has Full Control .
`s3:GetObjectVersion`	`s3:VersionId`	The version ID of the object being retrieved. Example value: `Upfdndhfd8438MNFDN93jdnJFkdmqnh893`
`s3:GetObjectVersionAcl`	`s3:VersionId`	The version ID of the object ACL being retrieved. Example value: `Upfdndhfd8438MNFDN93jdnJFkdmqnh893`
`s3:PutObjectVersionAcl`	`s3:VersionId`	The version ID of the object ACL being PUT. Example value: `Upfdndhfd8438MNFDN93jdnJFkdmqnh893`
	`s3:x-amz-acl`	The Amazon S3 canned ACL that is applied to the object. A canned ACL represents a predefined permission that can be applied to the object being PUT to Amazon S3. Valid values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` \| `log-delivery-write`. Example value: `public-read`
	`s3:x-amz-grant-read, s3:x-amz-grant-write, s3:x-amz-grant-read-acp, s3:x-amz-grant-write-acp, s3:x-amz-grant-full-control`	These conditions relate to the ACL-specific request headers the action supports. You can add a condition in your bucket policy to deny or grant the action based on the presence of these headers headers with specific values. For more information about the API and the request headers, go to PUT Object acl. For an example policy that uses these condition keys, see Granting Cross-Account Permissions to Upload Objects While Ensuring the Bucket Owner Has Full Control .
`s3:DeleteObjectVersion`	`s3:VersionId`	The version ID of the object being deleted. Example value: `Upfdndhfd8438MNFDN93jdnJFkdmqnh893`

Bucket Keys in Amazon S3 Policies

The following table shows the keys related to buckets that can be in Amazon S3 policies.

Action	Applicable Keys	Description
`s3:CreateBucket`	`s3:x-amz-acl`	The Amazon S3 canned ACL that is applied to the bucket. A canned ACL represents a predefined permission that can be applied to the bucket being created. Valid values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` \| `log-delivery-write`. Example value: `public-read`
	`s3:LocationConstraint`	Specifies the Region where the bucket will be created. Valid values are `us-west-1` (for Northern California) or `EU` (for Ireland). Do not specify a value for US Standard. Example value: `us-west-1`
	`s3:x-amz-grant-read, s3:x-amz-grant-write, s3:x-amz-grant-read-acp, s3:x-amz-grant-write-acp, s3:x-amz-grant-full-control`	These conditions relate to the ACL-specific request headers the action supports. You can add a condition in your bucket policy to deny or grant the action based on the presence of these headers headers with specific values. For more information about the API and the request headers, go to PUT Bucket. For an example policy that uses these condition keys, see Granting Cross-Account Permissions to Upload Objects While Ensuring the Bucket Owner Has Full Control .
`s3:ListBucket`	`s3:prefix`	Limits the response to objects that begin with the specified prefix. Use this to allow or deny access to objects that begin with the prefix. Example value: `home`
	`s3:delimiter`	The character you use to group objects. Example value: `/`
	`s3:max-keys`	The number of objects to return from the call. The maximum allowed value (and default) is 1000. For use with access policy language numeric conditions (for more information, see Numeric Conditions). Example value: `100`
`s3:ListBucketVersions`	`s3:prefix`	Header that lets you limit the response to include only keys that begin with the specified prefix. Example value: `home`
	`s3:delimiter`	The character you use to group objects. Example value: `/`
	`s3:max-keys`	The number of objects to return from the call. The maximum allowed value (and default) is 1000. For use with access policy language numeric conditions (for more information, see Numeric Conditions). Example value: `100`
`s3:PutBucketAcl`	`s3:x-amz-acl`	The Amazon S3 canned ACL that is applied to the bucket. A canned ACL represents a predefined permission that can be applied to the bucket being created. Valid values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` \| `log-delivery-write`. Example value: `public-read`
`s3:PutBucketAcl`	`s3:x-amz-grant-read, s3:x-amz-grant-write, s3:x-amz-grant-read-acp, s3:x-amz-grant-write-acp, s3:x-amz-grant-full-control`	These conditions relate to the ACL-specific request headers the action supports. You can add a condition in your bucket policy to deny or grant the action based on the presence of these headers headers with specific values. For more information about the API and the request headers, go to PUT Bucket acl. For an example policy that uses these condition keys, see Granting Cross-Account Permissions to Upload Objects While Ensuring the Bucket Owner Has Full Control .

Example Policies for Amazon S3

This section shows several simple IAM policies for controlling user access to Amazon S3.

Note

The following example policies will work if you test them programmatically; however, in order to use them with the Amazon S3 console, you will need to grant additional permissions that are required by the console. For information about using policies such as these with the Amazon S3 console, see An Example: Using IAM policies to control access to your bucket.

Example 1: Allow each user access to a folder in a bucket

In this example, you want two IAM users, Alice and Bob, to have access to your bucket, examplebucket, so they can add, update, and delete objects. However, you want to restrict each user’s access to a single folder in the bucket. You might create folders with names that match the user names.

examplebucket
   Alice/
   Bob/

To grant each user access only to his or her folder, you can write a policy for each user and attach it individually. For example, you can attach the following policy to user Alice to allow her specific Amazon S3 actions on the examplebucket/Alice folder.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:DeleteObject",
            "s3:DeleteObjectVersion"
         ],
         "Resource":"arn:aws:s3:::examplebucket/Alice/*"
      }
   ]
}

You then attach a similar policy to user Bob, identifying folder Bob in the Resource value.

Instead of attaching policies to individual users, though, you can write a single policy that uses a policy variable and attach the policy to a group. You will first need to create a group and add both Alice and Bob to the group. The following example policy allows a set of Amazon S3 actions in the examplebucket/${aws:username} folder. When the policy is evaluated, the policy variable ${aws:username} is replaced by the requester's user name. For example, if Alice sends a request to put an object, the action is allowed only if Alice is uploading the object to the examplebucket/Alice folder.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:DeleteObject",
            "s3:DeleteObjectVersion"
         ],
         "Resource":"arn:aws:s3:::examplebucket/${aws:username}/*"
      }
   ]
}

Note

When using policy variables you must explicitly specify version 2012-10-17 in the policy. The default version of the access policy language, 2008-10-17, does not support policy variables.

If you want to test the preceding policy on the Amazon S3 console, the console requires permission for additional Amazon S3 actions, as shown in the following policy. For information about how the console uses these permissions , see An Example: Using IAM policies to control access to your bucket.

{
 "Version":"2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGroupToSeeBucketListInTheConsole",
      "Action": [ "s3:ListAllMyBuckets", "s3:GetBucketLocation" ],
      "Effect": "Allow",
      "Resource": [ "arn:aws:s3:::*"  ]
    },
    {
      "Sid": "AllowRootLevelListingOfTheBucket",
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::examplebucket"],
      "Condition":{ 
            "StringEquals":{
                    "s3:prefix":[""], "s3:delimiter":["/"]
                           }
                 }
    },
    {
      "Sid": "AllowListBucketOfASpecificUserPrefix",
      "Action": ["s3:ListBucket"],
      "Effect": "Allow",
      "Resource": ["arn:aws:s3:::examplebucket"],
      "Condition":{  "StringLike":{"s3:prefix":["${aws:username}/*"] }
       }
    },
      {
     "Sid": "AllowUserSpecificActionsOnlyInTheSpecificUserPrefix",
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:DeleteObject",
            "s3:DeleteObjectVersion"
         ],
         "Resource":"arn:aws:s3:::examplebucket/${aws:username}/*"
      }
  ]
}

Note

In the 2012-10-17 version of the policy, policy variables start with $. This change in syntax can potentially create a conflict if your object key includes a $. For example, to include a object key my$file in a policy, you specify the $ character with ${$}, my${$}file.

Although IAM user names are friendly, human-readable identifiers, they are not required to be globally unique. For example, if user Bob leaves the organization and another Bob joins, then new Bob could access old Bob's information. Instead of using user names, you could create folders based on user IDs. Each user ID is unique. In this case, you will need to modify the preceding policy to use the ${aws:userid} policy variable.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:DeleteObject",
            "s3:DeleteObjectVersion"
         ],
         "Resource":"arn:aws:s3:::my_corporate_bucket/home/${aws:userid}/*"
      }
   ]
}

Example 2: Allow a group to have a shared folder in Amazon S3

Attaching the following policy to the group grants everybody in the group access to the following folder in Amazon S3: my_corporate_bucket/share/marketing. Group members are allowed to access only the specific Amazon S3 actions shown in the policy and only for objects in the specified folder.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:GetObjectVersion",
            "s3:DeleteObject",
            "s3:DeleteObjectVersion"
         ],
         "Resource":"arn:aws:s3:::my_corporate_bucket/share/marketing/*"
      }
   ]
}

Example 3: Allow all your users to read objects in a portion of the corporate bucket

In this example, we create a group called AllUsers, which contains all the IAM users that are owned by the AWS account. We then attach a policy that gives the group access to GetObject and GetObjectVersion, but only for objects in the my_corporate_bucket/readonly folder.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:GetObject",
            "s3:GetObjectVersion"
         ],
         "Resource":"arn:aws:s3:::my_corporate_bucket/readonly/*"
      }
   ]
}

Example 4: Allow a partner to drop files into a specific portion of the corporate bucket

In this example, we create a group called WidgetCo that represents a partner company. We create an IAM user for the specific person or application at the partner company that needs access, and then we put the user in the group.

We then attach a policy that gives the group PutObject access to the following folder in the corporate bucket: my_corporate_bucket/uploads/widgetco.

We want to prevent the WidgetCo group from doing anything else with the bucket, so we add a statement that explicitly denies permission to any Amazon S3 actions except PutObject on any Amazon S3 resource in the AWS account. This step is necessary only if there's a broad policy in use elsewhere in your AWS account that gives users wide access to Amazon S3 resources.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":"s3:PutObject",
         "Resource":"arn:aws:s3:::my_corporate_bucket/uploads/widgetco/*"
      },
      {
         "Effect":"Deny",
         "NotAction":"s3:PutObject",
         "Resource":"arn:aws:s3:::my_corporate_bucket/uploads/widgetco/*"
      },
      {
         "Effect":"Deny",
         "Action":"s3:*",
         "NotResource":"arn:aws:s3:::my_corporate_bucket/uploads/widgetco/*"
      }
   ]
}

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...