Register a location
After you create an Amazon S3 Access Grants
instance in a AWS Region in your account, you can register an S3 location in that
instance. A location is an S3 resource that contains data that you want to grant access to.
You can register the default location, s3://
, which is all of your buckets in
the AWS Region, and then narrow the scope of access later, when you create individual access
grants. You can also register a specific bucket or a bucket and prefix as a location.
You must first register at least one location with your S3 Access Grants instance before you can create access grants. When you register a location, you must also specify the AWS Identity and Access Management (IAM) role that S3 Access Grants assumes to fulfill runtime requests for the location and scope the permissions down to the specific grant at runtime.
S3 URI | IAM role | Description |
---|---|---|
s3:// |
|
The default location, |
s3:// |
|
This location includes all objects in the specified bucket. |
Before you can register a location, make sure that you do the following:
-
Create one or more buckets that contain the data that you want to grant access to. These buckets must be located in the same AWS Region as your S3 Access Grants instance. For more information, see Creating a bucket.
To add a prefix to a bucket, see Creating object key names.
-
Create an IAM role and give the S3 Access Grants service principal access to this role in the resource policy file. To do so, you can create a JSON file that contains the following statements. To add the resource policy to your account, see Create and attach your first customer managed policy.
TestRolePolicy.json
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1234567891011", "Action": ["sts:AssumeRole", "sts:SetSourceIdentity", "sts:SetContext"], "Effect": "Allow", "Principal": {"Service":"access-grants.s3.amazonaws.com"} } ] }
-
Create an IAM policy to attach Amazon S3 permissions to the IAM role. See the following example
iam-policy.json
file and replace the
with your own information.user input placeholders
Note
-
If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following example includes the necessary AWS KMS permissions for the IAM role in the policy. If you do not use this feature, you can remove these permissions from your IAM policy.
-
You can restrict the IAM role to access S3 data only if the credentials are vended by S3 Access Grants. This example shows you how to add a
Condition
statement for a specific S3 Access Grants instance. To do this, replace the S3 Access Grants instance ARN in the condition statement with your S3 Access Grants instance ARN, which has the format:arn:aws:s3:
region
:accountId
:access-grants/default
iam-policy.json
{ "Version":"2012-10-17", "Statement": [ { "Sid": "ObjectLevelReadPermissions", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:GetObjectVersion", "s3:GetObjectAcl", "s3:GetObjectVersionAcl", "s3:ListMultipartUploadParts" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "
accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:region
:accountId
:access-grants/default"] } } }, { "Sid": "ObjectLevelWritePermissions", "Effect":"Allow", "Action":[ "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "s3:DeleteObject", "s3:DeleteObjectVersion", "s3:AbortMultipartUpload" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:AWS Region
:accountId
:access-grants/default"] } } }, { "Sid": "BucketLevelReadPermissions", "Effect":"Allow", "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:AWS Region
:accountId
:access-grants/default"] } } }, { "Sid": "KMSPermissions", "Effect":"Allow", "Action":[ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource":[ "*" ] } ] } -
You can register a location in your S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, or the AWS SDKs.
Before you can grant access to your S3 data with S3 Access Grants, you must have at least one registered location.
To register a location in your S3 Access Grants instance
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 S3 Access Grants instance for the first time, make sure that you have completed Step 1 - create an S3 Access Grants instance and navigated to Step 2 of the Set up Access Grants instance wizard. If you already have an S3 Access Grants instance, choose View details, and then from the Locations tab, choose Register location.
-
For the Location scope, choose Browse S3 or enter the S3 URI path to the location that you want to register. For S3 URI formats, see the location formats table. After you enter a URI, you can choose View to browse the location.
-
For the IAM role, choose one of the following:
-
Choose from existing IAM roles
Choose an IAM role from the dropdown list. After you choose a role, choose View to make sure that this role has the necessary permissions to manage the location that you're registering. Specifically, make sure that this role grants S3 Access Grants the permissions
sts:AssumeRole
andsts:SetSourceIdentity
. -
Enter IAM role ARN
Navigate to the IAM Console
. Copy the Amazon Resource Name (ARN) of the IAM role and paste it in this box.
-
-
To finish, choose Next or Register location.
-
-
Troubleshooting:
Cannot register location
-
The location might already be registered.
You might not have the
s3:CreateAccessGrantsLocation
permission to register locations. Contact your account administrator.
-
To install the AWS CLI, see Installing the AWS CLI in the AWS Command Line Interface User Guide.
You can register the default location, s3://
, or a custom location in
your S3 Access Grants instance. Make sure that you first create an IAM role with principal
access to the location, and then make sure that you grant S3 Access Grants permission to
assume this role.
To use the following example commands, replace the
with your own information.user input
placeholders
Example Create a resource policy
Create a policy that allows S3 Access Grants to assume the IAM role. To do so, you can create a JSON file that contains the following statements. To add the resource policy to your account, see Create and attach your first customer managed policy.
TestRolePolicy.json
{ "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1234567891011", "Action": ["sts:AssumeRole", "sts:SetSourceIdentity"], "Effect": "Allow", "Principal": {"Service":"access-grants.s3.amazonaws.com"} } ] }
Example Create the role
Run the following IAM command to create the role.
aws iam create-role --role-name
accessGrantsTestRole
\ --regionus-east-2
\ --assume-role-policy-document file://TestRolePolicy.json
Running the create-role
command returns the policy:
{ "Role": { "Path": "/", "RoleName": "accessGrantsTestRole", "RoleId": "AROASRDGX4WM4GH55GIDA", "Arn": "arn:aws:iam::
111122223333
:role/accessGrantsTestRole", "CreateDate": "2023-05-31T18:11:06+00:00", "AssumeRolePolicyDocument": { "Version": "2012-10-17", "Statement": [ { "Sid": "Stmt1685556427189", "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Effect": "Allow", "Principal": { "Service":"access-grants.s3.amazonaws.com" } } ] } } }
Create an IAM policy to attach Amazon S3 permissions to the IAM role. See the
following example iam-policy.json
file and replace the
with your
own information. user input placeholders
Note
If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following example adds the necessary AWS KMS permissions for the IAM role in the policy. If you do not use this feature, you can remove these permissions from your IAM policy.
To make sure that the IAM role can only be used to access data in S3 if the credentials
are vended out by S3 Access Grants, this example shows you how to add a
Condition
statement that specifies the S3 Access Grants instance
(s3:AccessGrantsInstance:
) in your IAM policy. When using following example policy, replace the InstanceArn
with your own information.user input placeholders
iam-policy.json
{ "Version":"2012-10-17", "Statement": [ { "Sid": "ObjectLevelReadPermissions", "Effect":"Allow", "Action":[ "s3:GetObject", "s3:GetObjectVersion", "s3:GetObjectAcl", "s3:GetObjectVersionAcl", "s3:ListMultipartUploadParts" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "
accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:region
:accountId
:access-grants/default"] } } }, { "Sid": "ObjectLevelWritePermissions", "Effect":"Allow", "Action":[ "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "s3:DeleteObject", "s3:DeleteObjectVersion", "s3:AbortMultipartUpload" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:AWS Region
:accountId
:access-grants/default"] } } }, { "Sid": "BucketLevelReadPermissions", "Effect":"Allow", "Action":[ "s3:ListBucket" ], "Resource":[ "arn:aws:s3:::*" ], "Condition":{ "StringEquals": { "aws:ResourceAccount": "accountId
" }, "ArnEquals": { "s3:AccessGrantsInstanceArn": ["arn:aws:s3:AWS Region
:accountId
:access-grants/default"] } } }, { "Sid": "KMSPermissions", "Effect":"Allow", "Action":[ "kms:Decrypt", "kms:GenerateDataKey" ], "Resource":[ "*" ] } ] }
Run the following command:
aws iam put-role-policy \ --role-name accessGrantsTestRole \ --policy-name accessGrantsTestRole \ --policy-document file://iam-policy.json
Example Register the default location
aws s3control create-access-grants-location \ --account-id
111122223333
\ --location-scopes3://
\ --iam-role-arn arn:aws:iam::111122223333
:role/accessGrantsTestRole
Response:
{"CreatedAt": "2023-05-31T18:23:48.107000+00:00", "AccessGrantsLocationId": "default", "AccessGrantsLocationArn": "arn:aws:s3:
us-east-2
:111122223333
:access-grants/default/location/default", "LocationScope": "s3://” "IAMRoleArn": "arn:aws:iam::111122223333
:role/accessGrantsTestRole" }
Example Register a custom location
aws s3control create-access-grants-location \ --account-id
111122223333
\ --location-scopes3://DOC-BUCKET-EXAMPLE/
\ --iam-role-arn arn:aws:iam::123456789012
:role/accessGrantsTestRole
Response:
{"CreatedAt": "2023-05-31T18:23:48.107000+00:00", "AccessGrantsLocationId": "635f1139-1af2-4e43-8131-a4de006eb456", "AccessGrantsLocationArn": "arn:aws:s3:
us-east-2
:111122223333
:access-grants/default/location/635f1139-1af2-4e43-8131-a4de006eb888", "LocationScope": "s3://DOC-BUCKET-EXAMPLE/", "IAMRoleArn": "arn:aws:iam::111122223333
:role/accessGrantsTestRole" }
For information about Amazon S3 REST API support for managing an S3 Access Grants instance, see the following sections in the Amazon Simple Storage Service API Reference:
This section provides examples of how to register locations by using the AWS SDKs.
To use the following examples, replace the
with your own information.user input
placeholders