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 API operations on directory buckets¶
Description¶
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint API operations on directory buckets. For more information about Zonal endpoint API operations 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 API operations. 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-zone-id.region-code.amazonaws.com
. Path-style requests are not supported. For more information about endpoints in Availability Zones, see Regional and Zonal endpoints for directory buckets in Availability Zones in the Amazon S3 User Guide. For more information about endpoints in Local Zones, see Available Local Zone for directory buckets in the Amazon S3 User Guide. -
copy_object
API operation - Unlike other Zonal endpoint API operations, 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 API operations, 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 API operations, the
bucket policy should also grant both accounts the
s3express:CreateSession
permission.
If you want to encrypt objects with SSE-KMS, you must also have the
kms:GenerateDataKey
and the kms:Decrypt
permissions in IAM
identity-based policies and KMS key policies for the target KMS key.
Encryption¶
For directory buckets, there are only two supported options for
server-side encryption: server-side encryption with Amazon S3 managed
keys (SSE-S3) (AES256
) and server-side encryption with KMS keys
(SSE-KMS) (aws:kms
). We recommend that the bucket's default encryption
uses the desired encryption configuration and you don't override the
bucket default encryption in your create_session
requests or PUT
object requests. Then, new objects are automatically encrypted with the
desired encryption settings. For more information, see Protecting data
with server-side
encryption in
the Amazon S3 User Guide. For more information about the encryption
overriding behaviors in directory buckets, see Specifying server-side
encryption with KMS for new object
uploads.
For Zonal endpoint (object-level) API
operations
except copy_object
and upload_part_copy
, you authenticate and
authorize requests through create_session
for low latency. To encrypt
new objects in a directory bucket with SSE-KMS, you must specify SSE-KMS
as the directory bucket's default encryption configuration with a KMS
key (specifically, a customer managed
key).
Then, when a session is created for Zonal endpoint API operations, new
objects are automatically encrypted and decrypted with SSE-KMS and S3
Bucket Keys during the session.
Only 1 customer managed
key
is supported per directory bucket for the lifetime of the bucket. The
Amazon Web Services managed
key
(aws/s3
) isn't supported. After you specify SSE-KMS as your bucket's
default encryption configuration with a customer managed key, you can't
change the customer managed key for the bucket's SSE-KMS configuration.
In the Zonal endpoint API calls (except copy_object
and
upload_part_copy
) using the REST API, you can't override the values of
the encryption settings (x-amz-server-side-encryption
,
x-amz-server-side-encryption-aws-kms-key-id
,
x-amz-server-side-encryption-context
, and
x-amz-server-side-encryption-bucket-key-enabled
) from the
create_session
request. You don't need to explicitly specify these
encryption settings values in Zonal endpoint API calls, and Amazon S3
will use the encryption settings values from the create_session
request to protect new objects in the directory bucket.
When you use the CLI or the Amazon Web Services SDKs, for
create_session
, the session token refreshes automatically to avoid
service interruptions when a session expires. The CLI or the Amazon Web
Services SDKs use the bucket's default encryption configuration for the
create_session
request. It's not supported to override the encryption
settings values in the create_session
request. Also, in the Zonal
endpoint API calls (except copy_object
and upload_part_copy
), it's
not supported to override the values of the encryption settings from the
create_session
request.
HTTP Host header syntax¶
Directory buckets - The HTTP Host header syntax is
Bucket-name.s3express-zone-id.region-code.amazonaws.com
.
Usage¶
s3_create_session(SessionMode, Bucket, ServerSideEncryption,
SSEKMSKeyId, SSEKMSEncryptionContext, BucketKeyEnabled)
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 API operations on a directory bucket. AReadOnly
session is constrained to execute the following Zonal endpoint API operations: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.
ServerSideEncryption
The server-side encryption algorithm to use when you store objects in the directory bucket.
For directory buckets, there are only two supported options for server-side encryption: server-side encryption with Amazon S3 managed keys (SSE-S3) (
AES256
) and server-side encryption with KMS keys (SSE-KMS) (aws:kms
). By default, Amazon S3 encrypts data with SSE-S3. For more information, see Protecting data with server-side encryption in the Amazon S3 User Guide.SSEKMSKeyId
If you specify
x-amz-server-side-encryption
withaws:kms
, you must specify thex-amz-server-side-encryption-aws-kms-key-id
header with the ID (Key ID or Key ARN) of the KMS symmetric encryption customer managed key to use. Otherwise, you get an HTTP400 Bad Request
error. Only use the key ID or key ARN. The key alias format of the KMS key isn't supported. Also, if the KMS key doesn't exist in the same account that't issuing the command, you must use the full Key ARN not the Key ID.Your SSE-KMS configuration can only support 1 customer managed key per directory bucket for the lifetime of the bucket. The Amazon Web Services managed key (
aws/s3
) isn't supported.SSEKMSEncryptionContext
Specifies the Amazon Web Services KMS Encryption Context as an additional encryption context to use for object encryption. The value of this header is a Base64 encoded string of a UTF-8 encoded JSON, which contains the encryption context as key-value pairs. This value is stored as object metadata and automatically gets passed on to Amazon Web Services KMS for future
get_object
operations on this object.General purpose buckets - This value must be explicitly added during
copy_object
operations if you want an additional encryption context for your object. For more information, see Encryption context in the Amazon S3 User Guide.Directory buckets - You can optionally provide an explicit encryption context value. The value must match the default encryption context - the bucket Amazon Resource Name (ARN). An additional encryption context value is not supported.
BucketKeyEnabled
Specifies whether Amazon S3 should use an S3 Bucket Key for object encryption with server-side encryption using KMS keys (SSE-KMS).
S3 Bucket Keys are always enabled for
GET
andPUT
operations in a directory bucket and can’t be disabled. S3 Bucket Keys aren't supported, when you copy SSE-KMS encrypted objects from general purpose buckets to directory buckets, from directory buckets to general purpose buckets, or between directory buckets, throughcopy_object
,upload_part_copy
, the Copy operation in Batch Operations, or the import jobs. In this case, Amazon S3 makes a call to KMS every time a copy request is made for a KMS-encrypted object.
Value¶
A list with the following syntax:
list(
ServerSideEncryption = "AES256"|"aws:kms"|"aws:kms:dsse",
SSEKMSKeyId = "string",
SSEKMSEncryptionContext = "string",
BucketKeyEnabled = TRUE|FALSE,
Credentials = list(
AccessKeyId = "string",
SecretAccessKey = "string",
SessionToken = "string",
Expiration = as.POSIXct(
"2015-01-01"
)
)
)