Configures cross-origin resource sharing (CORS) rules for a bucket.

Usage notes

  • Disabled-by-default design

    By default, CORS is disabled for a bucket. All cross-origin requests are not allowed.

  • Overwriting mechanism

    If you call the PutBucketCors operation to configure a new CORS rule for a bucket for which a CORS rule is already configured, the existing rule is overwritten.

  • Use of CORS in applications

    Before you can use CORS in applications, you must call the PutBucketCors operation to configure a CORS rule to enable CORS.

    For example, if you want to use the XMLHttpRequest feature of your browser to access Object Storage Service (OSS) from the domain name example.com, you must call the PutBucketCors operation to configure a CORS rule that is described by an XML message body.

  • CORS rule matching

    When OSS receives a cross-origin request or an OPTIONS request that is destined for a bucket, OSS reads the CORS rules that are configured for the bucket and attempts to match the rules one after another. If OSS finds the first match, OSS returns a corresponding header. If no match is found, OSS does not include CORS headers in the response.

    OSS considers that a cross-origin request or an OPTIONS request matches a CORS rule only when the request meets the following conditions:

    • The origin from which the cross-origin request is sent matches the value of one AllowedOrigin element in the CORS rule.
    • The method of the cross-origin request such as GET or PUT or the method that corresponds to the Access-Control-Request-Method header in the OPTIONS request matches the value of one AllowedMethod element in the CORS rule.
    • Each header that is included in Access-Control-Request-Headers in the OPTIONS request matches the value of one AllowedHeader element in the CORS rule.

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 Example Description
CORSRule Container Yes N/A The container that stores CORS rules.

You can configure up to 10 CORS rules for a bucket. The XML message body in a request can be up to 16 KB in size.

Parent nodes: CORSConfiguration

AllowedOrigin String Yes * The origin from which you want to allow cross-origin requests. You can use multiple elements to specify multiple allowed origins.

You can use only one asterisk (*) as the wildcard for AllowedOrigin. If you set AllowedOrigin to an asterisk (*), all cross-origin requests are allowed.

Parent nodes: CORSRule

AllowedMethod Enumeration Yes GET The cross-origin request method that is allowed. Valid values: GET, PUT, DELETE, POST, and HEAD

Parent nodes: CORSRule

AllowedHeader String No Authorization Specifies whether the headers specified by Access-Control-Request-Headers in the OPTIONS preflight request are allowed.

Each header specified by Access-Control-Request-Headers must match the value of an AllowedHeader element.

Notice You can use only one asterisk (*) as the wildcard for AllowedHeader. The following characters are not supported:
  • <
  • >
  • &
  • '
  • "

Parent nodes: CORSRule

ExposeHeader String No x-oss-test The response headers for allowed access requests from applications, such as an XMLHttpRequest object in JavaScript.
Notice The following characters are not supported:
  • *
  • <
  • >
  • &
  • '
  • "

Parent nodes: CORSRule

MaxAgeSeconds Integer No 100 The period of time within which the browser can cache the response for an OPTIONS preflight request that is destined to specific resources. Unit: seconds.

You can specify only one MaxAgeSeconds element in a CORS rule.

Parent nodes: CORSRule

CORSConfiguration Container Yes N/A The container that stores the CORS rule that you want to configure for the bucket.

Parent nodes: none

ResponseVary Boolean No false Specifies whether to return the Vary: Origin header. Default value: false. Valid values:
  • true: The Vary: Origin header is returned regardless whether the request is a cross-origin request or whether the cross-origin request succeeds.
  • false: The Vary: Origin header is not returned.
Notice This element is valid only when at least one CORS rule is configured.

For more information about the common request headers contained in PutBucketCors requests such as Host and Authorization, see Common request headers.

Response headers

The response to a PutBucketCors request contains only common response headers. For more information, see Common response headers.

Examples

  • Sample requests
    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 qn6qrrqxo2oawuk53otf****:KU5h8YMUC78M30dXqf3JxrT*****
    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration>
        <CORSRule>
          <AllowedOrigin>*</AllowedOrigin>
          <AllowedMethod>PUT</AllowedMethod>
          <AllowedMethod>GET</AllowedMethod>
          <AllowedHeader>Authorization</AllowedHeader>
        </CORSRule>
        <CORSRule>
          <AllowedOrigin>http://example.com</AllowedOrigin>
          <AllowedOrigin>http://example.net</AllowedOrigin>
          <AllowedMethod>GET</AllowedMethod>
          <AllowedHeader> Authorization</AllowedHeader>
          <ExposeHeader>x-oss-test</ExposeHeader>
          <ExposeHeader>x-oss-test1</ExposeHeader>
          <MaxAgeSeconds>100</MaxAgeSeconds>
        </CORSRule>
        <ResponseVary>false</ResponseVary>
    </CORSConfiguration >
  • Sample responses
    HTTP/1.1 200 OK
    x-oss-request-id: 50519080C4689A033D0*****
    Date: Fri, 04 May 2012 03:21:12 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS

SDKs

You can use OSS SDKs for the following programming languages to call the PutBucketCors operation:

Error codes

Error code HTTP status code Description
InvalidDigest 400 The error message returned because the Content-MD5 value that is calculated by OSS based on the message body is different from the Content-MD5 value that is specified in the request header.