• Object Storage Service

obs
  1. Help Center
  2. Object Storage Service
  3. User Guide (S3cmd)
  4. Operation Guide
  5. Bucket Management
  6. Configuring CORS

Configuring CORS

Cross-Origin Resource Sharing (CORS) is a standard mechanism put forward by World Wide Web Consortium (W3C) and enables client-side cross-origin requests. Bucket owners or users who have the following permissions on the buckets can configure CORS. After a CORS rule is configured for a bucket stored on OBS, the bucket policy and ACL permissions on the bucket's objects still prevail.

  • s3:PutBucketCORS
  • s3:GetBucketCORS
NOTE:

You can obtain these permissions by configuring a bucket policy. For details about how to configure a bucket policy, see section Configuring a Bucket Policy.

Procedure

  1. Open the command line tool.
  2. Run the following commands to create a file that stores a CORS rule.

    vi cors-file-name

    NOTE:

    cors-file-name is the name of the file that stores a CORS rule and can be user-defined.

  3. Press i to go to the edit mode and configure a CORS rule in the following format:

    <CORSConfiguration> 
       <CORSRule> 
         <ID>id</ID> 
         <AllowedMethod>method</AllowedMethod> 
         <AllowedOrigin>origin</AllowedOrigin> 
         <AllowedHeader>header</AllowedHeader> 
         <MaxAgeSeconds>seconds</MaxAgeSeconds> 
         <ExposeHeader>header</ExposeHeader> 
       </CORSRule> 
    </CORSConfiguration>

    Table 1 describes each parameter in a CORS rule.

    Table 1 CORS rule

    Parameter

    Description

    Mandatory or Not

    CORSConfiguration

    The root node of CORSRule and its capacity cannot exceed 64 KB.

    Type: Container

    Ancestor: None

    Mandatory

    CORSRule

    The CORS rule. CORSConfiguration can contain a maximum of 100 CORS rules.

    Type: Container

    Ancestor: CORSConfiguration

    Mandatory

    ID

    Indicates the unique identifier of a rule. The value can contain a maximum of 255 characters.

    Type: String

    Ancestor: CORSRule

    Optional

    AllowedMethod

    Specifies the cross-origin request methods allowed by a CORS rule. If the other parameters are the same, each CORS rule can contain multiple allowed methods. Each method occupies one line.

    Type: String

    Valid values: GETPUTHEADPOST, and DELETE

    Ancestor: CORSRule

    Mandatory

    AllowedOrigin

    The origin of the cross-origin requests allowed by a CORS rule. Requests from this origin can access the bucket. Multiple matching rules are allowed. One rule occupies one line, and allows one wildcard character (*) at most.

    Type: String

    Ancestor: CORSRule

    Mandatory

    AllowedHeader

    Specifies the allowed header of cross-origin requests. Only CORS requests matching the allowed header are valid. You can enter multiple allowed headers (one per line). Each line can contain one wildcard character (*) at most. Spaces and special characters including &:< are not allowed.

    Type: String

    Ancestor: CORSRule

    Optional

    ExposeHeader

    Specifies the exposed header in CORS responses, providing additional information for clients. You can enter multiple exposed headers (one per line). Spaces and special characters including &:< are not allowed.

    Type: String

    Ancestor: CORSRule

    Optional

    MaxAgeSeconds

    Specifies the duration that the client can cache CORS responses, expressed in seconds. The default value is 100.

    Each CORS rule can contain one MaxAgeSeconds at most.

    Type: Integer

    Ancestor: CORSRule

    Optional

  4. Press Esc, input :wq!, and press Enter to save and exit the vi editor.
  5. Run the following command to configure this CORS rule for a specified bucket:

    s3cmd setcors cors-file-name s3://my-bucket

    NOTE:

    cors-file-name is the name of the file that stores the CORS rule and my-bucket is the name of the bucket for which you want to configure this CORS rule.

  6. (Optional) Run the following command to view the basic information about the bucket and check the CORS rule configuration:

    s3cmd info s3://my-bucket

    NOTE:

    Bucket owners or users who have all the following five permissions can perform this operation.

    • s3:GetBucketLocation
    • s3:GetLifecycleConfiguration
    • s3:GetBucketPolicy
    • s3:GetBucketCORS
    • s3:GetBucketAcl

    You can obtain these permissions by configuring a bucket policy. For details about how to configure a bucket policy, see section Configuring a Bucket Policy.

Example

You can configure a CORS rule for a bucket to specify the origin, supported request methods, and other specific operations allowed to access a bucket. The following uses an example to introduce how to configure a CORS rule. In the example, a CORS rule is configured to allow the OBS static website to respond to cross-origin requests from another website.

Usually, the scripts and content of a website cannot interact with those of another website because of the Same Origin Policy (SOP) for requests on the web page. In the following example rule, the bucket that is allowed to be configured as the static website can respond to the PUT, POST, and DELETE requests from website http://www.example.com.

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

In this example, the optional parameters and their descriptions are as follows:

  • AllowedHeader: In this example, its value is a wildcard character (*) which indicates that all specific headers are allowed to access the bucket.
  • MaxAgeSeconds: In this example, its value is 3000 seconds which indicates that the duration that your browser can cache CORS responses is 3000 seconds. The browser caches the CORS responses so that if repeated requests are sent, it can respond to these requests without sending them to OBS.
  • ExposeHeader: In this example, its value is x-server-side-encryption. Each ExposeHeader element identifies a header in the response that you want customers to be able to access from their applications.

Follow-up Procedure

If you need to modify a CORS rule for a bucket, you can modify the CORS configuration file or create a CORS file, and then run the CORS rule configuration command. By doing so, the bucket's CORS rule is updated.

You can delete a CORS rule as follows if necessary:

  1. Open the command line tool.
  2. Run the following command to delete a specific CORS rule:

    s3cmd delcors s3://my-bucket

    If the following information is displayed in the command output, it indicates that the CORS rule of the bucket is successfully deleted.

    s3://my-bucket/: CORS deleted

  3. (Optional) Run the following command to view the basic information about the bucket and check that the CORS rule is deleted:

    s3cmd info s3://my-bucket

    NOTE:

    Bucket owners or users who have all the following five permissions can perform this operation.

    • s3:GetBucketLocation
    • s3:GetLifecycleConfiguration
    • s3:GetBucketPolicy
    • s3:GetBucketCORS
    • s3:GetBucketAcl

    You can obtain these permissions by configuring a bucket policy. For details about how to configure a bucket policy, see section Configuring a Bucket Policy.