S3 Access Grants concepts - Amazon Simple Storage Service
How it works

S3 Access Grants concepts

S3 Access Grants introduces the following concepts for its simplified access scheme:

S3 Access Grants instances

An S3 Access Grants instance is a logical container for individual grants that define who has what level of access to what Amazon S3 data. You can have one S3 Access Grants instance per AWS Region per AWS account. You use this S3 Access Grants instance to control access to all buckets in the same account and AWS Region. If you want to use S3 Access Grants to grant access to user and group identities in your corporate directory, you must also associate your S3 Access Grants instance with an AWS Identity and Access Management (IAM) Identity Center instance.

Locations

A location defines which data your S3 Access Grants instance can grant access to. S3 Access Grants works by vending IAM credentials with access scoped to a particular S3 prefix, bucket, or object. You associate an S3 Access Grants location with an IAM role, from which these temporary sessions are created. The most common location configuration is a single location at s3:// for the entire S3 Access Grants instance, which can cover access to all S3 buckets in the account and AWS Region. You can also create multiple locations in your S3 Access Grants instance. For example, you can register a bucket as a location s3://DOC-EXAMPLE-BUCKET1 for grants that you want to limit to this bucket, and you can also register the default location s3://.

Grants

To narrow the scope of access within a location, you create individual grants. An individual grant in an S3 Access Grants instance allows a specific entity—an IAM principal, or a user or group in a corporate directory—access to an Amazon S3 prefix, bucket, or object. For each grant, you can define a different scope (a prefix, bucket, or object) and access level (READ, WRITE, or READWRITE). For example, you might have a grant that allows a particular corporate directory group, 01234567-89ab-cdef-0123-456789abcdef READ access to s3://DOC-EXAMPLE-BUCKET1/projects/items/*. This grant gives users in that group READ access to every object that has a key name with the prefix projects/items/ in the bucket named DOC-EXAMPLE-BUCKET1.

S3 Access Grants temporary credentials

An application can request just-in-time access credentials by calling a new S3 API operation, GetDataAccess, to request access to a single object, prefix, or bucket with a permission level of READ, WRITE, or READWRITE. The S3 Access Grants instance evaluates the GetDataAccess request against the grants that it has. If there is a matching grant, S3 Access Grants assumes the IAM role that's associated with the location of the matching grant. S3 Access Grants then scopes the permissions of the IAM session to precisely the S3 bucket, prefix, or object that's specified by the grant's scope. The expiration time of the temporary access credentials defaults to 1 hour, but you can set it to any value from 15 minutes to 36 hours.

How it works

In the following diagram, a default Amazon S3 location with the scope s3:// is registered with the IAM role s3ag-location-role. This IAM role has permissions to perform Amazon S3 actions within the account when its credentials are obtained through S3 Access Grants.

Within this location, two individual access grants are created for two IAM users. The IAM user Bob is granted both READ and WRITE access on the bob/ prefix in the DOC-BUCKET-EXAMPLE bucket. Another IAM role, Alice, is granted only READ access on the alice/ prefix in the DOC-BUCKET-EXAMPLE bucket. A grant, colored in blue, is defined for Bob to access the prefix bob/ in the DOC-BUCKET-EXAMPLE bucket. A grant, colored in green, is defined for Alice to access the prefix alice/ in the DOC-BUCKET-EXAMPLE bucket.

When it's time for Bob to READ data, the IAM role that's associated with the location that his grant is in calls the S3 Access Grants GetDataAccess API operation. If Bob tries to READ any S3 prefix or object that starts with s3://DOC-BUCKET-EXAMPLE/bob/*, the GetDataAccess request returns a set of temporary IAM session credentials with permission to s3://DOC-BUCKET-EXAMPLE/bob/*. Similarly, Bob can WRITE to any S3 prefix or object that starts with s3://DOC-BUCKET-EXAMPLE/bob/*, because the grant also allows that.

Similarly, Alice can READ anything that starts with s3://DOC-BUCKET-EXAMPLE/alice/. However, if she tries to WRITE anything to any bucket, prefix, or object in s3://, she will get an Access Denied (403 Forbidden) error, because there is no grant that gives her WRITE access to any data. In addition, if Alice requests any level of access (READ or WRITE) to data outside of s3://DOC-BUCKET-EXAMPLE/alice/, she will again receive an Access Denied error.

How S3 Access Grants works

This pattern scales to a high number of users and buckets and simplifies management of those permissions. Rather than editing potentially large S3 bucket policies every time you want to add or remove an individual user-prefix access relationship, you can add and remove individual, discrete grants.