Create grants
After you register at least one location in your Amazon S3 Access Grants instance, you can create an access grant. An access grant gives a grantee permission to access a registered location.
The grantee can be an AWS Identity and Access Management (IAM) user or role or a directory user or group. A
directory user is a user from your corporate directory or external identity source that you
added to the AWS IAM Identity Center
instance that's associated with your
S3 Access Grants instance. To create a grant for a specific user or group from IAM Identity Center, find
the GUID that IAM Identity Center uses to identify that user in IAM Identity Center, for example,
a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
.
You can grant access to a bucket, to a prefix, or to an object. A prefix in Amazon S3 is a string
of characters in the beginning of an object key name that is used to organize objects within
a bucket. This can be any string of allowed characters, for example, object key names in a
bucket that start with the engineering/
prefix.
Subprefix
When granting access to a registered location, you can use the Subprefix
field
to narrow the scope to a specific prefix within a bucket or to a specific object in a
bucket.
You cannot create an access grant for the default location s3://
, which would
give the grantee access to every bucket in a Region. If you choose the default
s3://
location as your grant location, you must narrow the grant scope
by using the Subprefix
field to specify one of the following:
-
A bucket —
s3://
bucket
/* -
A prefix within a bucket —
s3://
bucket
/prefix
* -
A prefix within a prefix —
s3://
bucket
/prefixA
/prefixB
* -
An object —
s3://
bucket
/object-key-name
If you create an access grant where the registered location is a bucket, you can pass
one of the following in the Subprefix
field:
-
A prefix within the bucket —
prefix
* -
A prefix within a prefix —
prefixA/
prefixB
* -
An object —
/
object-key-name
The grant scope shown in the Amazon S3 console or the GrantScope
that is returned in
the API or AWS Command Line Interface (AWS CLI) response is the result of concatenating the location path
with the Subprefix
. Make sure that this concatenated path maps correctly to
the S3 bucket, prefix, or object to which you want to grant access.
If you are creating an access grant that grants access to only one object, specify in the
API call or CLI command that the s3PrefixType
is
Object
.
Note
You cannot create a grant to a bucket if the bucket does not yet exist. However, you can create grant to a prefix that does not exist, yet.
You can create an access grant by using the Amazon S3 console, AWS CLI, the Amazon S3 REST API, and AWS SDKs.
To create an access grant
Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/
. -
In the left navigation pane, choose Access Grants.
-
On the S3 Access Grants page, choose the Region that contains the S3 Access Grants instance that you want to work with.
If you're using the S3 Access Grants instance for the first time, make sure that you have completed Step 2 - register a location and navigated to Step 3 of the Set up Access Grants instance wizard. If you already have an S3 Access Grants instance, choose View details, and then from the Grants tab, choose Create grant.
-
In the Grant scope section, select or enter a registered location.
If you selected the default
s3://
location, use the Subprefix box to can narrow the scope of the access grant. For more information, see Subprefix. If you're granting access only to an object, select Grant scope is an object. -
Under Permissions and access, select the Permission level, either Read, Write, or both.
Then choose the Grantee type. If you have added your corporate directory to IAM Identity Center and associated this IAM Identity Center instance with your S3 Access Grants instance, you can choose Directory identity from IAM Identity Center. If you choose this option, get the ID of the user or group from IAM Identity Center and enter it in this section.
If the Grantee type is an IAM user or role, choose IAM principal. Under IAM principal type, choose User or Role. Then, under IAM principal user, either choose from the list or enter the identity's ID.
-
To create the S3 Access Grants grant, choose Next or Create grant.
-
-
If Next or Create grant is disabled:
Cannot create grant
-
You might need to register a location first in your S3 Access Grants instance.
-
You might not have the
s3:CreateAccessGrant
permission to create an access grant. Contact your account administrator.
-
To install the AWS CLI, see Installing the AWS CLI in the AWS Command Line Interface User Guide.
The following examples show how to create an access grant request for an IAM principal and how to create an access grant request for a corporate directory user or group.
To use the following example commands, replace the
with your own information.user input
placeholders
Note
If you're creating an access grant that grants access to only one object,
include the required parameter --s3-prefix-type Object
.
Example Create an access grant request for an IAM principal
aws s3control create-access-grant \ --account-id
111122223333
\ --access-grants-location-ida1b2c3d4-5678-90ab-cdef-EXAMPLE22222
\ --access-grants-location-configurationS3SubPrefix=prefixB*
\ --permissionREAD
\ --grantee GranteeType=IAM
,GranteeIdentifier=arn:aws:iam::123456789012
:user
/data-consumer-3
Example Create an access grant response
{"CreatedAt": "2023-05-31T18:41:34.663000+00:00", "AccessGrantId": "
a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
", "AccessGrantArn": "arn:aws:s3:us-east-2
:111122223333
:access-grants/default/grant/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
", "Grantee": { "GranteeType": "IAM", "GranteeIdentifier": "arn:aws:iam::111122223333
:user/data-consumer-3" }, "AccessGrantsLocationId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222
", "AccessGrantsLocationConfiguration": { "S3SubPrefix": "prefixB*" }, "GrantScope": "s3://DOC-BUCKET-EXAMPLE/prefix*", "Permission": "READ" }
Create an access grant request for a directory user or group
To create an access grant request for a directory user or group, you must first get the GUID for the directory user or group by running one of the following commands.
Example Get a GUID for a directory user or group
You can find the GUID of an IAM Identity Center user through the IAM Identity Center console or by using the AWS CLI or AWS SDKs. The following command lists the users in he specified IAM Identity Center instance, with their names and identifiers.
aws identitystore list-users --identity-store-id
d-1a2b3c4d1234
This command lists the groups in the specified IAM Identity Center instance.
aws identitystore list-groups --identity-store-id
d-1a2b3c4d1234
Example Create an access grant for a directory user or group
This command is similar to creating a grant for IAM users or roles, except
the grantee type is DIRECTORY_USER
or DIRECTORY_GROUP
,
and the grantee identifier is the GUID for the directory user or group.
aws s3control create-access-grant \ --account-id
123456789012
\ --access-grants-location-iddefault
\ --access-grants-location-configurationS3SubPrefix="DOC-EXAMPLE-BUCKET/rafael/*
" \ --permissionREADWRITE
\ --grantee GranteeType=DIRECTORY_USER
,GranteeIdentifier=83d43802-00b1-7054-db02-f1d683aacba5
\
For information about the Amazon S3 REST API support for managing access grants, see the following sections in the Amazon Simple Storage Service API Reference:
This section provides examples of how to create an access grant by using the AWS SDKs.