Interface S3Presigner
-
- All Superinterfaces:
AutoCloseable
,SdkAutoCloseable
,SdkPresigner
- All Known Implementing Classes:
DefaultS3Presigner
@Immutable @ThreadSafe public interface S3Presigner extends SdkPresigner
Enables signing an S3SdkRequest
so that it can be executed without requiring any additional authentication on the part of the caller. For example: if Alice has access to an S3 object, and she wants to temporarily share access to that object with Bob, she can generate a pre-signedGetObjectRequest
to secure share with Bob so that he can download the object without requiring access to Alice's credentials.Signature Duration
Pre-signed requests are only valid for a finite period of time, referred to as the signature duration. This signature duration is configured when the request is generated, and cannot be longer than 7 days. Attempting to generate a signature longer than 7 days in the future will fail at generation time. Attempting to use a pre-signed request after the signature duration has passed will result in an access denied response from the service.Example Usage
// Create an S3Presigner using the default region and credentials. // This is usually done at application startup, because creating a presigner can be expensive. S3Presigner presigner = S3Presigner.create(); // Create a GetObjectRequest to be pre-signed GetObjectRequest getObjectRequest = GetObjectRequest.builder() .bucket("my-bucket") .key("my-key") .build(); // Create a GetObjectPresignRequest to specify the signature duration GetObjectPresignRequest getObjectPresignRequest = GetObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .getObjectRequest(getObjectRequest) .build(); // Generate the presigned request PresignedGetObjectRequest presignedGetObjectRequest = presigner.presignGetObject(getObjectPresignRequest); // Log the presigned URL, for example. System.out.println("Presigned URL: " + presignedGetObjectRequest.url()); // It is recommended to close the S3Presigner when it is done being used, because some credential // providers (e.g. if your AWS profile is configured to assume an STS role) require system resources // that need to be freed. If you are using one S3Presigner per application (as recommended), this // usually is not needed. presigner.close();
Browser Compatibility
Some pre-signed requests can be executed by a web browser. These "browser compatible" pre-signed requests do not require the customer to send anything other than a "host" header when performing an HTTP GET against the pre-signed URL. Whether a pre-signed request is "browser compatible" can be determined by checking thePresignedRequest.isBrowserExecutable()
flag. It is recommended to always check this flag when the pre-signed request needs to be executed by a browser, because some request fields will result in the pre-signed request not being browser-compatible.Configurations that affect browser compatibility
Enabling Checking Validation
If checksum validations are enabled, the presigned URL will no longer be browser compatible because it adds a signed header that must be included in the HTTP request. Checksum validation is disabled in the presigner by default, but when using a customS3Configuration
when enabling features like path style access or accelerate mode, it must be explicitly disabled:S3Presigner presigner = S3Presigner.builder() .serviceConfiguration(S3Configuration.builder() .checksumValidationEnabled(false) .build()) .build();
Executing a Pre-Signed Request from Java code
Browser-compatible requests (see above) can be executed using a web browser. All pre-signed requests can be executed from Java code. This documentation describes two methods for executing a pre-signed request: (1) using the JDK'sURLConnection
class, (2) using an SDK synchronousSdkHttpClient
class. Using {code URLConnection}:// Create a pre-signed request using one of the "presign" methods on S3Presigner PresignedRequest presignedRequest = ...; // Create a JDK HttpURLConnection for communicating with S3 HttpURLConnection connection = (HttpURLConnection) presignedRequest.url().openConnection(); // Specify any headers that are needed by the service (not needed when isBrowserExecutable is true) presignedRequest.httpRequest().headers().forEach((header, values) -> { values.forEach(value -> { connection.addRequestProperty(header, value); }); }); // Send any request payload that is needed by the service (not needed when isBrowserExecutable is true) if (presignedRequest.signedPayload().isPresent()) { connection.setDoOutput(true); try (InputStream signedPayload = presignedRequest.signedPayload().get().asInputStream(); OutputStream httpOutputStream = connection.getOutputStream()) { IoUtils.copy(signedPayload, httpOutputStream); } } // Download the result of executing the request try (InputStream content = connection.getInputStream()) { System.out.println("Service returned response: "); IoUtils.copy(content, System.out); }
Using {code SdkHttpClient}:// Create a pre-signed request using one of the "presign" methods on S3Presigner PresignedRequest presignedRequest = ...; // Create an SdkHttpClient using one of the implementations provided by the SDK SdkHttpClient httpClient = ApacheHttpClient.builder().build(); // or UrlConnectionHttpClient.create() // Specify any request payload that is needed by the service (not needed when isBrowserExecutable is true) ContentStreamProvider requestPayload = presignedRequest.signedPayload() .map(SdkBytes::asContentStreamProvider) .orElse(null); // Create the request for sending to the service HttpExecuteRequest request = HttpExecuteRequest.builder() .request(presignedRequest.httpRequest()) .contentStreamProvider(requestPayload) .build(); // Call the service HttpExecuteResponse response = httpClient.prepareRequest(request).call(); // Download the result of executing the request if (response.responseBody().isPresent()) { try (InputStream responseStream = response.responseBody().get()) { System.out.println("Service returned response: "); IoUtils.copy(content, System.out); } }
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
S3Presigner.Builder
A builder for creatingS3Presigner
s.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description static S3Presigner.Builder
builder()
Create anS3Presigner.Builder
that can be used to configure and create aS3Presigner
.static S3Presigner
create()
Create anS3Presigner
with default configuration.default PresignedAbortMultipartUploadRequest
presignAbortMultipartUpload(Consumer<AbortMultipartUploadPresignRequest.Builder> request)
Presign aAbortMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedAbortMultipartUploadRequest
presignAbortMultipartUpload(AbortMultipartUploadPresignRequest request)
Presign aAbortMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedCompleteMultipartUploadRequest
presignCompleteMultipartUpload(Consumer<CompleteMultipartUploadPresignRequest.Builder> request)
Presign aCompleteMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedCompleteMultipartUploadRequest
presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest request)
Presign aCompleteMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedCreateMultipartUploadRequest
presignCreateMultipartUpload(Consumer<CreateMultipartUploadPresignRequest.Builder> request)
Presign aCreateMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedCreateMultipartUploadRequest
presignCreateMultipartUpload(CreateMultipartUploadPresignRequest request)
Presign aCreateMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedDeleteObjectRequest
presignDeleteObject(Consumer<DeleteObjectPresignRequest.Builder> request)
Presign aDeleteObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedDeleteObjectRequest
presignDeleteObject(DeleteObjectPresignRequest request)
Presign aDeleteObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedGetObjectRequest
presignGetObject(Consumer<GetObjectPresignRequest.Builder> request)
Presign aGetObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedGetObjectRequest
presignGetObject(GetObjectPresignRequest request)
Presign aGetObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedPutObjectRequest
presignPutObject(Consumer<PutObjectPresignRequest.Builder> request)
Presign aPutObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedPutObjectRequest
presignPutObject(PutObjectPresignRequest request)
Presign aPutObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.default PresignedUploadPartRequest
presignUploadPart(Consumer<UploadPartPresignRequest.Builder> request)
Presign aUploadPartRequest
so that it can be executed at a later time without requiring additional signing or authentication.PresignedUploadPartRequest
presignUploadPart(UploadPartPresignRequest request)
Presign aUploadPartRequest
so that it can be executed at a later time without requiring additional signing or authentication.-
Methods inherited from interface software.amazon.awssdk.awscore.presigner.SdkPresigner
close
-
-
-
-
Method Detail
-
create
static S3Presigner create()
Create anS3Presigner
with default configuration. The region will be loaded from theDefaultAwsRegionProviderChain
and credentials will be loaded from theDefaultCredentialsProvider
. This is usually done at application startup, because creating a presigner can be expensive. It is recommended toSdkPresigner.close()
theS3Presigner
when it is done being used.
-
builder
static S3Presigner.Builder builder()
Create anS3Presigner.Builder
that can be used to configure and create aS3Presigner
. This is usually done at application startup, because creating a presigner can be expensive. It is recommended toSdkPresigner.close()
theS3Presigner
when it is done being used.
-
presignGetObject
PresignedGetObjectRequest presignGetObject(GetObjectPresignRequest request)
Presign aGetObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication. Example UsageS3Presigner presigner = ...; // Create a GetObjectRequest to be pre-signed GetObjectRequest getObjectRequest = ...; // Create a GetObjectPresignRequest to specify the signature duration GetObjectPresignRequest getObjectPresignRequest = GetObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .getObjectRequest(request) .build(); // Generate the presigned request PresignedGetObjectRequest presignedGetObjectRequest = presigner.presignGetObject(getObjectPresignRequest); if (presignedGetObjectRequest.isBrowserExecutable()) System.out.println("The pre-signed request can be executed using a web browser by " + "visiting the following URL: " + presignedGetObjectRequest.url()); else System.out.println("The pre-signed request has an HTTP method, headers or a payload " + "that prohibits it from being executed by a web browser. See the S3Presigner " + "class-level documentation for an example of how to execute this pre-signed " + "request from Java code.");
-
presignGetObject
default PresignedGetObjectRequest presignGetObject(Consumer<GetObjectPresignRequest.Builder> request)
Presign aGetObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication. This is a shorter method of invokingpresignGetObject(GetObjectPresignRequest)
without needing to callGetObjectPresignRequest.builder()
or.build()
.
-
presignPutObject
PresignedPutObjectRequest presignPutObject(PutObjectPresignRequest request)
Presign aPutObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Create a PutObjectRequest to be pre-signed PutObjectRequest putObjectRequest = ...; // Create a PutObjectPresignRequest to specify the signature duration PutObjectPresignRequest putObjectPresignRequest = PutObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .putObjectRequest(request) .build(); // Generate the presigned request PresignedPutObjectRequest presignedPutObjectRequest = presigner.presignPutObject(putObjectPresignRequest);
-
presignPutObject
default PresignedPutObjectRequest presignPutObject(Consumer<PutObjectPresignRequest.Builder> request)
Presign aPutObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignPutObject(PutObjectPresignRequest)
without needing to callPutObjectPresignRequest.builder()
or.build()
.
-
presignDeleteObject
PresignedDeleteObjectRequest presignDeleteObject(DeleteObjectPresignRequest request)
Presign aDeleteObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Create a DeleteObjectRequest to be pre-signed DeleteObjectRequest deleteObjectRequest = ...; // Create a PutObjectPresignRequest to specify the signature duration DeleteObjectPresignRequest deleteObjectPresignRequest = DeleteObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .deleteObjectRequest(deleteObjectRequest) .build(); // Generate the presigned request PresignedDeleteObjectRequest presignedDeleteObjectRequest = presigner.presignDeleteObject(deleteObjectPresignRequest);
-
presignDeleteObject
default PresignedDeleteObjectRequest presignDeleteObject(Consumer<DeleteObjectPresignRequest.Builder> request)
Presign aDeleteObjectRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignDeleteObject(DeleteObjectPresignRequest)
without needing to callDeleteObjectPresignRequest.builder()
or.build()
.- See Also:
#presignDeleteObject(PresignedDeleteObjectRequest)
-
presignCreateMultipartUpload
PresignedCreateMultipartUploadRequest presignCreateMultipartUpload(CreateMultipartUploadPresignRequest request)
Presign aCreateMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Create a CreateMultipartUploadRequest to be pre-signed CreateMultipartUploadRequest createMultipartUploadRequest = ...; // Create a CreateMultipartUploadPresignRequest to specify the signature duration CreateMultipartUploadPresignRequest createMultipartUploadPresignRequest = CreateMultipartUploadPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .createMultipartUploadRequest(request) .build(); // Generate the presigned request PresignedCreateMultipartUploadRequest presignedCreateMultipartUploadRequest = presigner.presignCreateMultipartUpload(createMultipartUploadPresignRequest);
-
presignCreateMultipartUpload
default PresignedCreateMultipartUploadRequest presignCreateMultipartUpload(Consumer<CreateMultipartUploadPresignRequest.Builder> request)
Presign aCreateMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignCreateMultipartUpload(CreateMultipartUploadPresignRequest)
without needing to callCreateMultipartUploadPresignRequest.builder()
or.build()
.
-
presignUploadPart
PresignedUploadPartRequest presignUploadPart(UploadPartPresignRequest request)
Presign aUploadPartRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Create a UploadPartRequest to be pre-signed UploadPartRequest uploadPartRequest = ...; // Create a UploadPartPresignRequest to specify the signature duration UploadPartPresignRequest uploadPartPresignRequest = UploadPartPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .uploadPartRequest(request) .build(); // Generate the presigned request PresignedUploadPartRequest presignedUploadPartRequest = presigner.presignUploadPart(uploadPartPresignRequest);
-
presignUploadPart
default PresignedUploadPartRequest presignUploadPart(Consumer<UploadPartPresignRequest.Builder> request)
Presign aUploadPartRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignUploadPart(UploadPartPresignRequest)
without needing to callUploadPartPresignRequest.builder()
or.build()
.
-
presignCompleteMultipartUpload
PresignedCompleteMultipartUploadRequest presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest request)
Presign aCompleteMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Complete a CompleteMultipartUploadRequest to be pre-signed CompleteMultipartUploadRequest completeMultipartUploadRequest = ...; // Create a CompleteMultipartUploadPresignRequest to specify the signature duration CompleteMultipartUploadPresignRequest completeMultipartUploadPresignRequest = CompleteMultipartUploadPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .completeMultipartUploadRequest(request) .build(); // Generate the presigned request PresignedCompleteMultipartUploadRequest presignedCompleteMultipartUploadRequest = presigner.presignCompleteMultipartUpload(completeMultipartUploadPresignRequest);
-
presignCompleteMultipartUpload
default PresignedCompleteMultipartUploadRequest presignCompleteMultipartUpload(Consumer<CompleteMultipartUploadPresignRequest.Builder> request)
Presign aCompleteMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest)
without needing to callCompleteMultipartUploadPresignRequest.builder()
or.build()
.
-
presignAbortMultipartUpload
PresignedAbortMultipartUploadRequest presignAbortMultipartUpload(AbortMultipartUploadPresignRequest request)
Presign aAbortMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.Example Usage
S3Presigner presigner = ...; // Complete a AbortMultipartUploadRequest to be pre-signed AbortMultipartUploadRequest abortMultipartUploadRequest = ...; // Create a AbortMultipartUploadPresignRequest to specify the signature duration AbortMultipartUploadPresignRequest abortMultipartUploadPresignRequest = AbortMultipartUploadPresignRequest.builder() .signatureDuration(Duration.ofMinutes(10)) .abortMultipartUploadRequest(request) .build(); // Generate the presigned request PresignedAbortMultipartUploadRequest presignedAbortMultipartUploadRequest = presigner.presignAbortMultipartUpload(abortMultipartUploadPresignRequest);
-
presignAbortMultipartUpload
default PresignedAbortMultipartUploadRequest presignAbortMultipartUpload(Consumer<AbortMultipartUploadPresignRequest.Builder> request)
Presign aAbortMultipartUploadRequest
so that it can be executed at a later time without requiring additional signing or authentication.This is a shorter method of invoking
presignAbortMultipartUpload(AbortMultipartUploadPresignRequest)
without needing to callAbortMultipartUploadPresignRequest.builder()
or.build()
.
-
-