Create Session
s3_create_session | R Documentation |
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint APIs on directory buckets¶
Description¶
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint APIs on directory buckets. For more information about Zonal endpoint APIs that include the Availability Zone in the request endpoint, see S3 Express One Zone APIs in the Amazon S3 User Guide.
To make Zonal endpoint API requests on a directory bucket, use the
create_session
API operation. Specifically, you grant
s3express:CreateSession
permission to a bucket in a bucket policy or
an IAM identity-based policy. Then, you use IAM credentials to make the
create_session
API request on the bucket, which returns temporary
security credentials that include the access key ID, secret access key,
session token, and expiration. These credentials have associated
permissions to access the Zonal endpoint APIs. After the session is
created, you don’t need to use other policies to grant permissions to
each Zonal endpoint API individually. Instead, in your Zonal endpoint
API requests, you sign your requests by applying the temporary security
credentials of the session to the request headers and following the
SigV4 protocol for authentication. You also apply the session token to
the x-amz-s3session-token
request header for authorization. Temporary
security credentials are scoped to the bucket and expire after 5
minutes. After the expiration time, any calls that you make with those
credentials will fail. You must use IAM credentials again to make a
create_session
API request that generates a new set of temporary
credentials for use. Temporary credentials cannot be extended or
refreshed beyond the original specified interval.
If you use Amazon Web Services SDKs, SDKs handle the session token refreshes automatically to avoid service interruptions when a session expires. We recommend that you use the Amazon Web Services SDKs to initiate and manage requests to the CreateSession API. For more information, see Performance guidelines and design patterns in the Amazon S3 User Guide.
-
You must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide. -
copy_object
API operation - Unlike other Zonal endpoint APIs, thecopy_object
API operation doesn't use the temporary security credentials returned from thecreate_session
API operation for authentication and authorization. For information about authentication and authorization of thecopy_object
API operation on directory buckets, seecopy_object
. -
head_bucket
API operation - Unlike other Zonal endpoint APIs, thehead_bucket
API operation doesn't use the temporary security credentials returned from thecreate_session
API operation for authentication and authorization. For information about authentication and authorization of thehead_bucket
API operation on directory buckets, seehead_bucket
.
Permissions¶
To obtain temporary security credentials, you must create a bucket
policy or an IAM identity-based policy that grants
s3express:CreateSession
permission to the bucket. In a policy, you can
have the s3express:SessionMode
condition key to control who can create
a ReadWrite
or ReadOnly
session. For more information about
ReadWrite
or ReadOnly
sessions, see
x-amz-create-session-mode
. For example policies, see Example bucket policies for S3 Express One
Zone
and Amazon Web Services Identity and Access Management (IAM)
identity-based policies for S3 Express One
Zone
in the Amazon S3 User Guide.
To grant cross-account access to Zonal endpoint APIs, the bucket policy
should also grant both accounts the s3express:CreateSession
permission.
HTTP Host header syntax¶
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
Usage¶
Arguments¶
SessionMode
Specifies the mode of the session that will be created, either
ReadWrite
orReadOnly
. By default, aReadWrite
session is created. AReadWrite
session is capable of executing all the Zonal endpoint APIs on a directory bucket. AReadOnly
session is constrained to execute the following Zonal endpoint APIs:get_object
,head_object
,list_objects_v2
,get_object_attributes
,list_parts
, andlist_multipart_uploads
.Bucket
[required] The name of the bucket that you create a session for.
Value¶
A list with the following syntax:
list(
Credentials = list(
AccessKeyId = "string",
SecretAccessKey = "string",
SessionToken = "string",
Expiration = as.POSIXct(
"2015-01-01"
)
)
)