# Working with grants in S3 Access Grants An individual access *grant* in an S3 Access Grants instance allows a specific identity—an AWS Identity and Access Management (IAM) principal, or a user or group in a corporate directory—to get access within a location that is registered in your S3 Access Grants instance. A location maps buckets or prefixes to an IAM role. S3 Access Grants assumes this IAM role to vend temporary credentials to grantees. After you [register at least one location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html) in your S3 Access Grants instance, you can create an access grant. The grantee can be an 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 [associated with your S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-idc.html). For more information, see [S3 Access Grants and corporate directory identities](access-grants-directory-ids.md). To create a grant for a specific directory 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`. For more information about how to use IAM Identity Center to view user information, see [View user and group assignments](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-view-assignments.html) in the *AWS IAM Identity Center user guide*. You can grant access to a bucket, a prefix, or 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 your bucket that start with the `engineering/` prefix. **Topics** + [Create grants](access-grants-grant-create.md) + [View a grant](access-grants-grant-view.md) + [Delete a grant](access-grants-grant-delete.md) # Create grants An individual access *grant* in an S3 Access Grants instance allows a specific identity—an AWS Identity and Access Management (IAM) principal, or a user or group in a corporate directory—to get access within a location that is registered in your S3 Access Grants instance. A location maps buckets or prefixes to an IAM role. S3 Access Grants assumes this IAM role to vend temporary credentials to grantees. After you [register at least one location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html) in your S3 Access Grants instance, you can create an access grant. The grantee can be an 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 [associated with your S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-idc.html). For more information, see [S3 Access Grants and corporate directory identities](access-grants-directory-ids.md). To create a grant for a specific directory 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`. For more information about how to use IAM Identity Center to view user information, see [View user and group assignments](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-view-assignments.html) in the *AWS IAM Identity Center user guide*. You can grant access to a bucket, a prefix, or 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 your 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 of access to a subset of the location scope. If the registered location that you choose for the grant is the default S3 path (`s3://`), you must narrow the grant scope. You cannot create an access grant for the default location (`s3://`), which would give the grantee access to every bucket in an AWS Region. Instead, you must narrow the grant scope to 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 are creating an access grant where the registered location is a bucket, you can pass one of the following in the `Subprefix` field to narrow the grant scope: + A prefix within the bucket: `prefix*` + A prefix within a prefix: `prefixA/prefixB*` + An object: `/object-key-name` After you create the grant, the grant scope that's displayed 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. **Note** If you need to create an access grant that grants access to only one object, you must specify that the grant type is for an object. To do this in an API call or a CLI command, pass the `s3PrefixType` parameter with the value `Object`. In the Amazon S3 console, when you create the grant, after you select a location, under **Grant Scope**, select the **Grant scope is an object** checkbox. You cannot create a grant to a bucket if the bucket does not yet exist. However, you can create a grant to a prefix that does not yet exist. For the maximum number of grants that you can create in your S3 Access Grants instance, see [S3 Access Grants limitations](access-grants-limitations.md). You can create an access grant by using the Amazon S3 console, AWS CLI, the Amazon S3 REST API, and AWS SDKs. ## Using the S3 console **To create an access grant** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html#subprefix). If you're granting access only to an object, select **Grant scope is an object**. 1. 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. 1. To create the S3 Access Grants grant, choose **Next** or **Create grant**. 1. If **Next** or **Create grant** is disabled: **Cannot create grant** + You might need to [register a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html) first in your S3 Access Grants instance. + You might not have the `s3:CreateAccessGrant` permission to create an access grant. Contact your account administrator. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 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 `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: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://amzn-s3-demo-bucket/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-id default \ --access-grants-location-configuration S3SubPrefix="amzn-s3-demo-bucket/rafael/*" \ --permission READWRITE \ --grantee GranteeType=DIRECTORY_USER,GranteeIdentifier=83d43802-00b1-7054-db02-f1d683aacba5 \ ``` ## Using the REST API 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*: + [CreateAccessGrant](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrant.html) + [DeleteAccessGrant](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrant.html) + [GetAccessGrant](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrant.html) + [ListAccessGrants](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrants.html) ## Using the AWS SDKs This section provides examples of how to create an access grant by using the AWS 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: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:s3:us-east-2:444455556666:access-grants/default/grant/a1b2c3d4-5678-90ab-cdef-EXAMPLE33333, Grantee=Grantee( GranteeType=IAM, GranteeIdentifier=arn:aws:iam::111122223333:user/data-consumer-3 ), AccessGrantsLocationId=a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa, AccessGrantsLocationConfiguration=AccessGrantsLocationConfiguration( S3SubPrefix=prefixB* ), GrantScope=s3://amzn-s3-demo-bucket/prefixB, Permission=READ ) ``` ------ # View a grant You can view the details of an access grant in your Amazon S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console **To view the details of an access grant** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. Choose **View details** for the instance. 1. On the details page, choose the **Grants** tab. 1. In the **Grants** section, find the access grant that you want to view. To filter the list of grants, use the search box. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example commands, replace the `user input placeholders` with your own information. **Example – Get the details of an access grant** ``` aws s3control get-access-grant \ --account-id 111122223333 \ --access-grant-id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 ``` Response: ``` { "CreatedAt": "2023-05-31T18:41:34.663000+00:00", "AccessGrantId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "AccessGrantArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default/grant-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "Grantee": { "GranteeType": "IAM", "GranteeIdentifier": "arn:aws:iam::111122223333:user/data-consumer-3" }, "Permission": "READ", "AccessGrantsLocationId": "12a6710f-5af8-41f5-b035-0bc795bf1a2b", "AccessGrantsLocationConfiguration": { "S3SubPrefix": "prefixB*" }, "GrantScope": "s3://amzn-s3-demo-bucket/" } ``` **Example – List all of the access grants in an S3 Access Grants instance** You can optionally use the following parameters to restrict the results to an S3 prefix or AWS Identity and Access Management (IAM) identity: + **Subprefix** – `--grant-scope s3://bucket-name/prefix*` + **IAM identity** – `--grantee-type IAM` and `--grantee-identifier arn:aws:iam::123456789000:role/accessGrantsConsumerRole` ``` aws s3control list-access-grants \ --account-id 111122223333 ``` Response: ``` { "AccessGrantsList": [{"CreatedAt": "2023-06-14T17:54:46.542000+00:00", "AccessGrantId": "dd8dd089-b224-4d82-95f6-975b4185bbaa", "AccessGrantArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default/grant/dd8dd089-b224-4d82-95f6-975b4185bbaa", "Grantee": { "GranteeType": "IAM", "GranteeIdentifier": "arn:aws:iam::111122223333:user/data-consumer-3" }, "Permission": "READ", "AccessGrantsLocationId": "23514a34-ea2e-4ddf-b425-d0d4bfcarda1", "GrantScope": "s3://amzn-s3-demo-bucket/prefixA*" }, {"CreatedAt": "2023-06-24T17:54:46.542000+00:00", "AccessGrantId": "ee8ee089-b224-4d72-85f6-975b4185a1b2", "AccessGrantArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default/grant/ee8ee089-b224-4d72-85f6-975b4185a1b2", "Grantee": { "GranteeType": "IAM", "GranteeIdentifier": "arn:aws:iam::111122223333:user/data-consumer-9" }, "Permission": "READ", "AccessGrantsLocationId": "12414a34-ea2e-4ddf-b425-d0d4bfcacao0", "GrantScope": "s3://amzn-s3-demo-bucket/prefixB*" }, ] } ``` ## Using the REST API You can use Amazon S3 API operations to view the details of an access grant and list all access grants in an S3 Access Grants instance. For information about the REST API support for managing access grants, see the following sections in the *Amazon Simple Storage Service API Reference*: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrant.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrant.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrants.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrants.html) ## Using the AWS SDKs This section provides examples of how to get the details of an access grant by using the AWS SDKs. To use the following examples, replace the `user input placeholders` with your own information. ------ #### [ Java ] **Example – Get the details of an access grant** ``` public void getAccessGrant() { GetAccessGrantRequest getRequest = GetAccessGrantRequest.builder() .accountId("111122223333") .accessGrantId("a1b2c3d4-5678-90ab-cdef-EXAMPLE22222") .build(); GetAccessGrantResponse getResponse = s3Control.getAccessGrant(getRequest); LOGGER.info("GetAccessGrantResponse: " + getResponse); } ``` Response: ``` GetAccessGrantResponse( CreatedAt=2023-06-07T05:20:26.330Z, AccessGrantId=a1b2c3d4-5678-90ab-cdef-EXAMPLE22222, AccessGrantArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/grant-fd3a5086-42f7-4b34-9fad-472e2942c70e, Grantee=Grantee( GranteeType=IAM, GranteeIdentifier=arn:aws:iam::111122223333:user/data-consumer-3 ), Permission=READ, AccessGrantsLocationId=12a6710f-5af8-41f5-b035-0bc795bf1a2b, AccessGrantsLocationConfiguration=AccessGrantsLocationConfiguration( S3SubPrefix=prefixB* ), GrantScope=s3://amzn-s3-demo-bucket/ ) ``` **Example – List all of the access grants in an S3 Access Grants instance** You can optionally use these parameters to restrict the results to an S3 prefix or IAM identity: + **Scope** – `GrantScope=s3://bucket-name/prefix*` + **Grantee ** – `GranteeType=IAM` and `GranteeIdentifier= arn:aws:iam::111122223333:role/accessGrantsConsumerRole` ``` public void listAccessGrants() { ListAccessGrantsRequest listRequest = ListAccessGrantsRequest.builder() .accountId("111122223333") .build(); ListAccessGrantsResponse listResponse = s3Control.listAccessGrants(listRequest); LOGGER.info("ListAccessGrantsResponse: " + listResponse); } ``` Response: ``` ListAccessGrantsResponse( AccessGrantsList=[ ListAccessGrantEntry( CreatedAt=2023-06-14T17:54:46.540z, AccessGrantId=dd8dd089-b224-4d82-95f6-975b4185bbaa, AccessGrantArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/grant/dd8dd089-b224-4d82-95f6-975b4185bbaa, Grantee=Grantee( GranteeType=IAM, GranteeIdentifier= arn:aws:iam::111122223333:user/data-consumer-3 ), Permission=READ, AccessGrantsLocationId=23514a34-ea2e-4ddf-b425-d0d4bfcarda1, GrantScope=s3://amzn-s3-demo-bucket/prefixA ), ListAccessGrantEntry( CreatedAt=2023-06-24T17:54:46.540Z, AccessGrantId=ee8ee089-b224-4d72-85f6-975b4185a1b2, AccessGrantArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/grant/ee8ee089-b224-4d72-85f6-975b4185a1b2, Grantee=Grantee( GranteeType=IAM, GranteeIdentifier= arn:aws:iam::111122223333:user/data-consumer-9 ), Permission=READ, AccessGrantsLocationId=12414a34-ea2e-4ddf-b425-d0d4bfcacao0, GrantScope=s3://amzn-s3-demo-bucket/prefixB* ) ] ) ``` ------ # Delete a grant You can delete access grants from your Amazon S3 Access Grants instance. You can't undo an access grant deletion. After you delete an access grant, the grantee will no longer have access to your Amazon S3 data. You can delete an access grant by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. ## Using the S3 console **To delete an access grant** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Access Grants**. 1. On the **S3 Access Grants** page, choose the Region that contains the S3 Access Grants instance that you want to work with. 1. Choose **View details** for the instance. 1. On the details page, choose the **Grants** tab. 1. Search for the grant that you want to delete. When you locate the grant, choose the radio button next to it. 1. Choose **Delete**. A dialog box appears with a warning that your action can't be undone. Choose **Delete** again to delete the grant. ## Using the AWS CLI To install the AWS CLI, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. To use the following example command, replace the `user input placeholders` with your own information. **Example – Delete an access grant** ``` aws s3control delete-access-grant \ --account-id 111122223333 \ --access-grant-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 // No response body ``` ## Using the REST API For information about the Amazon S3 REST API support for managing access grants, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrant.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrant.html) in the *Amazon Simple Storage Service API Reference*. ## Using the AWS SDKs This section provides examples of how to delete an access grant by using the AWS SDKs. To use the following example, replace the `user input placeholders` with your own information. ------ #### [ Java ] **Example – Delete an access grant** ``` public void deleteAccessGrant() { DeleteAccessGrantRequest deleteRequest = DeleteAccessGrantRequest.builder() .accountId("111122223333") .accessGrantId("a1b2c3d4-5678-90ab-cdef-EXAMPLE11111") .build(); DeleteAccessGrantResponse deleteResponse = s3Control.deleteAccessGrant(deleteRequest); LOGGER.info("DeleteAccessGrantResponse: " + deleteResponse); } ``` Response: ``` DeleteAccessGrantResponse() ``` ------