Bucket CORS policy

CORS(Cross-Origin Resource Sharing) allows web applications running on a specific domain to access resources from another domain. You can set an option to respond only to specific domains by setting a CORS policy for the bucket of Object Storage. You can configure a maximum of 10 CORS policies on a bucket.

info

If the detailed rules are not followed when configuring CORS policy, a 400 Bad Request error may occur.

Sequence of priority for CORS policy

When a request is made with two or more CORS policies, the policies are evaluated in the following order.

CORS policies are compared in the order they were entered.
The policy for the first matching Origin in the CORS policy list will be checked.
For the first matching Origin in the list, allowed_methods and allowed_headers are checked and a response will be generated.

Composition of CORS policy

The details of a CORS policy are:

Item	Description
allowed_origins	Specifies the sources that will allow CORS for this bucket - Example: `https://example.com`
allowed_methods	Specifies the HTTP methods that will allow CORS with the bucket - Access-Control-Allow-Methods has a value returned in the header in response to a successful Preflight request
allowed_headers	Specifies the headers to allow CORS with the bucket - Access-Control-Allow-Headers has a value returned in the header in response to a successful Preflight request
expose_headers	Response Headers lists the header names exposed as part of the Access-Control-Expose-Headers response
max_age_seconds	Time (in seconds) to cache Preflight OPTIONS request responses - Returned in the Access-Control-Max-Age header in response to a Preflight request

Detailed rules for each CORS component

Detailed rules for each CORS policy component must be followed.

allowed_origins

This refers to the origin that allows access, and is a Required item.

Case sensitive
Can contain up to 1 *(wild card) character
Available (console.*.kakao.io)
Impossible (..kakao.io)
Maximum input length per origin: 200
Maximum number of entries per CORS policy: 10
Allowed input characters
alpha-numeric -colon (:)
forward-slash (/)
dot (.)
wild card (*)
regex: '^[a-zA-Z0-9:/.-]$' = Alphabet case, numbers, special characters (*, :, /, ., - Only ) is allowed
Cannot be used in combination with other characters
Maximum number of inputs per CORS structure: 10

Details

allowed_methods

This refers to the method (HTTP) that allows access. Required item.

Case sensitive
Only uppercase input is recognized as normal
When entering lowercase letters, a return 400 Bad Request error is output.
Allowed input characters
wild card (*)
Cannot be used in combination with other characters
regex: '^[A-Z]$' = Only uppercase alphabet letters and special characters (*) are allowed.
Duplicate input values possible
Values that can be entered: GET, PUT, POST, DELETE, HEAD, * (when entering a wild card, only the first 5 methods are applied)
Maximum number of inputs per CORS structure: 5

allowed_headers

This refers to the header that allows access (exposed to the browser by default) and is Required.

Case sensitive
Can contain up to 1 *(wild card) character
max length per allowed_headers = 200
Allowed input characters
alpha-numeric
dash (-)
wild card (*)
Cannot be used in combination with other characters
regex: ‘^[a-zA-Z\d-*]+$’ = Only upper and lower case letters, numbers, and special characters (-, *) are allowed.
Maximum number of inputs per CORS structure: 10

expose_headers

This refers to the header that allows access (not exposed to the browser by default) and is Required.

max length per expose_headers = 200
Allowed input characters
alpha-numeric
dash (-)
wild card (*)
Cannot be used in combination with other characters
regex: ^[a-zA-Z0-9-] * $ = Only upper and lower case letters, numbers, and special characters (-) are allowed.
Maximum number of inputs per CORS structure: 10
Headers such as x-account-meta-*, x-container-meta-*, and x-object-meta-* use the exact meta name set by the user, not *. Must enter

max_age_seconds

The refers to the lifetime for caching preflight request results, and it is Optional.

Receives time in seconds
Only integers greater than 0 can be entered.
Maximum input is 1 day (86400)
If not entered, set to default value (0)

HTTP header list

The list of HTTP headers used in CORS Request and Response is as follows. For a details of HTTP headers, please refer to the following document.

Item	Description
Accept	MIME type, a request HTTP header that tells the client what content type it can understand. - Using content negotiation, the server selects one of the suggestions to use, and uses the Content-Type response header to indicate the type selected by the client. Notifies - The browser sets appropriate values for the header depending on the context in which the request was made, When loading a CSS style sheet, different values are set for the request than when loading an image, video, or script.
Accept-Ranges	Response HTTP header, which is a marker used by the server to signal support for partial requests - The value of this field can be used to define the range of units
Content-Disposition	The header that typically informs whether content in a standard HTTP response should be displayed inline in a browser as part of a webpage or treated as an attachment for download and local storage
Content-Encoding	Object header used to compress Media types - If this header exists, its value indicates what additional content encoding will be applied to the object body. It also tells the client how to decode to obtain the Media type referenced by the Content-Type header
Content-Length	Object header sent to recipient - Size of object body: in bytes
Content-Range	Response header indicating the location of the partial message within the full body message
Content-Type	Object header used to indicate the Media type of the resource
ETag	Response header, which is an identifier that identifies a specific version of the resource - Efficient caching and bandwidth savings because the web server checks the content and does not send a full request to the web server if it has not changed - If the content has changed Useful for preventing mid-air collisions (simultaneous modification and overwriting between resources)
Expect	Request header indicating the value expected to be returned by the server to properly process the request
Host	A request header field that specifies the Internet host and port number of the resource being requested, obtained from the original URI provided by the user or the referring resource
Last-Modified	A response containing the last modified date and time known to the server in the HTTP header
Origin	Header, which is where fetch starts - Contains only the server name, not path information - Sent with CORS requests, as included in POST requests - Similar to the Referer header, origin header does not reveal full path
Range	HTTP request header that tells the server that only part of the document should be returned - You can request multiple parts at once through the Range header, and the server will return multiple parts of the document for that range. > - If the server returns, 206 Partial Content must be used as the response. - If the range is invalid, the server sends a 416 Range Not Satisfiable error. - The server also ignores the Range header and returns 200. Can return entire document with status code
Referer	Request header containing the absolute or partial address of the page that sent the current request - If the request came via a link, the address of the page containing the link is included in the header - A resource request is made to another domain. When sending, the address of the page that uses the resource is included in the header - The Referer header recognizes the visitor's origin and route, the page being visited, etc., and the data can be used for analysis/logging/caching optimization
Transfer-Encoding	A header that specifies the encoding format used to securely transmit the entity to the user
X-Account-Meta-*	Meta-data of account - When requesting, used to store meta-data in the account - When responding, used to indicate meta-data information held by the account
X-Auth-Token	Authentication token
X-Container-Bytes-Used	Total bytes used
X-Container-Meta-*	Container's meta-data - When requesting, used to store meta-data in the Container - When responding, used to indicate meta-data information held by the Container
X-Container-Object-Count	Number of objects
X-Object-Manifest	Manifest of a dynamic large object - The value is the segment object's container and object name prefix in the form container/prefix
X-Object-Meta-*	Object's meta-data - When requested, used to store meta-data in the object - When responding, indicates meta-data information held by the object
X-Openstack-Request-Id	Unique transaction ID for this request - Your service provider may need this value if you are reporting a problem (same as X-Trans-Id)
X-Static-Large-Object	Set to true if this object is the manifest of a static large object (response header)
X-Subject-Token	Token delivered when authentication is successful - Auth information is delivered by setting the X-Auth-Token header when sending a request
X-Timestamp	Date and time when the account, container, or object was first created in its current version - Format: UNIX Epoch Timestamp - Example: '1440619048' is 'August 26, 2015 19:57:28 GMT'
X-Trans-Id	Unique transaction ID for this request - If you are reporting a problem, your service provider may need this value
X-Trans-Id-Extra	Additional transaction information - The `X-Trans-Id-Extra` request header can include additional information to help debug errors that may occur during large object uploads and other object storage transactions. - The server adds the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value of the generated `X-Trans-Id` response header. - The `X-Trans-Id-Extra` request header value must be UTF-8 encoded and then URL encoded before including additional transaction information. (Example: When uploading a large object such as an image, additional transaction information can be included.) - Include the same value in the `X-Trans-Id-Extra` request header when uploading each segment and manifest. - If an error occurs, all requests related to the large object upload can be found in the object storage logs. Additionally, the `X-Trans-Id-Extra` string can be used to debug requests where the operator did not receive a response. - The operator can retrieve additional information from the logs.

Configure bucket CORS policy

Here's how to set up a CORS policy for a bucket in Object Storage:

Configure new CORS policy

You can set up new CORS policies.

info

Only users granted the Storage Administrator role can set CORS policies for individual buckets.

Go to KakaoCloud Console > Beyond Storage Service > Object Storage.
Select a bucket in the Bucket menu.
Go to the Permission tab > CORS(Cross-Origin Resource Sharing) tab, then enter the policy in JSON Editor and click the [OK] button.

CORS tab

Load existing template

You can load an existing template. The default code at the bottom is automatically entered, and a template with CORS policy default values is applied.

info

Enter your policy by changing the default code at the bottom. If you use the code as is, it may be applied differently from the CORS policy desired by the user.

Go to KakaoCloud Console > Beyond Storage Service > Object Storage.
Select a bucket in the Bucket menu.

Go to the Permission tab >CORS(Cross-Origin Resource Sharing) tab, then click the [Load template].

Load template
    {
    "cors": [
        {
        "allowed_origins": [
            "http://example.com",
            "http://example.com:8080",
            "https://example.com",
            "http://*.example.com"
        ],
        "allowed_methods": [
            "GET",
            "HEAD"
        ],
        "allowed_headers": [
            "X-Auth-Token" 
            ],
            "expose_headers": [
            "Access-Control-Allow-Origin"
            ],
            "max_age_seconds": 0
        }
        ]
    }

Load existing policy

You can load CORS policies set in other buckets in your project and edit them in the current bucket.

info

To load a policy, a user must have the Storage Administrator role for another bucket in the project and have a CORS policy applied to that bucket.

Go to KakaoCloud Console > Beyond Storage Service > Object Storage.
Select a bucket in the Bucket menu.
Go to the Permission tab > CORS(Cross-Origin Resource Sharing) tab, then click the [Load existing policies].
Enter information in the pop-up window and click the [Load] button.

Load existing policy

Apply policy

You can apply CORS policies to your buckets.

Go to KakaoCloud Console > Beyond Storage Service > Object Storage.
In the Bucket menu, select the bucket to apply the policy to.
Go to the Permission tab > CORS(Cross-Origin Resource Sharing) tab, then enter the policy in JSON format in JSON Editor.
Confirm the changes in the pop-up window and click the [OK] button.

Delete policy

You can delete a CORS policy applied to a bucket. However, if you delete the CORS policy, ongoing resource sharing between other origins will be blocked.

Go to KakaoCloud Console > Beyond Storage Service > Object Storage.
Select a bucket in the Bucket menu.
Click the Permission tab and check whether the CORS policy is being applied in the CORS(Cross-Origin Resource Sharing) tab.
Click the [Delete] button in the pop-up window.
The policy is deleted and the CORS policy application status is Not applied.

Examples of bucket CORS policy

CORS policy configuration must be in JSON format, and up to 10 policies can be set. Instead of using an endpoint to access your website, you can serve content using your own domain, such as “example1.com”. For a detailed description of policy configuration, please refer to Bucket CORS policy configuration.

The CORS policy configuration example has two CORS policy rules applied:

Rules	Description
Rule 1	- Allow cross-origin `GET`, `HEAD`, `PUT` requests from `https://example.com`, `http://*.example.com` origin - Access-Control- Only accept `X-Auth-Token` in Preflight OPTIONS requests via Request-Headers header - Return the requested headers in response to Preflight OPTIONS requests
Rule 2	Allow cross-origin POST requests from all origins - `*` (wildcard) means all origins

CORS policy example
{
  "cors": [
    {
      "allowed_origins": [
        "https://example.com",
        "http://*.example.com"
      ],
      "allowed_methods": [
        "GET",
        "HEAD",
        "PUT"
      ],
      "allowed_headers": [
        "X-Auth-Token"
      ],
      "expose_headers": [
        "Access-Control-Allow-Origin"
      ],
      "max_age_seconds": 5
    },
    {
      "allowed_origins": [
        "*"
      ],
      "allowed_methods": [
        "POST"
      ],
      "allowed_headers": [ ],
      "expose_headers": [ ]
    }
  ]
}