All Products
Search
Document Center

Object Storage Service:PutBucketCors

Last Updated:Apr 28, 2024

Configures cross-origin resource sharing (CORS) rules for an Object Storage Service (OSS) 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 that has an identical existing CORS rule, 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 example.com to access OSS by using XMLHttpRequest of your browser, you must call this operation to configure a CORS rule in XML.

  • 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 corresponding headers. If the request fails to match any of the CORS rules, 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 request method (such as GET or PUT) or the method corresponding to the Access-Control-Request-Method header of the OPTIONS request must match one AllowedMethod item.

    • Each header included in Access-Control-Request-Headers in an OPTIONS request must match 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 cross-origin requests are allowed. 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.

Important

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.

Important

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 to an OPTIONS preflight request for the specified resource. 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 CORS configurations for the bucket.

Parent nodes: none

ResponseVary

Boolean

No

false

Specifies whether to return the Vary: Origin header. Valid values:

  • true: returns the Vary: Origin header, regardless of whether the request is a cross-origin request or whether the cross-origin request succeeds.

  • false: does not return the Vary: Origin header.

Important

This element is valid only when at least one CORS rule is configured.

For more information about the common request headers in the operation, see Common HTTP headers.

Response headers

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

Examples

  • Sample request

    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 qn6q**************:77Dv****************
    <?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 response

    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
    x-oss-server-time: 94

SDK

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 Content-MD5 value that is calculated by OSS based on the request body is different from the Content-MD5 value that is specified in the request header.