software.amazon.awssdk.services.s3.presigner

Interface S3Presigner

All Superinterfaces:

AutoCloseable, SdkAutoCloseable, SdkPresigner

All Known Implementing Classes:

DefaultS3Presigner

@Immutable
 @ThreadSafe
public interface S3Presigner
extends SdkPresigner

Enables signing an S3 SdkRequest 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-signed GetObjectRequest 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(request)
                                .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 the PresignedRequest.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.

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's URLConnection class, (2) using an SDK synchronous SdkHttpClient 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 and Description
static interface	S3Presigner.Builder A builder for creating S3Presigners.

Method Summary

Modifier and Type	Method and Description
static S3Presigner.Builder	builder() Create an S3Presigner.Builder that can be used to configure and create a S3Presigner.
static S3Presigner	create() Create an S3Presigner with default configuration.
PresignedAbortMultipartUploadRequest	presignAbortMultipartUpload(AbortMultipartUploadPresignRequest request) Presign a AbortMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedAbortMultipartUploadRequest	presignAbortMultipartUpload(Consumer<AbortMultipartUploadPresignRequest.Builder> request) Presign a AbortMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
PresignedCompleteMultipartUploadRequest	presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest request) Presign a CompleteMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedCompleteMultipartUploadRequest	presignCompleteMultipartUpload(Consumer<CompleteMultipartUploadPresignRequest.Builder> request) Presign a CompleteMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedCreateMultipartUploadRequest	presignCreateMultipartUpload(Consumer<CreateMultipartUploadPresignRequest.Builder> request) Presign a CreateMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
PresignedCreateMultipartUploadRequest	presignCreateMultipartUpload(CreateMultipartUploadPresignRequest request) Presign a CreateMultipartUploadRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedGetObjectRequest	presignGetObject(Consumer<GetObjectPresignRequest.Builder> request) Presign a GetObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.
PresignedGetObjectRequest	presignGetObject(GetObjectPresignRequest request) Presign a GetObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedPutObjectRequest	presignPutObject(Consumer<PutObjectPresignRequest.Builder> request) Presign a PutObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.
PresignedPutObjectRequest	presignPutObject(PutObjectPresignRequest request) Presign a PutObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.
default PresignedUploadPartRequest	presignUploadPart(Consumer<UploadPartPresignRequest.Builder> request) Presign a UploadPartRequest so that it can be executed at a later time without requiring additional signing or authentication.
PresignedUploadPartRequest	presignUploadPart(UploadPartPresignRequest request) Presign a UploadPartRequest 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 an S3Presigner with default configuration. The region will be loaded from the DefaultAwsRegionProviderChain and credentials will be loaded from the DefaultCredentialsProvider.

This is usually done at application startup, because creating a presigner can be expensive. It is recommended to SdkPresigner.close() the S3Presigner when it is done being used.

builder

static S3Presigner.Builder builder()

Create an S3Presigner.Builder that can be used to configure and create a S3Presigner.

This is usually done at application startup, because creating a presigner can be expensive. It is recommended to SdkPresigner.close() the S3Presigner when it is done being used.

presignGetObject

PresignedGetObjectRequest presignGetObject(GetObjectPresignRequest request)

Presign a GetObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.

Example Usage

 
     S3Presigner 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 a GetObjectRequest so that it can be executed at a later time without requiring additional signing or authentication.

This is a shorter method of invoking presignGetObject(GetObjectPresignRequest) without needing to call GetObjectPresignRequest.builder() or .build().

See Also:

presignGetObject(GetObjectPresignRequest)

presignPutObject

PresignedPutObjectRequest presignPutObject(PutObjectPresignRequest request)

Presign a PutObjectRequest 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 a PutObjectRequest 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 call PutObjectPresignRequest.builder() or .build().

See Also:

presignPutObject(PutObjectPresignRequest)

presignCreateMultipartUpload

PresignedCreateMultipartUploadRequest presignCreateMultipartUpload(CreateMultipartUploadPresignRequest request)

Presign a CreateMultipartUploadRequest 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 a CreateMultipartUploadRequest 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 call CreateMultipartUploadPresignRequest.builder() or .build().

See Also:

presignCreateMultipartUpload(CreateMultipartUploadPresignRequest)

presignUploadPart

PresignedUploadPartRequest presignUploadPart(UploadPartPresignRequest request)

Presign a UploadPartRequest 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 a UploadPartRequest 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 call UploadPartPresignRequest.builder() or .build().

See Also:

presignUploadPart(UploadPartPresignRequest)

presignCompleteMultipartUpload

PresignedCompleteMultipartUploadRequest presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest request)

Presign a CompleteMultipartUploadRequest 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 a CompleteMultipartUploadRequest 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 call CompleteMultipartUploadPresignRequest.builder() or .build().

See Also:

presignCompleteMultipartUpload(CompleteMultipartUploadPresignRequest)

presignAbortMultipartUpload

PresignedAbortMultipartUploadRequest presignAbortMultipartUpload(AbortMultipartUploadPresignRequest request)

Presign a AbortMultipartUploadRequest 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 a AbortMultipartUploadRequest 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 call AbortMultipartUploadPresignRequest.builder() or .build().

See Also:

presignAbortMultipartUpload(AbortMultipartUploadPresignRequest)