PUT Bucket CORS

Description

You can call this operation to configure CORS settings for your bucket. If the settings exist, KS3 replaces them.

To call this operation, you must have permission to perform the PutBucketCORS operation. The owner of a bucket has this permission by default and can grant it to others.

By configuring CORS settings for your bucket, you enable your bucket to respond to requests from different origins. For example, you can call this operation if you want to enable a request whose origin is http://www.example.com to access your KS3 bucket at my.example.bucket.com by using the XMLHttpRequest capability of the browser.

To enable CORS for your bucket, you must create a CORS configuration file in XML format. The file contains rules that identify the allowed origins, the supported HTTP methods for each origin, and information related to other operations. You can add up to 100 rules to a configuration file. Add the XML file as a CORS subresource to the bucket. The file cannot exceed 64 KB in size.

For example, the following CORS configuration contains two CORSRule elements, each specifying a CORS rule.

• The first rule allows cross-origin PUT, POST, and DELETE requests from the origin https://www.example.com. The rule also uses Access-Control-Request-Headers to allow all headers in an OPTIONS preflight request. KS3 returns a requested header to OPTIONS preflight requests.
• The second rule allows CORS requests from all origins by using the GET method. The asterisk (*) indicates all origins.

<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>

You can also set optional parameters to configure CORS settings for your bucket. For example, the following CORS rule allows CORS requests sent from the origin http://www.example.com by using the PUT and POST methods.

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

In the preceding example, the CORS rule contains the following optional parameters:

• MaxAgeSeconds: the period of time in seconds within which the browser caches the response of KS3 for an OPTIONS preflight request to specified resources. In the preceding example, this parameter is set to 3000. By caching the response, the browser does not need to send preflight requests to KS3 if the original request needs to be repeated.
• ExposeHeader: the response header that you are allowed to access from an application, such as from a JavaScript XMLHttpRequest object. In the preceding example, this parameter is set to x-kss-server-side-encryption.

When KS3 receives a cross-origin request for a bucket, it checks whether the request matches the configured CORS rules. For a rule to match a request, the following conditions must be met:

• The origin header of the request must match the AllowedOrigin elements in the CORS rule.
• The request method such as PUT, GET, and HEAD, or the Access-Control-Request-Method header header of an OPTIONS preflight request must match one of the AllowedMethod elements.
• Each header specified in Access-Control-Request-Headers of an OPTIONS preflight request must match an AllowedHeader element.

Request

Request syntax

PUT /?cors HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}
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>

References:

• Endpoint and Region
• Request Signature V4

Request parameters

No request parameter is used.

Request headers

This operation uses only common request headers. For more information, see Public Request Header.

Request body

Response

Response headers

This operation uses only common response headers. For more information, see Public Response Header.

Response body

No response body is returned.

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

PUT /?cors HTTP/1.1
Content-MD5: /QO8JEkpekFaAuWWEKS7Fg==
Date: Thu, 15 Jun 2017 02:32:02 GMT
Authorization: authorization string
Content-Length: 652
Host: ks3-example.ks3-cn-beijing.ksyuncs.com

<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
<AllowedMethod>GET</AllowedMethod>
<AllowedOrigin>http://baidu.com</AllowedOrigin>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
<CORSRule>
<AllowedMethod>POST</AllowedMethod>
<AllowedOrigin>http://*ks3.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://*ks3.console.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://*ks3.ksyun.com</AllowedOrigin>
<AllowedOrigin>https://www.example.com</AllowedOrigin>
<AllowedOrigin>http://*ks3.console.ksyun.com</AllowedOrigin>
<AllowedHeader>*</AllowedHeader>
</CORSRule>
</CORSConfiguration>

Sample response

HTTP/1.1 200 OK
Server: Tengine
Date: Thu, 15 Jun 2017 02:32:56 GMT
Content-Length: 0
X-Application-Context: application
x-kss-request-id: 94def5b819f74135a1df54e6cf422f64