Menu
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

PUT Bucket cors

Description

Sets the cors configuration for your bucket. If the configuration exists, Amazon S3 replaces it.

To use this operation, you must be allowed to perform the s3:PutBucketCORS action. By default, the bucket owner has this permission and can grant it to others.

You set this configuration on a bucket so that the bucket can service cross-origin requests. For example, you might want to enable a request whose origin is http://www.example.com to access your Amazon S3 bucket at my.example.bucket.com by using the browser's XMLHttpRequest capability.

To enable cross-origin resource sharing (CORS) on a bucket, you add the cors subresource to the bucket. The cors subresource is an XML document in which you configure rules that identify origins and the HTTP methods that can be executed on your bucket. The document is limited to 64 KB in size. For example, the following cors configuration on a bucket has two rules:

  • The first CORSRule allows cross-origin PUT, POST and DELETE requests whose origin is https://www.example.com origins. The rule also allows all headers in a pre-flight OPTIONS request through the Access-Control-Request-Headers header. Therefore, in response to any pre-flight OPTIONS request, Amazon S3 will return any requested headers.

  • The second rule allows cross-origin GET requests from all the origins. The '*' wildcard character refers to all origins.

Copy
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> </CORSRule> <CORSRule> <AllowedOrigin>*</AllowedOrigin> <AllowedMethod>GET</AllowedMethod> </CORSRule> </CORSConfiguration>

The cors configuration also allows additional optional configuration parameters as shown in the following cors configuration on a bucket. For example, this cors configuration allows cross-origin PUT and POST requests from http://www.example.com.

Copy
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> <MaxAgeSeconds>3000</MaxAgeSeconds> <ExposeHeader>x-amz-server-side-encryption</ExposeHeader> </CORSRule> </CORSConfiguration>

In the preceding configuration, CORSRule includes the following additional optional parameters:

  • MaxAgeSeconds—Specifies the time in seconds that the browser will cache an Amazon S3 response to a pre-flight OPTIONS request for the specified resource. In this example, this parameter is 3000 seconds. Caching enables the browsers to avoid sending pre-flight OPTIONS request to Amazon S3 for repeated requests.

  • ExposeHeader—Identifies the response header (in this case x-amz-server-side-encryption) that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

When Amazon S3 receives a cross-origin request (or a pre-flight OPTIONS request) against a bucket, it evaluates the cors configuration on the bucket and uses the first CORSRule rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met:

  • The request's Origin header must match AllowedOrigin elements.

  • The request method (for example, GET, PUT, HEAD and so on) or the Access-Control-Request-Method header in case of a pre-flight OPTIONS request must be one of the AllowedMethod elements.

  • Every header specified in the Access-Control-Request-Headers request header of a pre-flight request must match an AllowedHeader element.

For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

Copy
PUT /?cors HTTP/1.1 Host: bucketname.s3.amazonaws.com Content-Length: length Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) Content-MD5: MD5 <CORSConfiguration> <CORSRule> <AllowedOrigin>Origin you want to allow cross-domain requests from</AllowedOrigin> <AllowedOrigin>...</AllowedOrigin> ... <AllowedMethod>HTTP method</AllowedMethod> <AllowedMethod>...</AllowedMethod> ... <MaxAgeSeconds>Time in seconds your browser to cache the pre-flight OPTIONS response for a resource</MaxAgeSeconds> <AllowedHeader>Headers that you want the browser to be allowed to send</AllowedHeader> <AllowedHeader>...</AllowedHeader> ... <ExposeHeader>Headers in the response that you want accessible from client application</ExposeHeader> <ExposeHeader>...</ExposeHeader> ... </CORSRule> <CORSRule> ... </CORSRule> ... </CORSConfiguration>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required
Content-MD5

The base64-encoded 128-bit MD5 digest of the data. This header must be used as a message integrity check to verify that the request body was not corrupted in transit. For more information, go to RFC 1864.

Type: String

Default: None

Yes

Request Elements

Name Description Required
CORSConfiguration

Container for up to 100 CORSRules elements.

Type: Container

Children: CORSRules

Ancestor: None

Yes
CORSRule

A set of origins and methods (cross-origin access that you want to allow). You can add up to 100 rules to the configuration.

Type: Container

Children: AllowedOrigin, AllowedMethod, MaxAgeSeconds, ExposeHeader, ID.

Ancestor: CORSConfiguration

Yes

ID

A unique identifier for the rule. The ID value can be up to 255 characters long. The IDs help you find a rule in the configuration.

Type: String

Ancestor: CORSRule

No

AllowedMethod

An HTTP method that you want to allow the origin to execute.

Each CORSRule must identify at least one origin and one method.

Type: Enum (GET, PUT, HEAD, POST, DELETE)

Ancestor: CORSRule

Yes

AllowedOrigin

An origin that you want to allow cross-domain requests from. This can contain at most one * wild character.

Each CORSRule must identify at least one origin and one method.

The origin value can include at most one '*' wild character. For example, "http://*.example.com". You can also specify only * as the origin value allowing all origins cross-domain access.

Type: String

Ancestor: CORSRule

Yes

AllowedHeader

Specifies which headers are allowed in a pre-flight OPTIONS request via the Access-Control-Request-Headers header. Each header name specified in the Access-Control-Request-Headers header must have a corresponding entry in the rule. Amazon S3 will send only the allowed headers in a response that were requested.

This can contain at most one * wild character.

Type: String

Ancestor: CORSRule

No
MaxAgeSeconds

The time in seconds that your browser is to cache the preflight response for the specified resource.

A CORSRule can have at most one MaxAgeSeconds element.

Type: Integer (seconds)

Ancestor: CORSRule

No
ExposeHeader

One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).

You add one ExposeHeader element in the rule for each header.

Type: String

Ancestor: CORSRule

No

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

The following examples add the cors subresource to a bucket.

Example : Configure cors

Sample Request

The following PUT request adds the cors subresource to a bucket (examplebucket).

Copy
PUT /?cors HTTP/1.1 Host: examplebucket.s3.amazonaws.com x-amz-date: Tue, 21 Aug 2012 17:54:50 GMT Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W== Authorization: authorization string Content-Length: 216 <CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> <MaxAgeSeconds>3000</MaxAgeSec> <ExposeHeader>x-amz-server-side-encryption</ExposeHeader> </CORSRule> <CORSRule> <AllowedOrigin>*</AllowedOrigin> <AllowedMethod>GET</AllowedMethod> <AllowedHeader>*</AllowedHeader> <MaxAgeSeconds>3000</MaxAgeSeconds> </CORSRule> </CORSConfiguration>

Sample Response

Copy
HTTP/1.1 200 OK x-amz-id-2: CCshOvbOPfxzhwOADyC4qHj/Ck3F9Q0viXKw3rivZ+GcBoZSOOahvEJfPisZB7B x-amz-request-id: BDC4B83DF5096BBE Date: Tue, 21 Aug 2012 17:54:50 GMT Server: AmazonS3