Authentication methods
Important
Unless you are using the Amazon SDKs or CLI, you must write code to calculate signatures that provide authentication information in your requests. Signature calculation in Amazon Signature Version 4 can be a complex undertaking, and we recommend that you use the Amazon SDKs or CLI whenever possible.
You can express authentication information by using one of the following methods.
HTTP authorization header
The HTTP Authorization header is the most common method of
authenticating a request. All REST API operations (except for browser-based uploads
using POST requests) require this header. For more information about
the authorization header value, and how to calculate signature and related options,
see Authenticating Requests: Using the Authorization Header (Amazon Signature
Version 4) in the Amazon S3 API Reference.
The following is an example of the Authorization header value. Line
breaks are added to this example for readability. In your code, the header must be a
continuous string. There is no comma between the algorithm and Credential, but the
other elements must be separated by commas.
Authorization: Amazon4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;range;x-amz-date, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
The following table describes the various components of the Authorization header value in the preceding example:
| Component | Description |
|---|---|
|
Authorization |
The algorithm that was used to calculate the signature. You
must provide this value when you use Amazon Signature Version 4
for authentication.The string specifies Amazon Signature Version
4 ( |
|
Credential |
Your access key ID and the scope information, which includes the date, Region, and service that were used to calculate the signature. This string has the following form:
Where: |
|
SignedHeaders |
A semicolon-separated list of request headers that you used to
compute |
|
Signature |
The 256-bit signature expressed as 64 lowercase hexadecimal
characters. For
example: Note that the signature calculations vary depending on the option you choose to transfer the payload. |
Query string parameters
You can use a query string to express a request entirely in a URL. In this case, you use query parameters to provide request information, including the authentication information. Because the request signature is part of the URL, this type of URL is often referred to as a presigned URL. You can use presigned URLs to embed clickable links in HTML, which can be valid for up to seven days. For more information, see Authenticating Requests: Using Query Parameters (Amazon Signature Version 4) in the Amazon S3 API Reference.
The following is an example presigned URL. Line breaks are added to this example for readability:
https://s3.amazonaws.com/examplebucket/test.txt ? X-Amz-Algorithm=AWS4-HMAC-SHA256 & X-Amz-Credential=<your-access-key-id>/20130721/us-east-1/s3/aws4_request & X-Amz-Date=20130721T201207Z & X-Amz-Expires=86400 & X-Amz-SignedHeaders=host &X-Amz-Signature=<signature-value>
Note
The X-Amz-Credential value in the URL shows the "/" character
only for readability. In practice, it should be encoded as %2F. For
example:
&X-Amz-Credential=<your-access-key-id>%2F20130721%2Fus-east-1%2Fs3%2Faws4_request
The following table describes the query parameters in the URL that provide authentication information.
| Query string parameter name | Description |
|---|---|
|
X-Amz-Algorithm |
Identifies the version of Amazon Signature and the algorithm
that you used to calculate the signature.For Amazon Signature
Version 4, you set this parameter value to
|
|
X-Amz-Credential |
In addition to your access key ID, this parameter also provides scope (Amazon Region and service) for which the signature is valid. This value must match the scope you use in signature calculations, discussed in the following section. The general form for this parameter value is as follows:
For example:
For a list of Amazon regional strings, see Regional Endpoints in the Amazon General Reference. |
|
X-Amz-Date |
The date and time format must follow the ISO 8601 standard,
and must be formatted with the |
|
X-Amz-Expires |
Provides the time period, in seconds, for which the generated presigned URL is valid. For example, 86400 (24 hours). This value is an integer. The minimum value you can set is 1, and the maximum is 604800 (seven days).A presigned URL can be valid for a maximum of seven days because the signing key you use in signature calculation is valid for up to seven days. |
|
X-Amz-SignedHeaders |
Lists the headers that you used to calculate the signature. The following headers are required in the signature calculations:
For added security, you should sign all the request headers that you plan to include in your request. |
|
X-Amz-Signature |
Provides the signature to authenticate your request. This
signature must match the signature the service calculates;
otherwise, the service denies the request. For example,
Signature calculations are described in the following section. |
|
X-Amz-Security-Token |
Optional credential parameter if using credentials sourced from the STS service. |