Create grants - Amazon Simple Storage Service
Subprefix
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).

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 Amazon 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 Amazon 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 Amazon Command Line Interface (Amazon 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, Amazon CLI, the Amazon S3 REST API, and Amazon SDKs.

To create an access grant

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

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

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

    3. To create the S3 Access Grants grant, choose Next or Create grant.

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

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-id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 \
--access-grants-location-configuration S3SubPrefix=prefixB* \
--permission READ \
--grantee GranteeType=IAM,GranteeIdentifier=arn:aws-cn: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-cn:s3:us-east-2:111122223333:access-grants/default/grant/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Grantee": {
        "GranteeType": "IAM",
        "GranteeIdentifier": "arn:aws-cn: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 Amazon CLI or Amazon 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-id default \
--access-grants-location-configuration S3SubPrefix="DOC-EXAMPLE-BUCKET/rafael/*" \
--permission READWRITE \
--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 Amazon SDKs.

Java

To use the following example, replace the user input placeholders with your own information:

Note

If you are creating an access grant that grants access to only one object, include the required parameter .s3PrefixType(S3PrefixType.Object).

Example Create an access grant request
public void createAccessGrant() {
CreateAccessGrantRequest createRequest = CreateAccessGrantRequest.builder()
.accountId("111122223333")
.accessGrantsLocationId("a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa")
.permission("READ")
.accessGrantsLocationConfiguration(AccessGrantsLocationConfiguration.builder().s3SubPrefix("prefixB*").build())
.grantee(Grantee.builder().granteeType("IAM").granteeIdentifier("arn:aws-cn:iam::111122223333:user/data-consumer-3").build())
.build();
CreateAccessGrantResponse createResponse = s3Control.createAccessGrant(createRequest);
LOGGER.info("CreateAccessGrantResponse: " + createResponse);
}
Example Create an access grant response
CreateAccessGrantResponse(
CreatedAt=2023-06-07T05:20:26.330Z,
AccessGrantId=a1b2c3d4-5678-90ab-cdef-EXAMPLE33333,
AccessGrantArn=arn:aws-cn:s3:us-east-2:444455556666:access-grants/default/grant/a1b2c3d4-5678-90ab-cdef-EXAMPLE33333,
Grantee=Grantee(
GranteeType=IAM,
GranteeIdentifier=arn:aws-cn:iam::111122223333:user/data-consumer-3
),
AccessGrantsLocationId=a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa,
AccessGrantsLocationConfiguration=AccessGrantsLocationConfiguration(
S3SubPrefix=prefixB*
),
GrantScope=s3://DOC-BUCKET-EXAMPLE/prefixB,
Permission=READ
)
Topics