Module: AWS::S3::ACL

Defined in:
lib/aws/s3/acl.rb,
lib/aws/s3/response.rb

Overview

By default buckets are private. This means that only the owner has access rights to the bucket and its objects. Objects in that bucket inherit the permission of the bucket unless otherwise specified. When an object is private, the owner can generate a signed url that exposes the object to anyone who has that url. Alternatively, buckets and objects can be given other access levels. Several canned access levels are defined:

  • :private - Owner gets FULL_CONTROL. No one else has any access rights. This is the default.

  • :public_read - Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.

  • :public_read_write - Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to PUT objects into the bucket.

  • :authenticated_read - Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.

You can set a canned access level when you create a bucket or an object by using the :access option:

S3Object.store(
  'kiss.jpg', 
  data, 
  'marcel', 
  :access => :public_read
)

Since the image we created is publicly readable, we can access it directly from a browser by going to the corresponding bucket name and specifying the object’s key without a special authenticated url:

http://s3.amazonaws.com/marcel/kiss.jpg

Building custum access policies

For both buckets and objects, you can use the acl method to see its access control policy:

policy = S3Object.acl('kiss.jpg', 'marcel')
pp policy.grants
[#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
 #<AWS::S3::ACL::Grant READ to AllUsers Group>]

Policies are made up of one or more grants which grant a specific permission to some grantee. Here we see the default FULL_CONTROL grant to the owner of this object. There is also READ permission granted to the Allusers Group, which means anyone has read access for the object.

Say we wanted to grant access to anyone to read the access policy of this object. The current READ permission only grants them permission to read the object itself (for example, from a browser) but it does not allow them to read the access policy. For that we will need to grant the AllUsers group the READ_ACP permission.

First we’ll create a new grant object:

grant = ACL::Grant.new
# => #<AWS::S3::ACL::Grant (permission) to (grantee)>
grant.permission = 'READ_ACP'

Now we need to indicate who this grant is for. In other words, who the grantee is:

grantee = ACL::Grantee.new
# => #<AWS::S3::ACL::Grantee (xsi not set yet)>

There are three ways to specify a grantee: 1) by their internal amazon id, such as the one returned with an object’s Owner, 2) by their Amazon account email address or 3) by specifying a group. As of this writing you can not create custom groups, but Amazon does provide three already: AllUsers, Authenticated and LogDelivery. In this case we want to provide the grant to all users. This effectively means “anyone”.

grantee.group = 'AllUsers'

Now that our grantee is setup, we’ll associate it with the grant:

grant.grantee = grantee
grant
# => #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>

Are grant has all the information we need. Now that it’s ready, we’ll add it on to the object’s access control policy’s list of grants:

policy.grants << grant
pp policy.grants
[#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
 #<AWS::S3::ACL::Grant READ to AllUsers Group>,
 #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>]

Now that the policy has the new grant, we reuse the acl method to persist the policy change:

S3Object.acl('kiss.jpg', 'marcel', policy)

If we fetch the object’s policy again, we see that the grant has been added:

pp S3Object.acl('kiss.jpg', 'marcel').grants
[#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
 #<AWS::S3::ACL::Grant READ to AllUsers Group>,
 #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>]

If we were to access this object’s acl url from a browser: 

http://s3.amazonaws.com/marcel/kiss.jpg?acl

we would be shown its access control policy.

Pre-prepared grants

Alternatively, the ACL::Grant class defines a set of stock grant policies that you can fetch by name. In most cases, you can just use one of these pre-prepared grants rather than building grants by hand. Two of these stock policies are :public_read and :public_read_acp, which happen to be the two grants that we built by hand above. In this case we could have simply written:

policy.grants << ACL::Grant.grant(:public_read)
policy.grants << ACL::Grant.grant(:public_read_acp)
S3Object.acl('kiss.jpg', 'marcel', policy)

The full details can be found in ACL::Policy, ACL::Grant and ACL::Grantee.

Defined Under Namespace

Modules: Bucket, S3Object Classes: Grant, Grantee, OptionProcessor, Policy