Sets a CORS rule for a specified bucket. If a rule has been set for the bucket, it is overwritten.

Request syntax

PUT /?cors HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
    <CORSRule>
      <AllowedOrigin>the origin you want allow CORS request from</AllowedOrigin>
      <AllowedOrigin>…</AllowedOrigin>
      <AllowedMethod>HTTP method</AllowedMethod>
      <AllowedMethod>…</AllowedMethod>
        <AllowedHeader> headers that allowed browser to send</AllowedHeader>
          <AllowedHeader>…</AllowedHeader>
          <ExposeHeader> headers in response that can access from client app</ExposeHeader>
          <ExposeHeader>…</ExposeHeader>
          <MaxAgeSeconds>time to cache pre-fight response</MaxAgeSeconds>
    </CORSRule>
    <CORSRule>
      …
    </CORSRule>
…
</CORSConfiguration >

Request elements

Element Type Required Description
CORSRule Container Yes Specifies the container that stores CORS rules. A maximum of 10 rules can be set for a bucket.

Parent node: CORSConfiguration
AllowedOrigin String Yes Specifies the allowed origins from which the cross-domain requests are initiated. You can use multiple elements to specify multiple allowed origins. Each rule allows up to one wildcard (*), which indicates that cross-domain requests from all origins are allowed.

Parent node: CORSRule
AllowedMethod enumeration (GET, PUT, DELETE, POST, HEAD) Yes Specifies the allowed methods for cross-domain requests.

Parent node: CORSRule
AllowedHeader String No Controls whether the headers specified by Access-Control-Request-Headers in the OPTIONS prefetch command are allowed. Each header specified by Access-Control-Request-Headers must match a value in AllowedHeader. Each rule allows up to one wildcard (*).

Parent node: CORSRule
ExposeHeader String No Specifies the response headers that can be accessed by from an application (for example, a Javascript XMLHttpRequest object). The wildcard (*) is not allowed.

Parent node: CORSRule
MaxAgeSeconds Integer No Specifies the cache time (in seconds) of a browser used to respond a prefetch (OPTIONS) request to a specific resource. Only one of this parameter is allowed in a CORSRule.

Parent node: CORSRule
CORSConfiguration Container Yes Specifies the container that stores the CORS rules for a bucket.

Parent node: None

Detail analysis

  • CORS is disabled for buckets by default, that is, cross-domain requests from any origin are forbidden.
  • To use CORS in applications, for example, accessing OSS from www.a.com through the XMLHttpRequest function of the browser, you must manually upload a CORS rule through this interface to enable CORS. This rule is described in an XML document.
  • The CORS settings for each bucket is specified by multiple CORS rules. A maximum of 10 CORS rules can be set for a bucket. The uploaded XML document cannot be larger than 16 KB.
  • When receiving a cross-domain request (or an OPTIONS request), OSS reads the CORS rules for the bucket and then checks related permissions. OSS checks each rule sequentially and uses the first rule that matches the request to approve the request and return the corresponding header. If none of the rules match the request, OSS does not include any CORS header in the response.
  • The following conditions must be met before OSS determines that a CORS rule matches the request:
    • The origin from which the request is initiated must match the value of AllowOrigin of the CORS rule.
    • The method of the request (such as GET or PUT) or the method corresponding to the Access-Control-Request-Method header in an OPTIONS request must match the value of AllowedMethod of the CORS rule.
    • Each header included in the Access-Control-Request-Headers header in an OPTIONS request must match the value of AllowedHeader of the CORS rule.
  • If you include the Content-MD5 header in the request, OSS calculates the Content-MD5 of the request body and checks whether the two values are the same. If the two values are different, the error code InvalidDigest is returned.

Examples

Request example of adding a bucket CORS rule:

PUT /?cors HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 186
Date: Fri, 04 May 2012 03:21:12 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
    <CORSRule>
      <AllowedOrigin>*</AllowedOrigin>
      <AllowedMethod>PUT</AllowedMethod>
      <AllowedMethod>GET</AllowedMethod>
      <AllowedHeader>Authorization</AllowedHeader>
    </CORSRule>
    <CORSRule>
      <AllowedOrigin>http://www.a.com</AllowedOrigin>
      <AllowedOrigin>http://www.b.com</AllowedOrigin>
      <AllowedMethod>GET</AllowedMethod>
      <AllowedHeader> Authorization</AllowedHeader>
      <ExposeHeader>x-oss-test</ExposeHeader>
      <ExposeHeader>x-oss-test1</ExposeHeader>
      <MaxAgeSeconds>100</MaxAgeSeconds>
    </CORSRule>
</CORSConfiguration >

Response example:

HTTP/1.1 200 OK
x-oss-request-id: 50519080C4689A033D00235F
Date: Fri, 04 May 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS