# Managing access with S3 Access Grants
To adhere to the principle of least privilege, you define granular access to your Amazon S3 data based on applications, personas, groups, or organizational units. You can use various approaches to achieve granular access to your data in Amazon S3, depending on the scale and complexity of the access patterns.
The simplest approach for managing access to small-to-medium numbers of datasets in Amazon S3 by AWS Identity and Access Management (IAM) principals is to define [IAM permission policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/user-policies.html) and [S3 bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-policies.html). This strategy works, so long as the necessary policies fit within the policy size limits of S3 bucket policies (20 KB) and IAM policies (5 KB), and within the [number of IAM principals allowed per account](https://docs.aws.amazon.com/general/latest/gr/iam-service.html).
As your number of datasets and use cases scales, you might require more policy space. An approach that offers significantly more space for policy statements is to use [S3 Access Points](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-points.html) as additional endpoints for S3 buckets, because each access point can have its own policy. You can define quite granular access control patterns, because you can have thousands of access points per AWS Region per account, with a policy up to 20 KB in size for each access point. Although S3 Access Points increases the amount of policy space available, it requires a mechanism for clients to discover the right access point for the right dataset.
A third approach is to implement an [IAM session broker](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_federated-users.html) pattern, in which you implement access-decision logic and dynamically generate short-term IAM session credentials for each access session. While the IAM session broker approach supports arbitrarily dynamic permissions patterns and scales effectively, you must build the access-pattern logic.
Instead of using these approaches, you can use S3 Access Grants to manage access to your Amazon S3 data. S3 Access Grants provides a simplified model for defining access permissions to data in Amazon S3 by prefix, bucket, or object. In addition, you can use S3 Access Grants to grant access to both IAM principals and directly to users or groups from your corporate directory.
You commonly define permissions to data in Amazon S3 by mapping users and groups to datasets. You can use S3 Access Grants to define direct access mappings of S3 prefixes to users and roles within Amazon S3 buckets and objects. With the simplified access scheme in S3 Access Grants, you can grant read-only, write-only, or read-write access on a per-S3-prefix basis to both IAM principals and directly to users or groups from a corporate directory. With these S3 Access Grants capabilities, applications can request data from Amazon S3 on behalf of the application's current authenticated user.
When you integrate S3 Access Grants with the [trusted identity propagation](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html) feature of AWS IAM Identity Center, your applications can make requests to AWS services (including S3 Access Grants) directly on behalf of an authenticated corporate directory user. Your applications no longer need to first map the user to an IAM principal. Furthermore, because end-user identities are propagated all the way to Amazon S3, auditing which user accessed which S3 object is simplified. You no longer need to reconstruct the relationship between different users and IAM sessions. When you're using S3 Access Grants with IAM Identity Center trusted identity propagation, each [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html) data event for Amazon S3 contains a direct reference to the end user on whose behalf the data was accessed.
[Trusted identity propagation](https://docs.aws.amazon.com//singlesignon/latest/userguide/trustedidentitypropagation-overview.html) is an AWS IAM Identity Center feature that administrators of connected AWS services can use to grant and audit access to service data. Access to this data is based on user attributes such as group associations. Setting up trusted identity propagation requires collaboration between the administrators of connected AWS services and the IAM Identity Center administrators. For more information, see [Prerequisites and considerations](https://docs.aws.amazon.com//singlesignon/latest/userguide/trustedidentitypropagation-overall-prerequisites.html).
For more information about S3 Access Grants, see the following topics.
**Topics**
+ [
# S3 Access Grants concepts
](access-grants-concepts.md)
+ [
# S3 Access Grants and corporate directory identities
](access-grants-directory-ids.md)
+ [
# Getting started with S3 Access Grants
](access-grants-get-started.md)
+ [
# Working with S3 Access Grants instances
](access-grants-instance.md)
+ [
# Working with S3 Access Grants locations
](access-grants-location.md)
+ [
# Working with grants in S3 Access Grants
](access-grants-grant.md)
+ [
# Getting S3 data using access grants
](access-grants-data.md)
+ [
# S3 Access Grants cross-account access
](access-grants-cross-accounts.md)
+ [
# Managing tags for S3 Access Grants
](access-grants-tagging.md)
+ [
# S3 Access Grants limitations
](access-grants-limitations.md)
+ [
# S3 Access Grants integrations
](access-grants-integrations.md)
# S3 Access Grants concepts
**S3 Access Grants workflow**
The S3 Access Grants workflow is:
1. Create an S3 Access Grants instance. See [Working with S3 Access Grants instances](access-grants-instance.md).
1. Within your S3 Access Grants instance, register locations in your Amazon S3 data, and map these locations to AWS Identity and Access Management (IAM) roles. See [Register a location](access-grants-location-register.md).
1. Create grants for grantees, which give grantees access to your S3 resources. See [Working with grants in S3 Access Grants](access-grants-grant.md).
1. The grantee requests temporary credentials from S3 Access Grants. See [Request access to Amazon S3 data through S3 Access Grants](access-grants-credentials.md).
1. The grantee accesses the S3 data using those temporary credentials. See [Accessing S3 data using credentials vended by S3 Access Grants](access-grants-get-data.md).
For more information, see [Getting started with S3 Access Grants](access-grants-get-started.md).
**S3 Access Grants instances**
An *S3 Access Grants instance* is a logical container for individual *grants*. When you create an S3 Access Grants instance, you must specify an AWS Region. Each AWS Region in your AWS account can have one S3 Access Grants instance. For more information, see [Working with S3 Access Grants instances](access-grants-instance.md).
If you want to use S3 Access Grants to grant access to user and group identities from your corporate directory, you must also associate your S3 Access Grants instance with an AWS IAM Identity Center instance. For more information, see [S3 Access Grants and corporate directory identities](access-grants-directory-ids.md).
A newly created S3 Access Grants instance is empty. You must register a location in the instance, which can be the S3 default path (`s3://`), a bucket, or a prefix within a bucket. After you register at least one location, you can create access grants that give access to data in this registered location.
**Locations**
An S3 Access Grants *location* maps buckets or prefixes to an AWS Identity and Access Management (IAM) role. S3 Access Grants assumes this IAM role to vend temporary credentials to the grantee that's accessing that particular location. You must first register at least one location in your S3 Access Grants instance before you can create an access grant.
We recommend that you register the default location (`s3://`) and map it to an IAM role. The location at the default S3 path (`s3://`) covers access to all of your S3 buckets in the AWS Region of your account. When you create an access grant, you can narrow the grant scope to a bucket, a prefix, or an object within the default location.
More complex access-management use cases might require you to register more than the default location. Some examples of such use cases are:
+ Suppose that the *amzn-s3-demo-bucket* is a registered location in your S3 Access Grants instance with an IAM role mapped to it, but this IAM role is denied access to a particular prefix within the bucket. In this case, you can register the prefix that the IAM role does not have access to as a separate location and map that location to a different IAM role with the necessary access.
+ Suppose that you want to create grants that restrict access to only the users within a virtual private cloud (VPC) endpoint. In this case, you can register a location for a bucket in which the IAM role restricts access to the VPC endpoint. Later, when a grantee asks S3 Access Grants for credentials, S3 Access Grants assumes the location’s IAM role to vend the temporary credentials. This credential will deny access to the specific bucket unless the caller is within the VPC endpoint. This deny permission is applied in addition to the regular READ, WRITE, or READWRITE permission specified in the grant.
If your use case requires you to register multiple locations in your S3 Access Grants instance, you can register any of the following:
+ The default S3 location (`s3://`)
+ A bucket (for example, *amzn-s3-demo-bucket*) or multiple buckets
+ A bucket and a prefix (for example, `amzn-s3-demo-bucket/prefix*`) or multiple prefixes
For the maximum number of locations that you can register in your S3 Access Grants instance, see [S3 Access Grants limitations](access-grants-limitations.md). For more information about registering an S3 Access Grants location, see [Register a location](access-grants-location-register.md).
After you register the first location in your S3 Access Grants instance, your instance still does not have any individual access grants in it. So, no access has been granted yet to any of your S3 data. You can now create access grants to give access. For more information about creating grants, see [Working with grants in S3 Access Grants](access-grants-grant.md).
**Grants**
An individual *grant* in an S3 Access Grants instance allows a specific identity—an 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.
When you create a grant, you don't have to grant access to the entire registered location. You can narrow the grant's scope of access within a location. If the registered location is the default S3 path (`s3://`), you are required to narrow the scope of the grant to a bucket, a prefix within a bucket, or a specific object. If the registered location of the grant is a bucket or a prefix, then you can give access to the entire bucket or prefix, or you can optionally narrow the scope of the grant to a prefix, subprefix, or an object.
In the grant, you also set the access level of the grant to READ, WRITE, or READWRITE. Suppose you have a grant that gives the corporate directory group `01234567-89ab-cdef-0123-456789abcdef` READ access to the bucket `s3://amzn-s3-demo-bucket/projects/items/*`. Users in this group can have READ access to every object that has an object key name which starts with the prefix `projects/items/` in the bucket named *amzn-s3-demo-bucket*.
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). For more information about creating grants, see [Create grants](access-grants-grant-create.md).
**S3 Access Grants temporary credentials**
After you create a grant, an authorized application that utilizes the identity specified in the grant can request *just-in-time access credentials*. To do this, the application calls the [GetDataAccess](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html) S3 API operation. Grantees can use this API operation to request access to the S3 data you have shared with them.
The S3 Access Grants instance evaluates the `GetDataAccess` request against the grants that it has. If there is a matching grant for the requestor, S3 Access Grants assumes the IAM role that's associated with the registered location of the matching grant. S3 Access Grants scopes the permissions of the temporary credentials to access only the S3 bucket, prefix, or object that's specified by the grant's scope.
The expiration time of the temporary access credentials defaults to 1 hour, but you can set it to any value from 15 minutes to 12 hours. See the maximum duration session in the [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API reference.
## How it works
In the following diagram, a default Amazon S3 location with the scope `s3://` is registered with the IAM role `s3ag-location-role`. This IAM role has permissions to perform Amazon S3 actions within the account when its credentials are obtained through S3 Access Grants.
Within this location, two individual access grants are created for two IAM users. The IAM user Bob is granted both `READ` and `WRITE` access on the `bob/` prefix in the `DOC-BUCKET-EXAMPLE` bucket. Another IAM role, Alice, is granted only `READ` access on the `alice/` prefix in the `DOC-BUCKET-EXAMPLE` bucket. A grant, colored in blue, is defined for Bob to access the prefix `bob/` in the `DOC-BUCKET-EXAMPLE` bucket. A grant, colored in green, is defined for Alice to access the prefix `alice/` in the `DOC-BUCKET-EXAMPLE` bucket.
When it's time for Bob to `READ` data, the IAM role that's associated with the location that his grant is in calls the S3 Access Grants [GetDataAccess](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html) API operation. If Bob tries to `READ` any S3 prefix or object that starts with `s3://DOC-BUCKET-EXAMPLE/bob/*`, the `GetDataAccess` request returns a set of temporary IAM session credentials with permission to `s3://DOC-BUCKET-EXAMPLE/bob/*`. Similarly, Bob can `WRITE` to any S3 prefix or object that starts with `s3://DOC-BUCKET-EXAMPLE/bob/*`, because the grant also allows that.
Similarly, Alice can `READ` anything that starts with `s3://DOC-BUCKET-EXAMPLE/alice/`. However, if she tries to `WRITE` anything to any bucket, prefix, or object in `s3://`, she will get an Access Denied (403 Forbidden) error, because there is no grant that gives her `WRITE` access to any data. In addition, if Alice requests any level of access (`READ` or `WRITE`) to data outside of `s3://DOC-BUCKET-EXAMPLE/alice/`, she will again receive an Access Denied error.
![\[How S3 Access Grants works\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/s3ag-how-it-works.png)
This pattern scales to a high number of users and buckets and simplifies management of those permissions. Rather than editing potentially large S3 bucket policies every time you want to add or remove an individual user-prefix access relationship, you can add and remove individual, discrete grants.
# S3 Access Grants and corporate directory identities
You can use Amazon S3 Access Grants to grant access to AWS Identity and Access Management (IAM) principals (users or roles), both in the same AWS account and in others. However, in many cases, the entity accessing the data is an end user from your corporate directory. Instead of granting access to IAM principals, you can use S3 Access Grants to grant access directly to your corporate users and groups. With S3 Access Grants, you no longer need to map your corporate identities to intermediate IAM principals in order to access your S3 data through your corporate applications.
This new functionality—support for using end-user identities access to data—is provided by associating your S3 Access Grants instance with an AWS IAM Identity Center instance. IAM Identity Center supports standards-based identity providers and is the hub in AWS for any services or features, including S3 Access Grants, that support end-user identities. IAM Identity Center provides authentication support for corporate identities through its trusted identity propagation feature. For more information, see [Trusted identity propagation across applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html).
To get started with workforce identity support in S3 Access Grants, as a prerequisite, you start in IAM Identity Center by configuring identity provisioning between your corporate identity provider and IAM Identity Center. IAM Identity Center supports corporate identity providers such as Okta, Microsoft Entra ID (formerly Azure Active Directory), or any other external identity provider (IdP) that supports the System for Cross-domain Identity Management (SCIM) protocol. When you connect IAM Identity Center to your IdP and enable automatic provisioning, the users and groups from your IdP are synchronized into the identity store in IAM Identity Center. After this step, IAM Identity Center has its own view of your users and groups, so that you can refer to them by using other AWS services and features, such as S3 Access Grants. For more information about configuring IAM Identity Center automatic provisioning, see [Automatic provisioning](https://docs.aws.amazon.com/singlesignon/latest/userguide/provision-automatically.html) in the *AWS IAM Identity Center User Guide*.
IAM Identity Center is integrated with AWS Organizations so that you can centrally manage permissions across multiple AWS accounts without configuring each of your accounts manually. In a typical organization, your identity administrator configures one IAM Identity Center instance for the entire organization, as a single point of identity synchronization. This IAM Identity Center instance typically runs in a dedicated AWS account in your organization. In this common configuration, you can refer to user and group identities in S3 Access Grants from any AWS account in the organization.
However, if your AWS Organizations administrator hasn't yet configured a central IAM Identity Center instance, you can create a local one in the same account and AWS Region as your S3 Access Grants instance. If you have an IAM Identity Center instance configured in a different AWS Region, you can also [replicate](https://docs.aws.amazon.com/singlesignon/latest/userguide/replicate-to-additional-region.html) this instance to the same AWS Region as your S3 Access Grants instance. Such a configuration is more common for proof-of-concept or local development use cases. In all cases, the IAM Identity Center instance must be in the same AWS Region as the S3 Access Grants instance to which it will be associated.
In the following diagram of an IAM Identity Center configuration with an external IdP, the IdP is configured with SCIM to synchronize the identity store from the IdP to the identity store in IAM Identity Center.
![\[IAM Identity Center integration with an external identity store through automatic provisioning.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/s3ag-identity-store.png)
To use your corporate directory identities with S3 Access Grants, do the following:
+ Set up [Automatic provisioning](https://docs.aws.amazon.com/singlesignon/latest/userguide/provision-automatically.html) in IAM Identity Center to synchronize user and group information from your IdP into IAM Identity Center.
+ Configure your external identity source within IAM Identity Center as a trusted token issuer. For more information, see [Trusted identity propagation across applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html) in the *AWS IAM Identity Center User Guide*.
+ Associate your S3 Access Grants instance with your IAM Identity Center instance. You can do this when you [create your S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance.html). If you've already created your S3 Access Grants instance, see [Associate or disassociate your IAM Identity Center instance](access-grants-instance-idc.md).
## How directory identities can access S3 data
Suppose that you have corporate directory users who need to access your S3 data through a corporate application, for example, a document-viewer application, that is integrated with your external IdP (for example, Okta) to authenticate users. Authentication of the user in these applications is typically done through redirects in the user's web browser. Because users in the directory are not IAM principals, your application needs IAM credentials with which it can call the S3 Access Grants `GetDataAccess` API operation to [get access credentials to S3 data](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-credentials.html) on the users' behalf. Unlike IAM users and roles who get credentials themselves, your application needs a way to represent a directory user, who isn't mapped to an IAM role, so that the user can get data access through S3 Access Grants.
This transition, from authenticated directory user to an IAM caller that can make requests to S3 Access Grants on behalf of the directory user, is done by the application through the trusted token issuer feature of IAM Identity Center. The application, after authenticating the directory user, has an identity token from the IdP (for example, Okta) that represents the directory user according to Okta. The trusted token issuer configuration in IAM Identity Center enables the application to exchange this Okta token (the Okta tenant is configured as the "trusted issuer") for a different identity token from IAM Identity Center that will securely represent the directory user within AWS services. The data application will then assume an IAM role, providing the directory user's token from IAM Identity Center as additional context. The application can use the resulting IAM session to call S3 Access Grants. The token represents both the identity of the application (the IAM principal itself) as well as the directory user's identity.
The main step of this transition is the token exchange. The application performs this token exchange by calling the `CreateTokenWithIAM` API operation in IAM Identity Center. Of course, that too is an AWS API call and requires an IAM principal to sign it. The IAM principal that makes this request is typically an IAM role that's associated with the application. For example, if the application runs on Amazon EC2, the `CreateTokenWithIAM` request is typically performed by the IAM role that's associated with the EC2 instance on which the application runs. The result of a successful `CreateTokenWithIAM` call is a new identity token, which will be recognized within AWS services.
The next step, before the application can call `GetDataAccess` on the directory user's behalf, is for the application to obtain an IAM session that includes the directory user's identity. The application does this with an AWS Security Token Service (AWS STS) `AssumeRole` request that also includes the IAM Identity Center token for the directory user as additional identity context. This additional context is what enables IAM Identity Center to propagate the directory user's identity to the next step. The IAM role that the application assumes is the role that will need IAM permissions to call the `GetDataAccess` operation.
Having assumed the identity bearer IAM role with the IAM Identity Center token for the directory user as additional context, the application now has everything it needs to make a signed request to `GetDataAccess` on behalf of the authenticated directory user.
Token propagation is based on the following steps:
**Create an IAM Identity Center application**
First, create a new application in IAM Identity Center. This application will use a template that allows IAM Identity Center to identify which type of application settings that you can use. The command to create the application requires you to provide the IAM Identity Center instance Amazon Resource Name (ARN), an application name, and the application provider ARN. The application provider is the SAML or OAuth application provider that the application will use to make calls to IAM Identity Center.
To use the following example command, replace the `user input placeholders` with your own information:
```
aws sso-admin create-application \
--instance-arn "arn:aws:sso:::instance/ssoins-ssoins-1234567890abcdef" \
--application-provider-arn "arn:aws:sso::aws:applicationProvider/custom" \
--name MyDataApplication
```
Response:
```
{
"ApplicationArn": "arn:aws:sso::123456789012:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d"
}
```
**Create a trusted token issuer**
Now that you have your IAM Identity Center application, the next step is to configure a trusted token issuer that will be used to exchange your `IdToken` values from your IdP with IAM Identity Center tokens. In this step you need to provide the following items:
+ The identity provider issuer URL
+ The trusted token issuer name
+ The claim attribute path
+ The identity store attribute path
+ The JSON Web Key Set (JWKS) retrieval option
The claim attribute path is the identity provider attribute that will be used to map to the identity store attribute. Normally, the claim attribute path is the email address of the user, but you can use other attributes to perform the mapping.
Create a file called `oidc-configuration.json` with the following information. To use this file, replace the `user input placeholders` with your own information.
```
{
"OidcJwtConfiguration":
{
"IssuerUrl": "https://login.microsoftonline.com/a1b2c3d4-abcd-1234-b7d5-b154440ac123/v2.0",
"ClaimAttributePath": "preferred_username",
"IdentityStoreAttributePath": "userName",
"JwksRetrievalOption": "OPEN_ID_DISCOVERY"
}
}
```
To create the trusted token issuer, run the following command. To use this example command, replace the `user input placeholders` with your own information.
```
aws sso-admin create-trusted-token-issuer \
--instance-arn "arn:aws:sso:::instance/ssoins-1234567890abcdef" \
--name MyEntraIDTrustedIssuer \
--trusted-token-issuer-type OIDC_JWT \
--trusted-token-issuer-configuration file://./oidc-configuration.json
```
Response
```
{
"TrustedTokenIssuerArn": "arn:aws:sso::123456789012:trustedTokenIssuer/ssoins-1234567890abcdef/tti-43b4a822-1234-1234-1234-a1b2c3d41234"
}
```
**Connect the IAM Identity Center application with the trusted token issuer**
The trusted token issuer requires a few more configuration settings to work. Set the audience that the trusted token issuer will trust. The audience is the value inside the `IdToken` that's identified by the key and can be found in the identity provider settings. For example:
```
1234973b-abcd-1234-abcd-345c5a9c1234
```
Create a file named `grant.json` that contains the following content. To use this file, change the audience to match your identity provider settings and provide the trusted token issuer ARN that was returned by the previous command.
```
{
"JwtBearer":
{
"AuthorizedTokenIssuers":
[
{
"TrustedTokenIssuerArn": "arn:aws:sso::123456789012:trustedTokenIssuer/ssoins-1234567890abcdef/tti-43b4a822-1234-1234-1234-a1b2c3d41234",
"AuthorizedAudiences":
[
"1234973b-abcd-1234-abcd-345c5a9c1234"
]
}
]
}
}
```
Run the following example command. To use this command, replace the `user input placeholders` with your own information.
```
aws sso-admin put-application-grant \
--application-arn "arn:aws:sso::123456789012:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d" \
--grant-type "urn:ietf:params:oauth:grant-type:jwt-bearer" \
--grant file://./grant.json \
```
This command sets the trusted token issuer with configuration settings to trust the audience in the `grant.json` file and link this audience with the application created in the first step for exchanging tokens of the type `jwt-bearer`. The string `urn:ietf:params:oauth:grant-type:jwt-bearer` is not an arbitrary string. It is a registered namespace in OAuth JSON Web Token (JWT) assertion profiles. You can find more information about this namespace in [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523).
Next, use the following command to set up which scopes the trusted token issuer will include when exchanging `IdToken` values from your identity provider. For S3 Access Grants, the value for the `--scope` parameter is `s3:access_grants:read_write`.
```
aws sso-admin put-application-access-scope \
--application-arn "arn:aws:sso::111122223333:application/ssoins-ssoins-111122223333abcdef/apl-abcd1234a1b2c3d" \
--scope "s3:access_grants:read_write"
```
The last step is to attach a resource policy to the IAM Identity Center application. This policy will allow your application IAM role to make requests to the API operation `sso-oauth:CreateTokenWithIAM` and receive the `IdToken` values from IAM Identity Center.
Create a file named `authentication-method.json` that contains the following content. Replace `123456789012` with your account ID.
```
{
"Iam":
{
"ActorPolicy":
{
"Version": "2012-10-17" , TCX5-2025-waiver;,
"Statement":
[
{
"Effect": "Allow",
"Principal":
{
"AWS": "arn:aws:iam::123456789012:role/webapp"
},
"Action": "sso-oauth:CreateTokenWithIAM",
"Resource": "*"
}
]
}
}
}
```
To attach the policy to the IAM Identity Center application, run the following command:
```
aws sso-admin put-application-authentication-method \
--application-arn "arn:aws:sso::123456789012:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d" \
--authentication-method-type IAM \
--authentication-method file://./authentication-method.json
```
This completes the configuration settings for using S3 Access Grants with directory users through a web application. You can test this setup directly in the application or you can call the `CreateTokenWithIAM` API operation by using the following command from an allowed IAM role in the IAM Identity Center application policy:
```
aws sso-oidc create-token-with-iam \
--client-id "arn:aws:sso::123456789012:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d" \
--grant-type urn:ietf:params:oauth:grant-type:jwt-bearer \
--assertion IdToken
```
The response will be similar to this:
```
{
"accessToken": "",
"tokenType": "Bearer",
"expiresIn": 3600,
"refreshToken": "",
"idToken": "",
"issuedTokenType": "urn:ietf:params:oauth:token-type:refresh_token",
"scope": [
"sts:identity_context",
"s3:access_grants:read_write",
"openid",
"aws"
]
}
```
If you decode the `IdToken` value that is encoded with base64, you can see the key-value pairs in JSON format. The key `sts:identity_context` contains the value that your application needs to send in the `sts:AssumeRole` request to include the identity information of the directory user. Here is an example of the `IdToken` decoded:
```
{
"aws:identity_store_id": "d-996773e796",
"sts:identity_context": "AQoJb3JpZ2luX2VjEOTtl;",
"sub": "83d43802-00b1-7054-db02-f1d683aacba5",
"aws:instance_account": "123456789012",
"iss": "https://identitycenter.amazonaws.com/ssoins-1234567890abcdef",
"sts:audit_context": "AQoJb3JpZ2luX2VjEOT==",
"aws:identity_store_arn": "arn:aws:identitystore::232642235904:identitystore/d-996773e796",
"aud": "abcd12344U0gi7n4Yyp0-WV1LWNlbnRyYWwtMQ",
"aws:instance_arn": "arn:aws:sso:::instance/ssoins-6987d7fb04cf7a51",
"aws:credential_id": "EXAMPLEHI5glPh40y9TpApJn8...",
"act": {
"sub": "arn:aws:sso::232642235904:trustedTokenIssuer/ssoins-6987d7fb04cf7a51/43b4a822-1020-7053-3631-cb2d3e28d10e"
},
"auth_time": "2023-11-01T20:24:28Z",
"exp": 1698873868,
"iat": 1698870268
}
```
You can get the value from `sts:identity_context` and pass this information in an `sts:AssumeRole` call. The following is a CLI example of the syntax. The role to be assumed is a temporary role with permissions to invoke `s3:GetDataAccess`.
```
aws sts assume-role \
--role-arn "arn:aws:iam::123456789012:role/temp-role" \
--role-session-name "TempDirectoryUserRole" \
--provided-contexts ProviderArn="arn:aws:iam::aws:contextProvider/IdentityCenter",ContextAssertion="value from sts:identity_context"
```
You can now use the credentials received from this call to invoke the `s3:GetDataAccess` API operation and receive the final credentials with access to your S3 resources.
# Getting started with S3 Access Grants
Amazon S3 Access Grants is an Amazon S3 feature that provides a scalable access control solution for your S3 data. S3 Access Grants is an S3 credential vendor, meaning that you register with S3 Access Grants your list of grants and at what level. Thereafter, when users or clients need access to your S3 data, they first ask S3 Access Grants for credentials. If there is a corresponding grant that authorizes access, S3 Access Grants vends temporary, least-privilege access credentials. The users or clients can then use S3 Access Grants vended credentials to access your S3 data. With that in mind, if your S3 data requirements mandate a complex or large permission configuration, you can use S3 Access Grants to scale S3 data permissions for users, groups, roles, and applications.
For most use cases, you can manage access control for your S3 data by using AWS Identity and Access Management (IAM) with bucket policies or IAM identity-based policies.
However, if you have complex S3 access control requirements, such as the following, you could benefit greatly from using S3 Access Grants:
+ You are running into the bucket policy size limit of 20 KB.
+ You grant human identities, for example, Microsoft Entra ID (formerly Azure Active Directory), Okta, or Ping users and groups, access to S3 data for analytics and big data.
+ You must provide cross-account access without making frequent updates to IAM policies.
+ Your data is unstructured and object-level rather than structured, in row and column format.
The S3 Access Grants workflow is as follows:
| Steps | Description |
| --- | --- |
| 1 | [Create an S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance.html) To get started, initiate an S3 Access Grants instance that will contain your individual access grants. |
| 2 | [Register a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html) Second, register an S3 data location (such as the default, `s3://`) and then specify a default IAM role that S3 Access Grants assumes when providing access to the S3 data location. You can also add custom locations to specific buckets or prefixes and map those to custom IAM roles. |
| 3 | [Create grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html) Create individual permission grants. Specify in these permission grants the registered S3 location, the scope of data access within the location, the identity of the grantee, and their access level (`READ`, `WRITE`, or `READWRITE`). |
| 4 | [Request access to S3 data](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-credentials.html) When users, applications, and AWS services want to access S3 data, they first make an access request. S3 Access Grants determines if the request should be authorized. If there is a corresponding grant that authorizes access, S3 Access Grants uses the registered location's IAM role that's associated with that grant to vend temporary credentials back to the requester. |
| 5 | [Access S3 data](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-get-data.html) Applications use the temporary credentials vended by S3 Access Grants to access S3 data. |
# Working with S3 Access Grants instances
To get started with using AmazonS3 Access Grants, you first create an S3 Access Grants instance. You can create only one S3 Access Grants instance per AWS Region per account. The S3 Access Grants instance serves as the container for your S3 Access Grants resources, which include registered locations and grants.
With S3 Access Grants, you can create permission grants to your S3 data for AWS Identity and Access Management (IAM) users and roles. If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance. After you've done so, you can create access grants for your corporate users and groups. If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later.
**Topics**
+ [
# Create an S3 Access Grants instance
](access-grants-instance-create.md)
+ [
# Get the details of an S3 Access Grants instance
](access-grants-instance-view.md)
+ [
# List your S3 Access Grants instances
](access-grants-instance-list.md)
+ [
# Associate or disassociate your IAM Identity Center instance
](access-grants-instance-idc.md)
+ [
# Delete an S3 Access Grants instance
](access-grants-instance-delete.md)
# Create an S3 Access Grants instance
To get started with using AmazonS3 Access Grants, you first create an S3 Access Grants instance. You can create only one S3 Access Grants instance per AWS Region per account. The S3 Access Grants instance serves as the container for your S3 Access Grants resources, which include registered locations and grants.
With S3 Access Grants, you can create permission grants to your S3 data for AWS Identity and Access Management (IAM) users and roles. If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance. After you've done so, you can create access grants for your corporate users and groups. If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later.
You can create an S3 Access Grants instance by using the Amazon S3 console, the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and AWS SDKs.
## Using the S3 console
Before you can grant access to your S3 data with S3 Access Grants, you must first create an S3 Access Grants instance in the same AWS Region as your S3 data.
**Prerequisites**
If you want to grant access to your S3 data by using identities from your corporate directory, [add your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center. If you're not yet ready to do so, you can associate your S3 Access Grants instance with an IAM Identity Center instance later.
**To create an S3 Access Grants instance**
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 navigation bar, choose the name of the currently displayed AWS Region. Next, choose the Region that you want to switch to.
1. In the left navigation pane, choose **Access Grants**.
1. On the **S3 Access Grants** page, choose **Create S3 Access Grants instance**.
1. In **Step 1** of the **Set up Access Grants instance** wizard, verify that you want to create the instance in the current AWS Region. Make sure that this is the same AWS Region where your S3 data is located. You can create one S3 Access Grants instance per AWS Region per account.
1. (Optional) If you've [added your corporate identity directory](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) to AWS IAM Identity Center, you can associate this IAM Identity Center instance of your corporate directory with your S3 Access Grants instance.
To do so, select **Add IAM Identity Center instance in *region***. Then enter the IAM Identity Center instance Amazon Resource Name (ARN).
If you haven't yet added your corporate directory to IAM Identity Center, you can associate your S3 Access Grants instance with an IAM Identity Center instance later.
1. To create the S3 Access Grants instance, choose **Next**. To register a location, see [Step 2 - register a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance.html).
1. If **Next** or **Create S3 Access Grants instance** is disabled:
**Cannot create instance**
+ You might already have an S3 Access Grants instance in the same AWS Region. In the left navigation pane, choose **Access Grants**. On the **S3 Access Grants** page, scroll down to the **S3 Access Grants instance in your account** section o determine if an instance already exists.
+ You might not have the `s3:CreateAccessGrantsInstance` permission which is required to create an S3 Access Grants instance. Contact your account administrator. For additional permissions that are required if you are associating an IAM Identity Center instance, with your S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html) .
## 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 Create an S3 Access Grants instance**
```
aws s3control create-access-grants-instance \
--account-id 111122223333 \
--region us-east-2
```
Response:
```
{
"CreatedAt": "2023-05-31T17:54:07.893000+00:00",
"AccessGrantsInstanceId": "default",
"AccessGrantsInstanceArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
}
```
## Using the REST API
You can use the Amazon S3 REST API to create an S3 Access Grants instance. For information on the REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsInstance.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceResourcePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceResourcePolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html)
## Using the AWS SDKs
This section provides an example of how to create an S3 Access Grants instance by using the AWS SDKs.
------
#### [ Java ]
This example creates the S3 Access Grants instance, which serves as a container for your individual access grants. You can have one S3 Access Grants instance per AWS Region in your account. The response includes the instance ID `default` and an Amazon Resource Name (ARN) that's generated for your S3 Access Grants instance.
**Example Create an S3 Access Grants instance request**
```
public void createAccessGrantsInstance() {
CreateAccessGrantsInstanceRequest createRequest = CreateAccessGrantsInstanceRequest.builder().accountId("111122223333").build();
CreateAccessGrantsInstanceResponse createResponse = s3Control.createAccessGrantsInstance(createRequest);LOGGER.info("CreateAccessGrantsInstanceResponse: " + createResponse);
}
```
Response:
```
CreateAccessGrantsInstanceResponse(
CreatedAt=2023-06-07T01:46:20.507Z,
AccessGrantsInstanceId=default,
AccessGrantsInstanceArn=arn:aws:s3:us-east-2:111122223333:access-grants/default)
```
------
# Get the details of an S3 Access Grants instance
You can get the details of your Amazon S3 Access Grants instance in a particular AWS Region. You can get the details of your 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 get the details of an S3 Access Grants instance**
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. The **S3 Access Grants** page lists your S3 Access Grants instances and any cross-account instances that have been shared with your account. To view the details of an instance, choose **View details**.
## 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 – Get the details of an S3 Access Grants instance**
```
aws s3control get-access-grants-instance \
--account-id 111122223333 \
--region us-east-2
```
Response:
```
{
"AccessGrantsInstanceArn": "arn:aws:s3:us-east-2: 111122223333:access-grants/default",
"AccessGrantsInstanceId": "default",
"CreatedAt": "2023-05-31T17:54:07.893000+00:00"
}
```
## Using the REST API
For information about the Amazon S3 REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstance.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceForPrefix.html)
## Using the AWS SDKs
This section provides examples of how to get the details of an S3 Access Grants instance by using the AWS SDKs.
To use the following examples, replace the `user input placeholders` with your own information.
------
#### [ Java ]
**Example – Get an S3 Access Grants instance**
```
public void getAccessGrantsInstance() {
GetAccessGrantsInstanceRequest getRequest = GetAccessGrantsInstanceRequest.builder()
.accountId("111122223333")
.build();
GetAccessGrantsInstanceResponse getResponse = s3Control.getAccessGrantsInstance(getRequest);
LOGGER.info("GetAccessGrantsInstanceResponse: " + getResponse);
}
```
Response:
```
GetAccessGrantsInstanceResponse(
AccessGrantsInstanceArn=arn:aws:s3:us-east-2: 111122223333:access-grants/default,
CreatedAt=2023-06-07T01:46:20.507Z)
```
------
# List your S3 Access Grants instances
You can list your S3 Access Grants instances, including the instances that have been shared with you through AWS Resource Access Manager (AWS RAM).
You can list your S3 Access Grants instances 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 list your S3 Access Grants instances**
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. The **S3 Access Grants** page lists your S3 Access Grants instances and any cross-account instances that have been shared with your account. To view the details of an instance, choose **View details**.
## 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 – List all S3 Access Grants instances for an account**
This action lists the S3 Access Grants instances for an account. You can only have one S3 Access Grants instance per AWS Region. This action also lists other cross-account S3 Access Grants instances that your account has access to.
```
aws s3control list-access-grants-instances \
--account-id 111122223333 \
--region us-east-2
```
Response:
```
{
"AccessGrantsInstanceArn": "arn:aws:s3:us-east-2: 111122223333:access-grants/default",
"AccessGrantsInstanceId": "default",
"CreatedAt": "2023-05-31T17:54:07.893000+00:00"
}
```
## Using the REST API
For information about the Amazon S3 REST API support for managing an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsInstances.html)
## Using the AWS SDKs
This section provides examples of how to get the details of an S3 Access Grants instance by using the AWS SDKs.
To use the following examples, replace the `user input placeholders` with your own information.
------
#### [ Java ]
**Example – List all S3 Access Grants instances for an account**
This action lists the S3 Access Grants instances for an account. You can only have one S3 Access Grants instance per Region. This action can also list other cross-account S3 Access Grants instances that your account has access to.
```
public void listAccessGrantsInstances() {
ListAccessGrantsInstancesRequest listRequest = ListAccessGrantsInstancesRequest.builder()
.accountId("111122223333")
.build();
ListAccessGrantsInstancesResponse listResponse = s3Control.listAccessGrantsInstances(listRequest);
LOGGER.info("ListAccessGrantsInstancesResponse: " + listResponse);
}
```
Response:
```
ListAccessGrantsInstancesResponse(
AccessGrantsInstancesList=[
ListAccessGrantsInstanceEntry(
AccessGrantsInstanceId=default,
AccessGrantsInstanceArn=arn:aws:s3:us-east-2:111122223333:access-grants/default,
CreatedAt=2023-06-07T04:28:11.728Z
)
]
)
```
------
# Associate or disassociate your IAM Identity Center instance
In Amazon S3 Access Grants, you can associate the AWS IAM Identity Center instance of your corporate identity directory with an S3 Access Grants instance. After you do so, you can create access grants for your corporate directory users and groups, in addition to AWS Identity and Access Management (IAM) users and roles.
If you no longer want to create access grants for your corporate directory users and groups, you can disassociate your IAM Identity Center instance from your S3 Access Grants instance.
You can associate or disassociate an IAM Identity Center 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
Before you associate your IAM Identity Center instance with your S3 Access Grants instance, you must add your corporate identity directory to IAM Identity Center. For more information, see [S3 Access Grants and corporate directory identities](access-grants-directory-ids.md).
**To associate an IAM Identity Center instance with an S3 Access Grants instance**
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, in the **IAM Identity Center** section, choose to either **Add** an IAM Identity Center instance or **Deregister** an already associated IAM Identity Center instance.
## 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 – Associate an IAM Identity Center instance with an S3 Access Grants instance**
```
aws s3control associate-access-grants-identity-center \
--account-id 111122223333 \
--identity-center-arn arn:aws:sso:::instance/ssoins-1234a567bb89012c \
--profile access-grants-profile \
--region eu-central-1
// No response body
```
**Example – Disassociate an IAM Identity Center instance from an S3 Access Grants instance**
```
aws s3control dissociate-access-grants-identity-center \
--account-id 111122223333 \
--profile access-grants-profile \
--region eu-central-1
// No response body
```
## Using the REST API
For information about the Amazon S3 REST API support for managing the association between an IAM Identity Center instance and an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_AssociateAccessGrantsIdentityCenter.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DissociateAccessGrantsIdentityCenter.html)
# Delete an S3 Access Grants instance
You can delete an Amazon S3 Access Grants instance from an AWS Region in your account. However, before you can delete an S3 Access Grants instance, you must first do the following:
+ Delete all resources within the S3 Access Grants instance, including all grants and locations. For more information, see [Delete a grant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant-delete.html) and [Delete a location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant-location.html).
+ If you've associated an AWS IAM Identity Center instance with your S3 Access Grants instance, you must disassociate the IAM Identity Center instance. For more information, see [Associate or disassociate your IAM Identity Center instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-idc.html).
**Important**
If you delete an S3 Access Grants instance, the deletion is permanent and can't be undone. All grantees that were given access through the grants in this S3 Access Grants instance will lose access to your S3 data.
You can delete an 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 delete an S3 Access Grants instance**
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 instance details page, choose **Delete instance** in the upper-right corner.
1. In the dialog box that appears, choose **Delete**. This action can't be undone.
## 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.
**Note**
Before you can delete an S3 Access Grants instance, you must first delete all grants and locations created within the S3 Access Grants instance. If you have associated an IAM Identity Center center instance with your S3 Access Grants instance, you must disassociate it first.
**Example – Delete an S3 Access Grants instance**
```
aws s3control delete-access-grants-instance \
--account-id 111122223333 \
--profile access-grants-profile \
--region us-east-2 \
--endpoint-url https://s3-control.us-east-2.amazonaws.com \
// No response body
```
## Using the REST API
For information about the Amazon S3 REST API support for deleting an S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstance.html) in the *Amazon Simple Storage Service API Reference*.
## Using the AWS SDKs
This section provides examples of how to delete an S3 Access Grants instance by using the AWS SDKs.
To use the following example, replace the `user input placeholders` with your own information.
------
#### [ Java ]
**Note**
Before you can delete an S3 Access Grants instance, you must first delete all grants and locations created within the S3 Access Grants instance. If you have associated an IAM Identity Center center instance with your S3 Access Grants instance, you must disassociate it first.
**Example – Delete an S3 Access Grants instance**
```
public void deleteAccessGrantsInstance() {
DeleteAccessGrantsInstanceRequest deleteRequest = DeleteAccessGrantsInstanceRequest.builder()
.accountId("111122223333")
.build();
DeleteAccessGrantsInstanceResponse deleteResponse = s3Control.deleteAccessGrantsInstance(deleteRequest);
LOGGER.info("DeleteAccessGrantsInstanceResponse: " + deleteResponse);
}
```
------
# Working with S3 Access Grants locations
After you [create an Amazon S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-create.html) in an AWS Region in your account, you register an S3 location in that instance. An S3 Access Grants location maps the default S3 location (`s3://`), a bucket, or a prefix to an AWS Identity and Access Management (IAM) role. S3 Access Grants assumes this IAM role to vend temporary credentials to the grantee that is accessing that particular location. You must first register at least one location in your S3 Access Grants instance before you can create an access grant.
You can register a location, view a location's details, edit a location, and delete a location.
**Note**
After you register the first location in your S3 Access Grants instance, your instance still does not have any individual access grants in it. To create an access grant, see [Create grants](access-grants-grant-create.md).
**Topics**
+ [
# Register a location
](access-grants-location-register.md)
+ [
# View the details of a registered location
](access-grants-location-view.md)
+ [
# Update a registered location
](access-grants-location-edit.md)
+ [
# Delete a registered location
](access-grants-location-delete.md)
# Register a location
After you [create an Amazon S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-create.html) in an AWS Region in your account, you register an S3 location in that instance. An S3 Access Grants location maps the default S3 location (`s3://`), a bucket, or a prefix to an AWS Identity and Access Management (IAM) role. S3 Access Grants assumes this IAM role to vend temporary credentials to the grantee that is accessing that particular location. You must first register at least one location in your S3 Access Grants instance before you can create an access grant.
**Recommended use case**
We recommend that you register the default location (`s3://`) and map it to an IAM role. The location at the default S3 path (`s3://`) covers access to all of your S3 buckets in that AWS Region of your account. When you create an access grant, you can narrow the grant scope to a bucket, a prefix, or an object within the default location.
**Complex access-management use cases**
More complex access-management use cases might require you to register more than the default location. Some examples of such use cases are:
+ Suppose that the *amzn-s3-demo-bucket* is a registered location in your S3 Access Grants instance with an IAM role mapped to it, but this IAM role is denied access to a particular prefix within the bucket. In this case, you can register the prefix that the IAM role does not have access to as a separate location and map that location to a different IAM role with the necessary access.
+ Suppose that you want to create grants that restrict access to only the users within a virtual private cloud (VPC) endpoint. In this case, you can register a location for a bucket in which the IAM role restricts access to the VPC endpoint. Later, when a grantee asks S3 Access Grants for credentials, S3 Access Grants assumes the location’s IAM role to vend the temporary credentials. This credential will deny access to the specific bucket unless the caller is within the VPC endpoint. This deny permission is applied in addition to the regular READ, WRITE, or READWRITE permission specified in the grant.
When you register a location, you must also specify the IAM role that S3 Access Grants assumes to vend temporary credentials and to scope the permissions for a specific grant.
If your use case requires you to register multiple locations in your S3 Access Grants instance, you can register any of the following:
| S3 URI | IAM role | Description |
| --- | --- | --- |
| s3:// | Default-IAM-role | The default location, `s3://`, includes all buckets in the AWS Region. |
| s3://amzn-s3-demo-bucket1/ | IAM-role-For-bucket | This location includes all objects in the specified bucket. |
| s3://amzn-s3-demo-bucket1/prefix-name | IAM-role-For-prefix | This location includes all objects in the bucket with an object key name that starts with this prefix. |
Before you can register a specific bucket or prefix, 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html).
Adding a prefix is an optional step. Prefixes are strings at the beginning of an object key name. You can use them to organize objects in your bucket as well as for access management. To add a prefix to a bucket, see [Creating object key names](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).
+ Create an IAM role that has permission to access your S3 data in the AWS Region. For more information, see [Creating IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html) in the *AWS IAM Identity Center user guide*.
+ In the IAM role trust policy, give the S3 Access Grants service (`access-grants.s3.amazonaws.com`) principal access to the IAM role that you created. To do so, you can create a JSON file that contains the following statements. To add the trust policy to your account, see [Create a role using custom trust policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html).
*TestRolePolicy.json*
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "TestRolePolicy",
"Effect": "Allow",
"Principal": {
"Service": "access-grants.s3.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:SetSourceIdentity"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333",
"aws:SourceArn": "arn:aws:s3::111122223333:access-grants/default"
}
}
}
]
}
```
------
Alternatively, for an IAM Identity Center use case, use the following policy which includes a second statement:
+ Create an IAM policy to attach Amazon S3 permissions to the IAM role that you created. 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 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 use this `Condition`, 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"]
}
}
},
//Optionally add the following section if you use SSE-KMS encryption
{
"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.
**Note**
After you register the first location in your S3 Access Grants instance, your instance still does not have any individual access grants in it. To create an access grant, see [Create grants](access-grants-grant-create.md).
## Using the S3 console
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 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 S3 Access Grants instance for the first time, make sure that you have completed [Step 1 - create an S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-create.html) 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](#location-types) table. After you enter a URI, you can choose **View** to browse the location.
1. 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](https://console.aws.amazon.com/iam/). Copy the Amazon Resource Name (ARN) of the IAM role and paste it in this box.
1. To finish, choose **Next** or **Register location**.
1. 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.
## 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*.
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](https://docs.aws.amazon.com//IAM/latest/UserGuide/tutorial_managed-policies.html).
*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: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"
}
}
]
}
}
}
```
**Example**
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.
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: 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": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::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": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::access-grants/default"]
}
}
},
{
"Sid": "BucketLevelReadPermissions",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::*"
],
"Condition": {
"StringEquals": { "aws:ResourceAccount": "111122223333" },
"ArnEquals": {
"s3:AccessGrantsInstanceArn": ["arn:aws:s3:us-east-1::access-grants/default"]
}
}
},
{
"Sid": "KMSPermissions",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": [
"*"
],
"Condition": {
"StringEquals": {
"kms:ViaService": "s3.us-east-1.amazonaws.com"
}
}
}
]
}
```
**Example**
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: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-scope s3://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"
}
```
## Using the REST API
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*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateAccessGrantsLocation.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html)
## Using the AWS SDKs
This section provides examples of how to register locations by using the AWS 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: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:s3:us-east-2:111122223333:access-grants/default/location/default,
LocationScope=s3://,
IAMRoleArn=arn:aws: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: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:s3:us-east-2:111122223333:access-grants/default/location/18cfe6fb-eb5a-4ac5-aba9-8d79f04c2666,
LocationScope= s3://test-bucket-access-grants-user123/,
IAMRoleArn=arn:aws:iam::111122223333:role/accessGrantsTestRole
)
```
------
# View the details of a registered location
You can get the details of a location that's registered in your 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 locations registered in your S3 Access Grants instance**
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 for the instance, choose the **Locations** tab.
1. Find the registered location that you want to view. To filter the list of registered locations, 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 command, replace the `user input placeholders` with your own information.
**Example – Get the details of a registered location**
```
aws s3control get-access-grants-location \
--account-id 111122223333 \
--access-grants-location-id default
```
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",
"IAMRoleArn": "arn:aws:iam::111122223333:role/accessGrantsTestRole"
}
```
**Example – List all of the locations that are registered in an S3 Access Grants instance**
To restrict the results to an S3 prefix or bucket, you can optionally use the `--location-scope s3://bucket-and-or-prefix` parameter.
```
aws s3control list-access-grants-locations \
--account-id 111122223333 \
--region us-east-2
```
Response:
```
{"AccessGrantsLocationsList": [
{
"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"
},
{
"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://amzn-s3-demo-bucket/prefixA*",
"IAMRoleArn": "arn:aws:iam::111122223333:role/accessGrantsTestRole"
}
]
}
```
## Using the REST API
For information about the Amazon S3 REST API support for getting the details of a registered location or listing all of the locations that are registered with an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsLocation.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListAccessGrantsLocations.html)
## Using the AWS SDKs
This section provides examples of how to get the details of a registered location or list all of the registered locations in an S3 Access Grants instance 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 a registered location**
```
public void getAccessGrantsLocation() {
GetAccessGrantsLocationRequest getAccessGrantsLocationRequest = GetAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.accessGrantsLocationId("default")
.build();
GetAccessGrantsLocationResponse getAccessGrantsLocationResponse = s3Control.getAccessGrantsLocation(getAccessGrantsLocationRequest);
LOGGER.info("GetAccessGrantsLocationResponse: " + getAccessGrantsLocationResponse);
}
```
Response:
```
GetAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:10.027Z,
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 – List all registered locations in an S3 Access Grants instance**
To restrict the results to an S3 prefix or bucket, you can optionally pass an S3 URI, such as `s3://bucket-and-or-prefix`, in the `LocationScope` parameter.
```
public void listAccessGrantsLocations() {
ListAccessGrantsLocationsRequest listRequest = ListAccessGrantsLocationsRequest.builder()
.accountId("111122223333")
.build();
ListAccessGrantsLocationsResponse listResponse = s3Control.listAccessGrantsLocations(listRequest);
LOGGER.info("ListAccessGrantsLocationsResponse: " + listResponse);
}
```
Response:
```
ListAccessGrantsLocationsResponse(
AccessGrantsLocationsList=[
ListAccessGrantsLocationsEntry(
CreatedAt=2023-06-07T04:35:11.027Z,
AccessGrantsLocationId=default,
AccessGrantsLocationArn=arn:aws:s3:us-east-2:111122223333:access-grants/default/location/default,
LocationScope=s3://,
IAMRoleArn=arn:aws:iam::111122223333:role/accessGrantsTestRole
),
ListAccessGrantsLocationsEntry(
CreatedAt=2023-06-07T04:35:10.027Z,
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://amzn-s3-demo-bucket/prefixA*,
IAMRoleArn=arn:aws:iam::111122223333:role/accessGrantsTestRole
)
]
)
```
------
# Update a registered location
You can update the AWS Identity and Access Management (IAM) role of a location that's registered in your Amazon S3 Access Grants instance. For each new IAM role that you use to register a location in S3 Access Grants, be sure to give the S3 Access Grants service principal (`access-grants.s3.amazonaws.com`) access to this role. To do this, add an entry for the new IAM role in the same trust policy JSON file that you used when you first [registered the location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html).
You can update 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, and the AWS SDKs.
## Using the S3 console
**To update the IAM role of a location registered with your S3 Access Grants instance**
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 for the instance, choose the **Locations** tab.
1. Find the location that you want to update. To filter the list of locations, use the search box.
1. Choose the options button next to the registered location that you want to update.
1. Update the IAM role, and then choose **Save changes**.
## 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 – Update the IAM role of a registered location**
```
aws s3control update-access-grants-location \
--account-id 111122223333 \
--access-grants-location-id 635f1139-1af2-4e43-8131-a4de006eb999 \
--iam-role-arn arn:aws:iam::777788889999:role/accessGrantsTestRole
```
Response:
```
{
"CreatedAt": "2023-05-31T18:23:48.107000+00:00",
"AccessGrantsLocationId": "635f1139-1af2-4e43-8131-a4de006eb999",
"AccessGrantsLocationArn": "arn:aws:s3:us-east-2:777788889999:access-grants/default/location/635f1139-1af2-4e43-8131-a4de006eb888",
"LocationScope": "s3://amzn-s3-demo-bucket/prefixB*",
"IAMRoleArn": "arn:aws:iam::777788889999:role/accessGrantsTestRole"
}
```
## Using the REST API
For information on the Amazon S3 REST API support for updating a location in an S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UpdateAccessGrantsLocation.html) in the *Amazon Simple Storage Service API Reference*.
## Using the AWS SDKs
This section provides examples of how to update the IAM role of a registered location by using the AWS SDKs.
To use the following example, replace the `user input placeholders` with your own information.
------
#### [ Java ]
**Example – Update the IAM role of a registered location**
```
public void updateAccessGrantsLocation() {
UpdateAccessGrantsLocationRequest updateRequest = UpdateAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.accessGrantsLocationId("635f1139-1af2-4e43-8131-a4de006eb999")
.iamRoleArn("arn:aws:iam::777788889999:role/accessGrantsTestRole")
.build();
UpdateAccessGrantsLocationResponse updateResponse = s3Control.updateAccessGrantsLocation(updateRequest);
LOGGER.info("UpdateAccessGrantsLocationResponse: " + updateResponse);
}
```
Response:
```
UpdateAccessGrantsLocationResponse(
CreatedAt=2023-06-07T04:35:10.027Z,
AccessGrantsLocationId=635f1139-1af2-4e43-8131-a4de006eb999,
AccessGrantsLocationArn=arn:aws:s3:us-east-2:777788889999:access-grants/default/location/635f1139-1af2-4e43-8131-a4de006eb888,
LocationScope=s3://amzn-s3-demo-bucket/prefixB*,
IAMRoleArn=arn:aws:iam::777788889999:role/accessGrantsTestRole
)
```
------
# Delete a registered location
You can delete a location registration from an Amazon S3 Access Grants instance. Deleting the location deregisters it from the S3 Access Grants instance.
Before you can remove a location registration from an S3 Access Grants instance, you must delete all of the grants that are associated with this location. For information about how to delete grants, see [Delete a grant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant-delete.html).
You can delete 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, and the AWS SDKs.
## Using the S3 console
**To delete a location registration from your S3 Access Grants instance**
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 for the instance, choose the **Locations** tab.
1. Find the location that you want to update. To filter the list of locations, use the search box.
1. Choose the option button next to the registered location that you want to delete.
1. Choose **Deregister**.
1. A dialog box appears that warns you that this action can't be undone. To delete the location, choose **Deregister**.
## 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 a location registration**
```
aws s3control delete-access-grants-location \
--account-id 111122223333 \
--access-grants-location-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
// No response body
```
## Using the REST API
For information about the Amazon S3 REST API support for deleting a location from an S3 Access Grants instance, see [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsLocation.html) in the *Amazon Simple Storage Service API Reference*.
## Using the AWS SDKs
This section provides an example of how to delete a location by using the AWS SDKs.
To use the following example, replace the `user input placeholders` with your own information.
------
#### [ Java ]
**Example – Delete a location registration**
```
public void deleteAccessGrantsLocation() {
DeleteAccessGrantsLocationRequest deleteRequest = DeleteAccessGrantsLocationRequest.builder()
.accountId("111122223333")
.accessGrantsLocationId("a1b2c3d4-5678-90ab-cdef-EXAMPLE11111")
.build();
DeleteAccessGrantsLocationResponse deleteResponse = s3Control.deleteAccessGrantsLocation(deleteRequest);
LOGGER.info("DeleteAccessGrantsLocationResponse: " + deleteResponse);
}
```
Response:
```
DeleteAccessGrantsLocationResponse()
```
------
# 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()
```
------
# Getting S3 data using access grants
Grantees who have been given access to S3 data through S3 Access Grants must request temporary credentials from S3 Access Grants, which they use to access the S3 data. For more information, see [Request access to Amazon S3 data through S3 Access Grants](access-grants-credentials.md). Grantees then use the temporary credentials to perform allowable S3 actions on the S3 data. For more information, see [Accessing S3 data using credentials vended by S3 Access Grants](access-grants-get-data.md). Grantees can optionally request a list of their access grants for an AWS account before requesting these credentials. For more information, see [List the caller's access grants](access-grants-list-grants.md).
**Topics**
+ [
# Request access to Amazon S3 data through S3 Access Grants
](access-grants-credentials.md)
+ [
# Accessing S3 data using credentials vended by S3 Access Grants
](access-grants-get-data.md)
+ [
# List the caller's access grants
](access-grants-list-grants.md)
# Request access to Amazon S3 data through S3 Access Grants
After you [create an access grant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html) using S3 Access Grants, grantees can request credentials to access the S3 data that they were granted access to. Grantees can be AWS Identity and Access Management (IAM) principals, your corporate directory identities, or authorized applications.
An application or AWS service can use the S3 Access Grants `GetDataAccess` API operation to ask S3 Access Grants for access to your S3 data on behalf of a grantee. `GetDataAccess` first verifies that you have granted this identity access to the data. Then, S3 Access Grants uses the [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API operation to obtain a temporary credential token and vends it to the requester. This temporary credential token is an AWS Security Token Service (AWS STS) token.
The `GetDataAccess` request must include the `target` parameter, which specifies the scope of the S3 data that the temporary credentials apply to. This `target` scope can be the same as the scope of the grant or a subset of that scope, but the `target` scope must be within the scope of the grant that was given to the grantee. The request must also specify the `permission` parameter to indicate the permission level for the temporary credentials, whether `READ`, `WRITE`, or `READWRITE`.
**Privilege**
The requester can specify the privilege level of the temporary token in their credential request. Using the `privilege` parameter, the requester can reduce or increase the temporary credentials' scope of access, within the boundaries of the grant scope. The default value of the `privilege` parameter is `Default`, which means that the target scope of the credential returned is the original grant scope. The other possible value for `privilege` is `Minimal`. If the `target` scope is reduced from the original grant scope, then the temporary credential is de-scoped to match the `target` scope, as long as the `target` scope is within the grant scope.
The following table details the effect of the `privilege` parameter on two grants. One grant has the scope `S3://amzn-s3-demo-bucket1/bob/*`, which includes the entire `bob/` prefix in the `amzn-s3-demo-bucket1` bucket. The other grant has the scope `S3://amzn-s3-demo-bucket1/bob/reports/*`, which includes only the `bob/reports/` prefix in the `amzn-s3-demo-bucket1` bucket.
| Grant scope | Requested scope | Privilege | Returned scope | Effect |
| --- | --- | --- | --- | --- |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/\$1 | Default | amzn-s3-demo-bucket1/bob/\$1 | The requester has access to all objects that have key names that start with the prefix `bob/` in the `amzn-s3-demo-bucket1` bucket. |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/ | Minimal | amzn-s3-demo-bucket1/bob/ | Without a wild card \$1 character after the prefix name `bob/`, the requester has access to only the object named `bob/` in the `amzn-s3-demo-bucket1` bucket. It's not common to have such an object. The requester doesn't have access to any other objects, including those that have key names that start with the `bob/` prefix. |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | Minimal | amzn-s3-demo-bucket1/bob/images/\$1 | The requester has access to all objects that have key names that start with the prefix `bob/images/*`in the `amzn-s3-demo-bucket1` bucket. |
| S3://amzn-s3-demo-bucket1/bob/reports/\$1 | amzn-s3-demo-bucket1/bob/reports/file.txt | Default | amzn-s3-demo-bucket1/bob/reports/\$1 | The requester has access to all objects that have key names that start with the `bob/reports` prefix in the `amzn-s3-demo-bucket1` bucket, which is the scope of the matching grant. |
| S3://amzn-s3-demo-bucket1/bob/reports/\$1 | amzn-s3-demo-bucket1/bob/reports/file.txt | Minimal | amzn-s3-demo-bucket1/bob/reports/file.txt | The requester has access only to the object with the key name `bob/reports/file.txt` in the `amzn-s3-demo-bucket1` bucket. The requester has no access to any other object. |
**Directory identities**
`GetDataAccess` considers all of the identities involved in a request when matching suitable grants. For corporate directory identities, `GetDataAccess` also returns the grants of the IAM identity that is used for the identity-aware session. For more information on identity-aware sessions, see [Granting permissions to use identity-aware console sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_sts-setcontext.html) in the *AWS Identity and Access Management User Guide*. `GetDataAccess` generates credentials restricting scope to the most restrictive grant, as shown in the following table:
| Grant scope for IAM identity | Grant scope for directory identity | Requested scope | Returned scope | Privilege | Effect |
| --- | --- | --- | --- | --- | --- |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/\$1 | Default | The requestor has access to all of the objects that have key names that start with the prefix *bob/* as a part of the grant for the IAM role but is restricted to the prefixes *bob/images/* as a part of the grant for the directory identity. Both the IAM role and directory identity provide access to the requested scope, which is `bob/images/image1.jpeg`, but the directory identity has a more restrictive grant. So, the returned scope is restricted to the more restrictive grant for the directory identity. |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | Minimal | Because the Privilege is set to `Minimal`, even though the identity has access to a bigger scope, only the requested scope is returned `bob/images/image1.jpeg`. |
| S3://amzn-s3-demo-bucket1/bob/images/\$1 | amzn-s3-demo-bucket1/bob/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/\$1 | Default | The requestor has access to all of the objects that have key names that start with the prefix *bob/* as a part of the grant for the directory identity but is restricted to the prefixes *bob/images/* as a part of the grant for the IAM role. Both the IAM role and directory identity provide access to the requested scope, which is `bob/images/image1.jpeg`, but the IAM role has a more restrictive grant. So, the returned scope is restricted to the more restrictive grant for the IAM role. |
| S3://amzn-s3-demo-bucket1/bob/images/\$1 | amzn-s3-demo-bucket1/bob/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | Minimal | Because the Privilege is set to `Minimal`, even though the identity has access to a bigger scope, only the requested scope is returned `bob/images/image1.jpeg`. |
**Duration**
The `durationSeconds` parameter sets the temporary credential's duration, in seconds. The default value is `3600` seconds (1 hour), but the requester (the grantee) can specify a range from `900` seconds (15 minutes) up to `43200` seconds (12 hours). If the grantee requests a value higher than this maximum, the request fails.
**Note**
In your request for a temporary token, if the location is an object, set the value of the `targetType` parameter in your request to `Object`. This parameter is required only if the location is an object and the privilege level is `Minimal`. If the location is a bucket or a prefix, you don't need to specify this parameter.
**Examples**
You can request temporary credentials by using the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs. See these examples.
For additional information, see [GetDataAccess](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html) in the *Amazon Simple Storage Service API Reference*.
## 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 Request temporary credentials**
Request:
```
aws s3control get-data-access \
--account-id 111122223333 \
--target s3://amzn-s3-demo-bucket/prefixA* \
--permission READ \
--privilege Default \
--region us-east-2
```
Response:
```
{
"Credentials": {
"AccessKeyId": "Example-key-id",
"SecretAccessKey": "Example-access-key",
"SessionToken": "Example-session-token",
"Expiration": "2023-06-14T18:56:45+00:00"},
"MatchedGrantTarget": "s3://amzn-s3-demo-bucket/prefixA**",
"Grantee": {
"GranteeType": "IAM",
"GranteeIdentifier": "arn:aws:iam::111122223333:role/role-name"
}
}
```
## Using the REST API
For information about the Amazon S3 REST API support for requesting temporary credentials from S3 Access Grants, see [GetDataAccess](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html) in the *Amazon Simple Storage Service API Reference*.
## Using the AWS SDKs
This section provides an example of how grantees request temporary credentials from S3 Access Grants by using the AWS SDKs.
------
#### [ Java ]
The following code example returns the temporary credentials that the grantee uses to access your S3 data. To use this code example, replace the `user input placeholders` with your own information.
**Example Get temporary credentials**
Request:
```
public void getDataAccess() {
GetDataAccessRequest getDataAccessRequest = GetDataAccessRequest.builder()
.accountId("111122223333")
.permission(Permission.READ)
.privilege(Privilege.MINIMAL)
.target("s3://amzn-s3-demo-bucket/prefixA*")
.build();
GetDataAccessResponse getDataAccessResponse = s3Control.getDataAccess(getDataAccessRequest);
LOGGER.info("GetDataAccessResponse: " + getDataAccessResponse);
}
```
Response:
```
GetDataAccessResponse(
Credentials=Credentials(
AccessKeyId="Example-access-key-id",
SecretAccessKey="Example-secret-access-key",
SessionToken="Example-session-token",
Expiration=2023-06-07T06:55:24Z
))
```
------
# Accessing S3 data using credentials vended by S3 Access Grants
After a grantee [obtains temporary credentials](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-credentials.html) through their access grant, they can use these temporary credentials to call Amazon S3 API operations to access your data.
Grantees can access S3 data by using the AWS Command Line Interface (AWS CLI), the AWS SDKs, and the Amazon S3 REST API. Additionally, you can use the AWS [Python](https://github.com/aws/boto3-s3-access-grants-plugin) and [Java](https://github.com/aws/aws-s3-accessgrants-plugin-java-v2) plugins to call S3 Access Grants
## Using the AWS CLI
After the grantee obtains their temporary credentials from S3 Access Grants, they can set up a profile with these credentials to retrieve the data.
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 – Set up a profile**
```
aws configure set aws_access_key_id "$accessKey" --profile access-grants-consumer-access-profile
aws configure set aws_secret_access_key "$secretKey" --profile access-grants-consumer-access-profile
aws configure set aws_session_token "$sessionToken" --profile access-grants-consumer-access-profile
```
To use the following example command, replace the `user input placeholders` with your own information.
**Example – Get the S3 data**
The grantee can use the [https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-object.html) AWS CLI command to access the data. The grantee can also use [https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-object.html), [https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html](https://docs.aws.amazon.com/cli/latest/reference/s3/ls.html), and other S3 AWS CLI commands.
```
aws s3api get-object \
--bucket amzn-s3-demo-bucket1 \
--key myprefix \
--region us-east-2 \
--profile access-grants-consumer-access-profile
```
## Using the AWS SDKs
This section provides examples of how grantees can access your S3 data by using the AWS SDKs.
------
#### [ Java ]
The following Java code example gets an object from an S3 bucket. For instructions on creating and testing a working sample, see [Getting Started](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/getting-started.html) in the *AWS SDK for Java Developer Guide*.
```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.GetObjectRequest;
import com.amazonaws.services.s3.model.ResponseHeaderOverrides;
import com.amazonaws.services.s3.model.S3Object;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
public class GetObject2 {
public static void main(String[] args) throws IOException {
Regions clientRegion = Regions.DEFAULT_REGION;
String bucketName = "*** Bucket name ***";
String key = "*** Object key ***";
S3Object fullObject = null, objectPortion = null, headerOverrideObject = null;
try {
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
.withRegion(clientRegion)
.withCredentials(new ProfileCredentialsProvider())
.build();
// Get an object and print its contents.
System.out.println("Downloading an object");
fullObject = s3Client.getObject(new GetObjectRequest(bucketName, key));
System.out.println("Content-Type: " + fullObject.getObjectMetadata().getContentType());
System.out.println("Content: ");
displayTextInputStream(fullObject.getObjectContent());
// Get a range of bytes from an object and print the bytes.
GetObjectRequest rangeObjectRequest = new GetObjectRequest(bucketName, key)
.withRange(0, 9);
objectPortion = s3Client.getObject(rangeObjectRequest);
System.out.println("Printing bytes retrieved.");
displayTextInputStream(objectPortion.getObjectContent());
// Get an entire object, overriding the specified response headers, and print
// the object's content.
ResponseHeaderOverrides headerOverrides = new ResponseHeaderOverrides()
.withCacheControl("No-cache")
.withContentDisposition("attachment; filename=example.txt");
GetObjectRequest getObjectRequestHeaderOverride = new GetObjectRequest(bucketName, key)
.withResponseHeaders(headerOverrides);
headerOverrideObject = s3Client.getObject(getObjectRequestHeaderOverride);
displayTextInputStream(headerOverrideObject.getObjectContent());
} catch (AmazonServiceException e) {
// The call was transmitted successfully, but Amazon S3 couldn't process
// it, so it returned an error response.
e.printStackTrace();
} catch (SdkClientException e) {
// Amazon S3 couldn't be contacted for a response, or the client
// couldn't parse the response from Amazon S3.
e.printStackTrace();
} finally {
// To ensure that the network connection doesn't remain open, close any open
// input streams.
if (fullObject != null) {
fullObject.close();
}
if (objectPortion != null) {
objectPortion.close();
}
if (headerOverrideObject != null) {
headerOverrideObject.close();
}
}
}
private static void displayTextInputStream(InputStream input) throws IOException {
// Read the text input stream one line at a time and display each line.
BufferedReader reader = new BufferedReader(new InputStreamReader(input));
String line = null;
while ((line = reader.readLine()) != null) {
System.out.println(line);
}
System.out.println();
}
}
```
------
## Supported S3 actions in S3 Access Grants
A grantee can use the temporary credential vended by S3 Access Grants to perform S3 actions on the S3 data they have access to. The following is a list of allowable S3 actions that a grantee can perform. Which actions are allowable depends on the level of permission granted in the access grant, either `READ`, `WRITE`, or `READWRITE`.
**Note**
In addition to the Amazon S3 permissions listed below, Amazon S3 can call the AWS Key Management Service (AWS KMS) [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) (`kms:decrypt`) `READ` permission or the AWS KMS [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) (`kms:generateDataKey`) `WRITE` permission. These permissions don't allow direct access to the AWS KMS key.
****
| S3 IAM action | API action & doc | S3 Access Grants Permission | S3 resource |
| --- | --- | --- | --- |
| s3:GetObject | [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) | READ | Object |
| s3:GetObjectVersion | [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) | READ | Object |
| s3:GetObjectAcl | [GetObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectAcl.html) | READ | Object |
| s3:GetObjectVersionAcl | [GetObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectAcl.html) | READ | Object |
| s3:ListMultipartUploads | [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) | READ | Object |
| s3:PutObject | [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html), [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html), [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html), [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html), [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | WRITE | Object |
| s3:PutObjectAcl | [PutObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html) | WRITE | Object |
| s3:PutObjectVersionAcl | [PutObjectAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectAcl.html) | WRITE | Object |
| s3:DeleteObject | [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) | WRITE | Object |
| s3:DeleteObjectVersion | [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) | WRITE | Object |
| s3:AbortMultipartUpload | [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | WRITE | Object |
| s3:ListBucket | [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html), [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html), [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) | READ | Bucket |
| s3:ListBucketVersions | [ListObjectVersions](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html) | READ | Bucket |
| s3:ListBucketMultipartUploads | [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) | READ | Bucket |
# List the caller's access grants
S3 data owners can use S3 Access Grants to create access grants for AWS Identity and Access Management (IAM) identities or for AWS IAM Identity Center corporate directory identities. IAM identies and IAM Identity Center directory identities can in turn use the `ListCallerAccessGrants` API to list all of the Amazon S3 buckets, prefixes, and objects they can access, as defined by their S3 Access Grants. Use this API to discover all of the S3 data an IAM or directory identity can access through S3 Access Grants.
You can use this feature to build applications that show the data that is accessible to specific end-users. For example, the AWS Storage Browser for S3, an open source UI component that customers use to access S3 buckets, uses this feature to present end-users with the data that they have access to in Amazon S3, based on their S3 Access Grants. Another example is when building an application for browsing, uploading, or downloading data in Amazon S3, you can use this feature to build a tree structure in your application that an end-user could then browse.
**Note**
For corporate directory identities, when listing the caller's access grants, S3 Access Grants returns the grants of the IAM identity that is used for the identity-aware session. For more information on identity-aware sessions, see [Granting permissions to use identity-aware console sessions](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_sts-setcontext.html) in the *AWS Identity and Access Management User Guide*.
The grantee whether an IAM identity, or a corporate directory identity can get a list of their access grants by using the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs.
## 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 List a caller's access grants**
Request:
```
aws s3control list-caller-access-grants \
--account-id 111122223333 \
--region us-east-2
--max-results 5
```
Response:
```
{
"NextToken": "6J9S...",
"CallerAccessGrantsList": [
{
"Permission": "READWRITE",
"GrantScope": "s3://amzn-s3-demo-bucket/prefix1/sub-prefix1/*",
"ApplicationArn": "NA"
},
{
"Permission": "READWRITE",
"GrantScope": "s3://amzn-s3-demo-bucket/prefix1/sub-prefix2/*",
"ApplicationArn": "ALL"
},
{
"Permission": "READWRITE",
"GrantScope": "s3://amzn-s3-demo-bucket/prefix1/sub-prefix3/*",
"ApplicationArn": "arn:aws:sso::111122223333:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d"
}
]
}
```
**Example List a caller's access grants for a bucket**
You can narrow the scope of the results using the `grantscope` parameter.
Request:
```
aws s3control list-caller-access-grants \
--account-id 111122223333 \
--region us-east-2
--grant-scope "s3://amzn-s3-demo-bucket""
--max-results 1000
```
Response:
```
{
"NextToken": "6J9S...",
"CallerAccessGrantsList": [
{
"Permission": "READ",
"GrantScope": "s3://amzn-s3-demo-bucket*",
"ApplicationArn": "ALL"
},
{
"Permission": "READ",
"GrantScope": "s3://amzn-s3-demo-bucket/prefix1/*",
"ApplicationArn": "arn:aws:sso::111122223333:application/ssoins-ssoins-1234567890abcdef/apl-abcd1234a1b2c3d"
}
]
}
```
## Using the REST API
For information about the Amazon S3 REST API support for getting a list of the API caller's access grants, see [ListCallerAccessGrants](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListCallerAccessGrants.html) in the *Amazon Simple Storage Service API Reference*.
## Using the AWS SDKs
This section provides an example of how grantees request temporary credentials from S3 Access Grants by using the AWS SDKs.
------
#### [ Java ]
The following code example returns the API caller's access grants to the S3 data of a particular AWS account. To use this code example, replace the `user input placeholders` with your own information.
**Example List a caller's access grants**
Request:
```
Public void ListCallerAccessGrants() {
ListCallerAccessGrantsRequest listRequest = ListCallerAccessGrantsRequest.builder()
.withMaxResults(1000)
.withGrantScope("s3://")
.accountId("111122223333");
ListCallerAccessGrantsResponse listResponse = s3control.listCallerAccessGrants(listRequest);
LOGGER.info("ListCallerAccessGrantsResponse: " + listResponse);
}
```
Response:
```
ListCallerAccessGrantsResponse(
CallerAccessGrantsList=[
ListCallerAccessGrantsEntry(
S3Prefix=s3://amzn-s3-demo-bucket/prefix1/,
Permission=READ,
ApplicationArn=ALL
)
])
```
------
# S3 Access Grants cross-account access
With S3 Access Grants, you can grant Amazon S3 data access to the following:
+ AWS Identity and Access Management (IAM) identities within your account
+ IAM identities in other AWS accounts
+ Directory users or groups in your AWS IAM Identity Center instance
First, configure cross-account access for the other account. This includes granting access to your S3 Access Grants instance by using a resource policy. Then, grant access to your S3 data (buckets, prefixes, or objects) by using grants.
After you configure cross-account access, the other account can request temporary access credentials to your Amazon S3 data from S3 Access Grants. The following image shows the user flow for cross-account S3 access through S3 Access Grants:
![\[S3 Access Grants cross-account user flow\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/access-grants-cross-account.png)
1. Users or applications in a second account (B) request credentials from the S3 Access Grants instance in your account (A), where the Amazon S3 data is stored. For more information, see [Request access to Amazon S3 data through S3 Access Grants](access-grants-credentials.md).
1. The S3 Access Grants instance in your account (A) returns temporary credentials if there is a grant that gives the second account access to your Amazon S3 data. For more information on access grants, see [Working with grants in S3 Access Grants](access-grants-grant.md).
1. Users or applications in the second account (B) use the S3 Access Grants-vended credentials to access the S3 data in your account (A).
**Configuring S3 Access Grants cross-account access**
To grant cross-account S3 access through S3 Access Grants, follow these steps:
+ **Step 1:** Configure an S3 Access Grants instance in your account, for example, account ID `111122223333`, where the S3 data is stored.
+ **Step 2:** Configure the resource policy for the S3 Access Grants instance in your account `111122223333` to give access to the second account, for example, account ID `444455556666`.
+ **Step 3:** Configure the IAM permissions for the IAM Principal in the second account `444455556666` to request credentials from the S3 Access Grants instance in your account `111122223333`.
+ **Step 4:** Create a grant in your account `111122223333` that gives the IAM Principal in the second account `444455556666` access to some of the S3 data in your account `111122223333`.
## Step 1: Configure an S3 Access Grants instance in your account
First, you must have an S3 Access Grants instance in your account `111122223333` to manage access to your Amazon S3 data. You must create an S3 Access Grants instance in each AWS Region where the S3 data that you want to share is stored. If you are sharing data in more than one AWS Region, then repeat each of these configuration steps for each AWS Region. If you already have an S3 Access Grants instance in the AWS Region where your S3 data is stored, proceed to the next step. If you haven’t configured an S3 Access Grants instance, see [Working with S3 Access Grants instances](access-grants-instance.md) to complete this step.
## Step 2: Configure the resource policy for your S3 Access Grants instance to grant cross-account access
After you create an S3 Access Grants instance in your account `111122223333` for cross-account access, configure the resource-based policy for the S3 Access Grants instance in your account `111122223333` to grant cross-account access. The S3 Access Grants instance itself supports resource-based policies. With the correct resource-based policy in place, you can grant access for AWS Identity and Access Management (IAM) users or roles from other AWS accounts to your S3 Access Grants instance. Cross-account access only grants these permissions (actions):
+ `s3:GetAccessGrantsInstanceForPrefix` — the user, role, or app can retrieve the S3 Access Grants instance that contains a particular prefix.
+ `s3:ListAccessGrants`
+ `s3:ListAccessLocations`
+ `s3:ListCallerAccessGrants`
+ `s3:GetDataAccess` — the user, role, or app can request temporary credentials based on the access you were granted through S3 Access Grants. Use these credentials to access the S3 data to which you have been granted access.
You can choose which of these permissions to include in the resource policy. This resource policy on the S3 Access Grants instance is a normal resource-based policy and supports everything that the [IAM policy language](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) supports. In the same policy, you can grant access to specific IAM identities in your account `111122223333`, for example, by using the `aws:PrincipalArn` condition, but you don't have to do that with S3 Access Grants. Instead, within your S3 Access Grants instance, you can create grants for individual IAM identities from your account, as well as for the other account. By managing each access grant through S3 Access Grants, you can scale your permissions.
If you already use [AWS Resource Access Manager](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) (AWS RAM), you can use it to share your [https://docs.aws.amazon.com/ram/latest/userguide/shareable.html#shareable-s3](https://docs.aws.amazon.com/ram/latest/userguide/shareable.html#shareable-s3) resources with other accounts or within your organization. See [Working with shared AWS resources](https://docs.aws.amazon.com/ram/latest/userguide/working-with.html) for more information. If you don't use AWS RAM, you can also add the resource policy by using the S3 Access Grants API operations or the AWS Command Line Interface (AWS CLI).
### Using the S3 console
We recommend that you use the AWS Resource Access Manager (AWS RAM) Console to share your `s3:AccessGrants` resources with other accounts or within your organization. To share S3 Access Grants cross-account, do the following:
**To configure the S3 Access Grants instance resource policy:**
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. Select the AWS Region from the AWS Region selector.
1. From the left navigation pane, select **Access Grants**.
1. On the Access Grants instance page, in the **Instance in this account** section, select **Share instance**. This will redirect you to the AWS RAM Console.
1. Select **Create resource share**.
1. Follow the AWS RAM steps to create the resource share. For more information, see [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html).
### 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*.
You can add the resource policy by using the `put-access-grants-instance-resource-policy` CLI command.
If you want to grant cross-account access for the S3 Access Grants instance is in your account `111122223333` to the second account `444455556666`, the resource policy for the S3 Access Grants instance in your account `111122223333` should give the second account `444455556666` permission to perform the following actions:
+ `s3:ListAccessGrants`
+ `s3:ListAccessGrantsLocations`
+ `s3:GetDataAccess`
+ `s3:GetAccessGrantsInstanceForPrefix`
In the S3 Access Grants instance resource policy, specify the ARN of your S3 Access Grants instance as the `Resource`, and the second account `444455556666` as the `Principal`. To use the following example, replace the *user input placeholders* with your own information.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "444455556666"
},
"Action": [
"s3:ListAccessGrants",
"s3:ListAccessGrantsLocations",
"s3:GetDataAccess",
"s3:GetAccessGrantsInstanceForPrefix"
],
"Resource": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
} ]
}
```
To add or update the S3 Access Grants instance resource policy, use the following command. When you use the following example command, replace the `user input placeholders` with your own information.
**Example Add or update the S3 Access Grants instance resource policy**
```
aws s3control put-access-grants-instance-resource-policy \
--account-id 111122223333 \
--policy file://resourcePolicy.json \
--region us-east-2
{
"Policy": "{\n
\"Version\": \"2012-10-17\",\n
\"Statement\": [{\n
\"Effect\": \"Allow\",\n
\"Principal\": {\n
\"AWS\": \"444455556666\"\n
},\n
\"Action\": [\n
\"s3:ListAccessGrants\",\n
\"s3:ListAccessGrantsLocations\",\n
\"s3:GetDataAccess\",\n
\"s3:GetAccessGrantsInstanceForPrefix\",\n
\"s3:ListCallerAccessGrants"\n
],\n
\"Resource\": \"arn:aws:s3:us-east-2:111122223333:access-grants/default\"\n
}\n
]\n
}\n",
"CreatedAt": "2023-06-16T00:07:47.473000+00:00"
}
```
**Example Get an S3 Access Grants resource policy**
You can also use the CLI to get or delete a resource policy for an S3 Access Grants instance.
To get an S3 Access Grants resource policy, use the following example command. To use this example command, replace the `user input placeholders` with your own information.
```
aws s3control get-access-grants-instance-resource-policy \
--account-id 111122223333 \
--region us-east-2
{
"Policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::111122223333:root\"},\"Action\":[\"s3:ListAccessGrants\",\"s3:ListAccessGrantsLocations\",\"s3:GetDataAccess\",\"s3:GetAccessGrantsInstanceForPrefix\",\"s3:ListCallerAccessGrants\"],\"Resource\":\"arn:aws:
s3:us-east-2:111122223333:access-grants/default\"}]}",
"CreatedAt": "2023-06-16T00:07:47.473000+00:00"
}
```
**Example Delete an S3 Access Grants resource policy**
To delete an S3 Access Grants resource policy, use the following example command. To use this example command, replace the `user input placeholders` with your own information.
```
aws s3control delete-access-grants-instance-resource-policy \
--account-id 111122223333 \
--region us-east-2
// No response body
```
### Using the REST API
You can add the resource policy by using the [PutAccessGrantsInstanceResourcePolicy API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html).
If you want to grant cross-account access for the S3 Access Grants instance is in your account `111122223333` to the second account `444455556666`, the resource policy for the S3 Access Grants instance in your account `111122223333` should give the second account `444455556666` permission to perform the following actions:
+ `s3:ListAccessGrants`
+ `s3:ListAccessGrantsLocations`
+ `s3:GetDataAccess`
+ `s3:GetAccessGrantsInstanceForPrefix`
In the S3 Access Grants instance resource policy, specify the ARN of your S3 Access Grants instance as the `Resource`, and the second account `444455556666` as the `Principal`. To use the following example, replace the *user input placeholders* with your own information.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "444455556666"
},
"Action": [
"s3:ListAccessGrants",
"s3:ListAccessGrantsLocations",
"s3:GetDataAccess",
"s3:GetAccessGrantsInstanceForPrefix"
],
"Resource": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
} ]
}
```
You can then use the [PutAccessGrantsInstanceResourcePolicy API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html) to configure the policy.
For information on the REST API support to update, get, or delete a resource policy for an S3 Access Grants instance, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [PutAccessGrantsInstanceResourcePolicy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutAccessGrantsInstanceResourcePolicy.html)
+ [GetAccessGrantsInstanceResourcePolicy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetAccessGrantsInstanceResourcePolicy.html)
+ [DeleteAccessGrantsInstanceResourcePolicy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteAccessGrantsInstanceResourcePolicy.html)
### Using the AWS SDKs
This section provides you with the AWS SDK examples of how to configure your S3 Access Grants resource policy to grant a second AWS account access to some of your S3 data.
------
#### [ Java ]
Add, update, get, or delete a resource policy to manage cross-account access to your S3 Access Grants instance.
**Example Add or update an S3 Access Grants instance resource policy**
If you want to grant cross-account access for the S3 Access Grants instance is in your account `111122223333` to the second account `444455556666`, the resource policy for the S3 Access Grants instance in your account `111122223333` should give the second account `444455556666` permission to perform the following actions:
+ `s3:ListAccessGrants`
+ `s3:ListAccessGrantsLocations`
+ `s3:GetDataAccess`
+ `s3:GetAccessGrantsInstanceForPrefix`
In the S3 Access Grants instance resource policy, specify the ARN of your S3 Access Grants instance as the `Resource`, and the second account `444455556666` as the `Principal`. To use the following example, replace the *user input placeholders* with your own information.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "444455556666"
},
"Action": [
"s3:ListAccessGrants",
"s3:ListAccessGrantsLocations",
"s3:GetDataAccess",
"s3:GetAccessGrantsInstanceForPrefix"
],
"Resource": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
} ]
}
```
To add or update an S3 Access Grants instance resource policy, use the following code example:
```
public void putAccessGrantsInstanceResourcePolicy() {
PutAccessGrantsInstanceResourcePolicyRequest putRequest = PutAccessGrantsInstanceResourcePolicyRequest.builder()
.accountId(111122223333)
.policy(RESOURCE_POLICY)
.build();
PutAccessGrantsInstanceResourcePolicyResponse putResponse = s3Control.putAccessGrantsInstanceResourcePolicy(putRequest);
LOGGER.info("PutAccessGrantsInstanceResourcePolicyResponse: " + putResponse);
}
```
Response:
```
PutAccessGrantsInstanceResourcePolicyResponse(
Policy={
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"AWS": "444455556666"
},
"Action": [
"s3:ListAccessGrants",
"s3:ListAccessGrantsLocations",
"s3:GetDataAccess",
"s3:GetAccessGrantsInstanceForPrefix",
"s3:ListCallerAccessGrants"
],
"Resource": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
}]
}
)
```
**Example Get an S3 Access Grants resource policy**
To get an S3 Access Grants resource policy, use the following code example. To use the following example command, replace the `user input placeholders` with your own information.
```
public void getAccessGrantsInstanceResourcePolicy() {
GetAccessGrantsInstanceResourcePolicyRequest getRequest = GetAccessGrantsInstanceResourcePolicyRequest.builder()
.accountId(111122223333)
.build();
GetAccessGrantsInstanceResourcePolicyResponse getResponse = s3Control.getAccessGrantsInstanceResourcePolicy(getRequest);
LOGGER.info("GetAccessGrantsInstanceResourcePolicyResponse: " + getResponse);
}
```
Response:
```
GetAccessGrantsInstanceResourcePolicyResponse(
Policy={"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:aws:iam::444455556666:root"},"Action":["s3:ListAccessGrants","s3:ListAccessGrantsLocations","s3:GetDataAccess","s3:GetAccessGrantsInstanceForPrefix","s3:ListCallerAccessGrants"],"Resource":"arn:aws:s3:us-east-2:111122223333:access-grants/default"}]},
CreatedAt=2023-06-15T22:54:44.319Z
)
```
**Example Delete an S3 Access Grants resource policy**
To delete an S3 Access Grants resource policy, use the following code example. To use the following example command, replace the `user input placeholders` with your own information.
```
public void deleteAccessGrantsInstanceResourcePolicy() {
DeleteAccessGrantsInstanceResourcePolicyRequest deleteRequest = DeleteAccessGrantsInstanceResourcePolicyRequest.builder()
.accountId(111122223333)
.build();
DeleteAccessGrantsInstanceResourcePolicyResponse deleteResponse = s3Control.putAccessGrantsInstanceResourcePolicy(deleteRequest);
LOGGER.info("DeleteAccessGrantsInstanceResourcePolicyResponse: " + deleteResponse);
}
```
Response:
```
DeleteAccessGrantsInstanceResourcePolicyResponse()
```
------
## Step 3: Grant IAM identities in a second account permission to call the S3 Access Grants instance in your account
After the owner of the Amazon S3 data has configured the cross-account policy for the S3 Access Grants instance in account `111122223333`, the owner of the second account `444455556666` must create an identity-based policy for its IAM users or roles, and the owner must give them access to the S3 Access Grants instance. In the identity-based policy, include one or more of the following actions, depending on what’s granted in the S3 Access Grants instance resource policy and the permissions you want to grant:
+ `s3:ListAccessGrants`
+ `s3:ListAccessGrantsLocations`
+ `s3:GetDataAccess`
+ `s3:GetAccessGrantsInstanceForPrefix`
+ `s3:ListCallerAccessGrants`
Following the [AWS cross-account access pattern](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html), the IAM users or roles in the second account `444455556666` must explicitly have one or more of these permissions. For example, grant the `s3:GetDataAccess` permission so that the IAM user or role can call the S3 Access Grants instance in account `111122223333` to request credentials.
To use this example command, replace the `user input placeholders` with your own information.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetDataAccess",
],
"Resource": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
}
]
}
```
For information on editing IAM identity-based policy, see [Editing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-edit.html) in the *AWS Identity and Access Management guide*.
## Step 4: Create a grant in the S3 Access Grants instance of your account that gives the IAM identity in the second account access to some of your S3 data
For the final configuration step, you can create a grant in the S3 Access Grants instance in your account 111122223333 that gives access to the IAM identity in the second account 444455556666 to some of the S3 data in your account. You can do this by using the Amazon S3 Console, CLI, API, and SDKs. For more information, see [Create grants](access-grants-grant-create.md).
In the grant, specify the AWS ARN of the IAM identity from the second account, and specify which location in your S3 data (a bucket, prefix, or object) that you are granting access to. This location must already be registered with your S3 Access Grants instance. For more information, see [Register a location](access-grants-location-register.md). You can optionally specify a subprefix. For example, if the location you are granting access to is a bucket, and you want to limit the access further to a specific object in that bucket, then pass the object key name in the `S3SubPrefix` field. Or if you want to limit access to the objects in the bucket with key names that start with a specific prefix, such as `2024-03-research-results/`, then pass `S3SubPrefix=2024-03-research-results/`.
The following is an example CLI command for creating an access grant for an identity in the second account. See [Create grants](access-grants-grant-create.md) for more information. To use this example command, replace the `user input placeholders` with your own information.
```
aws s3control create-access-grant \
--account-id 111122223333 \
--access-grants-location-id default \
--access-grants-location-configuration S3SubPrefix=prefixA* \
--permission READ \
--grantee GranteeType=IAM,GranteeIdentifier=arn:aws:iam::444455556666:role/data-consumer-1
```
After configuring cross-account access, the user or role in the second account can do the following:
+ Calls `ListAccessGrantsInstances` to list the S3 Access Grants instances shared with it through AWS RAM. For more information, see [Get the details of an S3 Access Grants instance](access-grants-instance-view.md).
+ Requests temporary credentials from S3 Access Grants. For more information on how to make these requests, see [Request access to Amazon S3 data through S3 Access Grants](access-grants-credentials.md).
# Managing tags for S3 Access Grants
Tags in Amazon S3 Access Grants have similar characteristics to [object tags](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html) in Amazon S3. Each tag is a key-value pair. The resources in S3 Access Grants that you can tag are S3 Access Grants [instances](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance.html), [locations](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html), and [grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html).
**Note**
Tagging in S3 Access Grants uses different API operations than object tagging. S3 Access Grants uses the [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_TagResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_TagResource.html), [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UntagResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UntagResource.html), and [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListTagsForResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListTagsForResource.html) API operations, where a resource can be either an S3 Access Grants instance, a registered location, or an access grant.
Similar to [object tags](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-tagging.html), the following limitations apply:
+ You can add tags to new S3 Access Grants resources when you create them, or you can add tags to existing resources.
+ You can associate up to 10 tags with a resource. If multiple tags are associated with the same resource, they must have unique tag keys.
+ A tag key can be up to 128 Unicode characters in length, and tag values can be up to 256 Unicode characters in length. Tags are internally represented in UTF-16. In UTF-16, characters consume either 1 or 2 character positions.
+ The keys and values are case sensitive.
For more information about tag restrictions, see [User-defined tag restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) in the *AWS Billing User Guide*.
You can tag resources in S3 Access Grants by using the AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, or the AWS SDKs.
## 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*.
You can tag an S3 Access Grants resource when you create it or after you have created it. The following examples show how you tag or untag an S3 Access Grants instance. You can perform similar operations for registered locations and access grants.
To use the following example commands, replace the `user input placeholders` with your own information.
**Example – Create an S3 Access Grants instance with tags**
```
aws s3control create-access-grants-instance \
--account-id 111122223333 \
--profile access-grants-profile \
--region us-east-2 \
--tags Key=tagKey1,Value=tagValue1
```
Response:
```
{
"CreatedAt": "2023-10-25T01:09:46.719000+00:00",
"AccessGrantsInstanceId": "default",
"AccessGrantsInstanceArn": "arn:aws:s3:us-east-2:111122223333:access-grants/default"
}
```
**Example – Tag an already created S3 Access Grants instance**
```
aws s3control tag-resource \
--account-id 111122223333 \
--resource-arn "arn:aws:s3:us-east-2:111122223333:access-grants/default" \
--profile access-grants-profile \
--region us-east-2 \
--tags Key=tagKey2,Value=tagValue2
```
**Example – List tags for the S3 Access Grants instance**
```
aws s3control list-tags-for-resource \
--account-id 111122223333 \
--resource-arn "arn:aws:s3:us-east-2:111122223333:access-grants/default" \
--profile access-grants-profile \
--region us-east-2
```
Response:
```
{
"Tags": [
{
"Key": "tagKey1",
"Value": "tagValue1"
},
{
"Key": "tagKey2",
"Value": "tagValue2"
}
]
}
```
**Example – Untag the S3 Access Grants instance**
```
aws s3control untag-resource \
--account-id 111122223333 \
--resource-arn "arn:aws:s3:us-east-2:111122223333:access-grants/default" \
--profile access-grants-profile \
--region us-east-2 \
--tag-keys "tagKey2"
```
## Using the REST API
You can use the Amazon S3 API to tag, untag, or list tags for an S3 Access Grants instance, registered location, or access grant. For information about the REST API support for managing S3 Access Grants tags, see the following sections in the *Amazon Simple Storage Service API Reference*:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_TagResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_TagResource.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UntagResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UntagResource.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListTagsForResource.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListTagsForResource.html)
# S3 Access Grants limitations
[S3 Access Grants](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants.html) has the following limitations:
**Note**
If your use case exceeds these limitations, [contact AWS support](https://aws.amazon.com/contact-us/?cmpid=docs_headercta_contactus) to request higher limits.
**S3 Access Grants instance**
You can create **1 S3 Access Grants instance** per AWS Region per account. See [Create an S3 Access Grants instance](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-instance-create.html).
**S3 Access Grants location**
You can register **1,000 S3 Access Grants locations** per S3 Access Grants instance. See [Register an S3 Access Grants location](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-location.html).
**Grant**
You can create **100,000 grants** per S3 Access Grants instance. See [Create a grant](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html).
## S3 Access Grants AWS Regions
S3 Access Grants is currently available in the following AWS Regions:
| AWS Region code | AWS Region name |
| --- | --- |
| us-east-1 | US East (N. Virginia) |
| us-east-2 | US East (Ohio) |
| us-west-1 | US West (N. California) |
| us-west-2 | US West (Oregon) |
| af-south-1 | Africa (Cape Town) |
| ap-east-1 | Asia Pacific (Hong Kong) |
| ap-east-2 | Asia Pacific (Taipei) |
| ap-northeast-1 | Asia Pacific (Tokyo) |
| ap-northeast-2 | Asia Pacific (Seoul) |
| ap-northeast-3 | Asia Pacific (Osaka) |
| ap-south-1 | Asia Pacific (Mumbai) |
| ap-south-2 | Asia Pacific (Hyderabad) |
| ap-southeast-1 | Asia Pacific (Singapore) |
| ap-southeast-2 | Asia Pacific (Sydney) |
| ap-southeast-3 | Asia Pacific (Jakarta) |
| ap-southeast-4 | Asia Pacific (Melbourne) |
| ap-southeast-6 | Asia Pacific (New Zealand) |
| ap-southeast-7 | Asia Pacific (Thailand) |
| ca-central-1 | Canada (Central) |
| ca-west-1 | Canada West (Calgary) |
| eu-central-1 | Europe (Frankfurt) |
| eu-central-2 | Europe (Zurich) |
| eu-north-1 | Europe (Stockholm) |
| eu-south-1 | Europe (Milan) |
| eu-south-2 | Europe (Spain) |
| eu-west-1 | Europe (Ireland) |
| eu-west-2 | Europe (London) |
| eu-west-3 | Europe (Paris) |
| il-central-1 | Israel (Tel Aviv) |
| me-central-1 | Middle East (UAE) |
| me-south-1 | Middle East (Bahrain) |
| mx-central-1 | Mexico (Central) |
| sa-east-1 | South America (São Paulo) |
| us-gov-east-1 | AWS GovCloud (US-East) |
| us-gov-west-1 | AWS GovCloud (US-West) |
# S3 Access Grants integrations
S3 Access Grants can be used with the following AWS services and features. This page will be updated as new integrations become available.
**Tip**
This [AWS workshop for S3 Access Grants](https://catalog.us-east-1.prod.workshops.aws/workshops/77b0af63-6ad2-4c94-bfc0-270eb9358c7a/en-US/0-getting-started) walks you through using S3 Access Grants with AWS Identity and Access Management (IAM) users, IAM Identity Center users, Amazon EMR, and AWS Transfer Family.
**Amazon Athena**
[Using IAM Identity Center enabled Athena workgroups](https://docs.aws.amazon.com/athena/latest/ug/workgroups-identity-center.html)
**Amazon EMR**
[Launch an Amazon EMR cluster with S3 Access Grants](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-access-grants.html)
**Amazon EMR on EKS**
[Launch an Amazon EMR on EKS cluster with S3 Access Grants](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/access-grants.html)
**Amazon EMR Serverless application**
[Launch an Amazon EMR Serverless application with S3 Access Grants](https://docs.aws.amazon.com/emr/latest/EMR-Serverless-UserGuide/access-grants.html)
**Amazon Redshift**
[Amazon Redshift integration with Amazon S3 Access Grants](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-sso-s3idc.html)
**Amazon SageMaker AI Studio**
[Adding Amazon S3 data to Amazon SageMaker AI Unified Studio](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/adding-existing-s3-data.html)
Using S3 Access Grants in Amazon SageMaker AI Unified Studio, you can share your Amazon S3 data in multiple projects. To enable granting access to data using S3 Access Grants, an S3 Access Grants instance is required. Amazon SageMaker AI Unified Studio will use an S3 Access Grants instance if one is already available or can create an instance. First, you add your Amazon S3 data and then publish the data to the catalog or share it directly with consumers.
[Using Amazon S3 Access Grants with Amazon SageMaker AI Studio and the SDK for Python (Boto3) plugin](https://aws.amazon.com/about-aws/whats-new/2024/07/amazon-s3-access-grants-integrate-sagemaker-studio/)
Using S3 Access Grants in Amazon SageMaker AI Studio notebooks is now easier when using the SDK for Python (Boto3) plugin. Set up access grants for IAM principals and AWS IAM Identity Center directory users, beforehand. Although Amazon SageMaker AI Studio does not natively support identity provider directory users, you can write custom Python code, using the plugin that allows these identities to access S3 data via S3 Access Grants. The data access is taking place with the help of the plugin and not through Amazon SageMaker AI.
**AWS Glue**
[Amazon S3 Access Grants with AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/security-s3-access-grants.html)
**AWS IAM Identity Center**
[Trusted identity propagation across applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)
**AWS Transfer Family**
[Configure Amazon S3 Access Grants](https://docs.aws.amazon.com/transfer/latest/userguide/webapp-access-grant.html) for AWS Transfer Family
**Storage Browser for S3**
[Managing data access at scale](https://docs.aws.amazon.com/AmazonS3/latest/userguide/setup-storagebrowser.html#setup-storagebrowser-method3) using Storage Browser for S3
**Open source Python frameworks**
[Amazon S3 Access Grants now integrates with open source Python frameworks](https://aws.amazon.com/about-aws/whats-new/2024/07/amazon-s3-access-grants-integrate-open-source-python/)