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 locations3://
for grants that you want to limit to this bucket, and you can also register the default locationexample-s3-bucket1
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
, orREADWRITE
). For example, you might have a grant that allows a particular corporate directory group,01234567-89ab-cdef-0123-456789abcdef
READ
access tos3://
. This grant gives users in that groupexample-s3-bucket1
/projects/items/*READ
access to every object that has a key name with the prefixprojects/items/
in the bucket named
.example-s3-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
, orREADWRITE
. The S3 Access Grants instance evaluates theGetDataAccess
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 12 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.
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.