Register a location - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Register a location

After you create an Amazon S3 Access Grants instance in a Amazon Web Services 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 Amazon Web Services 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 Amazon 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:// Default-IAM-role

The default location, s3://, includes all buckets in the Amazon Web Services Region.
s3://DOC-EXAMPLE-BUCKET1/ IAM-role-For-bucket

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 Amazon Web Services 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 user input placeholders with your own information.

    Note

    • If you use server-side encryption with Amazon Key Management Service (Amazon KMS) keys to encrypt your data, the following example includes the necessary Amazon 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:Amazon Web Services 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:Amazon Web Services 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 Amazon Command Line Interface (Amazon CLI), the Amazon S3 REST API, or the Amazon 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

  1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

  2. In the left navigation pane, choose Access Grants.

  3. 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.

    1. 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.

    2. 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 and sts: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.

    3. To finish, choose Next or Register location.

  4. 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 Amazon CLI, see Installing the Amazon CLI in the Amazon 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 user input placeholders with your own information.

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 \
 --region us-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-cn: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 user input placeholders with your own information.

Note

If you use server-side encryption with Amazon Key Management Service (Amazon KMS) keys to encrypt your data, the following example adds the necessary Amazon 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: InstanceArn) in your IAM policy. When using following example policy, replace the user input placeholders with your own information.

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:Amazon Web Services 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:Amazon Web Services 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-scope s3:// \
 --iam-role-arn arn:aws-cn:iam::111122223333:role/accessGrantsTestRole

Response:

{"CreatedAt": "2023-05-31T18:23:48.107000+00:00",
    "AccessGrantsLocationId": "default",
    "AccessGrantsLocationArn": "arn:aws-cn:s3:us-east-2:111122223333:access-grants/default/location/default",
    "LocationScope": "s3://” 
    "IAMRoleArn": "arn:aws-cn:iam::111122223333:role/accessGrantsTestRole"
}
Example Register a custom location
aws s3control create-access-grants-location \
 --account-id 111122223333 \
 --location-scope s3://DOC-BUCKET-EXAMPLE/ \
 --iam-role-arn arn:aws-cn:iam::123456789012:role/accessGrantsTestRole

Response:

{"CreatedAt": "2023-05-31T18:23:48.107000+00:00",
    "AccessGrantsLocationId": "635f1139-1af2-4e43-8131-a4de006eb456",
    "AccessGrantsLocationArn": "arn:aws-cn:s3:us-east-2: 111122223333:access-grants/default/location/635f1139-1af2-4e43-8131-a4de006eb888",
    "LocationScope": "s3://DOC-BUCKET-EXAMPLE/",
    "IAMRoleArn": "arn:aws-cn: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 Amazon SDKs.

To use the following examples, replace the user input placeholders with your own information.

Java

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 user input placeholders with your own information.

Example Register a default location

Request:

public void createAccessGrantsLocation() {
CreateAccessGrantsLocationRequest createRequest = CreateAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.locationScope("s3://")
.iamRoleArn("arn:aws-cn:iam::123456789012:role/accessGrantsTestRole")
.build();
CreateAccessGrantsLocationResponse createResponse = s3Control.createAccessGrantsLocation(createRequest);
LOGGER.info("CreateAccessGrantsLocationResponse: " + createResponse);
}

Response:

CreateAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:11.027Z,
AccessGrantsLocationId=default,
AccessGrantsLocationArn=arn:aws-cn:s3:us-east-2:111122223333:access-grants/default/location/default,
LocationScope=s3://,
IAMRoleArn=arn:aws-cn:iam::111122223333:role/accessGrantsTestRole
)
Example Register a custom location

Request:

public void createAccessGrantsLocation() {
CreateAccessGrantsLocationRequest createRequest = CreateAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.locationScope("s3://DOC-BUCKET-EXAMPLE/")
.iamRoleArn("arn:aws-cn:iam::111122223333:role/accessGrantsTestRole")
.build();
CreateAccessGrantsLocationResponse createResponse = s3Control.createAccessGrantsLocation(createRequest);
LOGGER.info("CreateAccessGrantsLocationResponse: " + createResponse);
}

Response:

CreateAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:10.027Z,
AccessGrantsLocationId=18cfe6fb-eb5a-4ac5-aba9-8d79f04c2012,
AccessGrantsLocationArn=arn:aws-cn:s3:us-east-2:111122223333:access-grants/default/location/18cfe6fb-eb5a-4ac5-aba9-8d79f04c2666,
LocationScope= s3://test-bucket-access-grants-user123/,
IAMRoleArn=arn:aws-cn:iam::111122223333:role/accessGrantsTestRole
)
Topics