Request access to Amazon S3 data through S3 Access Grants

After you use Amazon S3 Access Grants to create an access grant that gives AWS Identity and Access Management (IAM) principals, your corporate directory identities, or authorized applications access to your S3 data, your grantees can request credentials to access this data.

When an application or AWS service uses the GetDataAccess API operation to ask S3 Access Grants for access to your S3 data on behalf of a grantee, S3 Access Grants first verifies that you have granted this identity access to the data. Then, S3 Access Grants uses the AssumeRole 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 requester. The request must also specify the permission parameter to indicate the permission level for the temporary credentials, whether READ, WRITE, or READWRITE.

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://DOC-EXAMPLE-BUCKET1/bob/*, which includes the entire bob/ prefix in the DOC-EXAMPLE-BUCKET1 bucket. The other grant has the scope S3://DOC-EXAMPLE-BUCKET1/bob/reports/*, which includes only the bob/reports/ prefix in the DOC-EXAMPLE-BUCKET1 bucket.

Grant scope	Requested scope	Privilege	Returned scope	Effect
`S3://DOC-EXAMPLE-BUCKET1/bob/*`	`DOC-EXAMPLE-BUCKET1/bob/*`	`Default`	`DOC-EXAMPLE-BUCKET1/bob/*`	The requester has access to all objects that have key names that start with the prefix `bob/` in the `DOC-EXAMPLE-BUCKET1` bucket.
`S3://DOC-EXAMPLE-BUCKET1/bob/*`	`DOC-EXAMPLE-BUCKET1/bob/`	`Minimal`	`DOC-EXAMPLE-BUCKET1/bob/`	Without a wild card * character after the prefix name `bob/`, the requester has access to only the object named `bob/` in the `DOC-EXAMPLE-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://DOC-EXAMPLE-BUCKET1/bob/*`	`DOC-EXAMPLE-BUCKET1/bob/images/*`	`Minimal`	`DOC-EXAMPLE-BUCKET1/bob/images/*`	The requester has access to all objects that have key names that start with the prefix `bob/images/*`in the `DOC-EXAMPLE-BUCKET1` bucket.
`S3://DOC-EXAMPLE-BUCKET1/bob/reports/*`	`DOC-EXAMPLE-BUCKET1/bob/reports/file.txt`	`Default`	`DOC-EXAMPLE-BUCKET1/bob/reports/*`	The requester has access to all objects that have key names that start with the `bob/reports` prefix in the `DOC-EXAMPLE-BUCKET1` bucket, which is the scope of the matching grant.
`S3://DOC-EXAMPLE-BUCKET1/bob/reports/*`	`DOC-EXAMPLE-BUCKET1/bob/reports/file.txt`	`Minimal`	`DOC-EXAMPLE-BUCKET1/bob/reports/file.txt`	The requester has access only to the object with the key name `bob/reports/file.txt` in the `DOC-EXAMPLE-BUCKET1` bucket. The requester has no access to any other object.

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.

For more information, see GetDataAccess in the Amazon Simple Storage Service API Reference.

You can request temporary credentials by using AWS Command Line Interface (AWS CLI), the Amazon S3 REST API, and the AWS SDKs.

To install the AWS CLI, see Installing the AWS CLI 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://DOC-EXAMPLE-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://DOC-EXAMPLE-BUCKET/prefixA**"
}

For information about the Amazon S3 REST API support for requesting temporary credentials from S3 Access Grants, see GetDataAccess in the Amazon Simple Storage Service API Reference.

This section provides an example of how grantees request temporary credentials from S3 Access Grants by using the AWS SDKs.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Delete a grant

Access S3 data through an access grant

Request access to Amazon S3 data through S3 Access Grants

Note

Example Request temporary credentials

Example Get temporary credentials