Bucket CORS policy

CORS (Cross-Origin Resource Sharing) is a feature that allows web applications running on a specific domain to access resources on another domain. By configuring a CORS policy for an Object Storage bucket, you can control responses so that only specific domains are allowed.

You can configure up to 10 CORS policies for a bucket. By default, the Origin in the CORS policy does not allow access from external domains.

CORS policy components

A CORS policy consists of origins, HTTP methods, request headers, response headers, and the preflight request cache duration.

info

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

Sequence of priority for CORS policy

When two or more CORS policies are entered and a request is received, policies are compared in the following order:

• Compare CORS policies in the order they were entered
• Check the policy for the first matching Origin in the CORS policy list
• Check allowed_methods and allowed_headers for the first matching Origin and generate a response

Composition of policy details

The components of a CORS policy are as follows:

Field	Description
allowed_origins	Specifies the origins allowed for the bucket's CORS - Example: https://example.com
allowed_methods	Specifies the HTTP methods allowed for CORS with the bucket - Access-Control-Allow-Methods is returned as a header value in response to a successful preflight request
allowed_headers	Specifies the headers allowed for CORS with the bucket - Access-Control-Allow-Headers is returned as a header value in response to a successful preflight request
expose_headers	Lists the header names exposed as part of the Access-Control-Expose-Headers response
max_age_seconds	Cache duration, in seconds, for the preflight OPTIONS request response - Access-Control-Max-Age is returned as a header in response to a preflight request

Detailed rules for each CORS component

Each CORS component must comply with specific rules.

allowed_origins

Specifies the origins allowed to access the resource. Required field.

• Case-sensitive
• Allows only one wildcard (*) per origin
• Valid: console.*.kakao.io
• Invalid: *.*.kakao.io
• Maximum length per origin: 200 characters
• Maximum of 10 origins per policy
• Allowed characters:
  • Alphanumeric
  • Colon (:)
  • Forward slash (/)
  • Dot (.)
  • Wildcard (*)
• Cannot mix with disallowed characters
• Regex: ^[*a-zA-Z0-9:/.-]*$
• Max 10 entries per CORS object

allowed_methods

Specifies the allowed HTTP methods. Required field.

• Case-sensitive
• Only uppercase is valid; lowercase results in 400 Bad Request
• Allowed characters:
  • Uppercase letters
  • Wildcard (*)
• Cannot mix with disallowed characters
• Regex: ^[*A-Z]*$
• Duplicate entries are allowed
• Valid values: GET, PUT, POST, DELETE, HEAD, *
• If wildcard (*) is entered, only the five methods listed above are applied
• Max 5 methods per CORS object

allowed_headers

Specifies the headers allowed by the browser (default exposed). Required field.

• Case-sensitive
• Allows one wildcard (*)
• Max length per entry: 200 characters
• Allowed characters:
  • Alphanumeric
  • Dash (-)
  • Wildcard (*)
• Cannot mix with disallowed characters
• Regex: ^[a-zA-Z\d-*]+$
• Max 10 entries per CORS object

expose_headers

Specifies the headers that are not exposed by default in the browser. Required field.

• Max length per entry: 200 characters
• Allowed characters:
  • Alphanumeric
  • Dash (-)
  • Wildcard (*)
• Cannot mix with disallowed characters
• Regex: ^[a-zA-Z0-9-]*$
• Max 10 entries per CORS object
• For headers like x-account-meta-*, x-container-meta-*, x-object-meta-*, the exact meta name must be specified instead of using *

max_age_seconds

Indicates the cache duration for the preflight request result. Optional field.

• Enter the value in seconds
• Must be an integer greater than or equal to 0
• Max value: 86400 (1 day)
• Default: 0 if not specified

Configure bucket CORS policy

Follow the steps below to configure a CORS policy for a bucket in Object Storage.

Set new CORS policy

You can configure a new CORS policy for a bucket.

info

Only users with the storage admin role can configure CORS policies for individual buckets.

1. Go to KakaoCloud console > Storage > Object Storage.
2. Select the bucket from the Standard bucket menu.
3. In Permission > CORS, click [Configure].
4. Configure the CORS policy by writing it directly, loading a template, or loading an existing policy.

Write directly

Enter the CORS policy directly.

Load template

Load a template to automatically populate the JSON Editor with default code.

info

Edit the default code as needed. Using it as-is may result in unintended CORS behavior.

Default code for loading 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

Load a CORS policy currently used by another bucket. The policy used by the other bucket is automatically populated in the JSON Editor.

You need the storage.buckets.getiampolicy permission to retrieve the other bucket's CORS policy.

Examples of bucket CORS policy

CORS policy configuration must be in JSON format and can include up to 10 policies. You can use a custom domain such as example1.com to serve content instead of accessing the website through an endpoint.

For details about policy configuration, see Configure bucket CORS policy.

The following CORS policy configuration example includes two CORS policy rules.

Rule	Description
Rule 1	- Allow cross-origin GET, HEAD, and PUT requests from the https://example.com and http://*.example.com Origins - Allow only X-Auth-Token for preflight OPTIONS requests through the Access-Control-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

Example of CORS policy configuration

{
  "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": [ ]
    }
  ]
}

HTTP header list

The following HTTP headers are used in CORS requests and responses. For more information about HTTP headers, see the following documents.

• RFC 9110: HTTP Semantics
• MDN Web Docs: HTTP headers
• OpenStack Object Store API Reference

Header	Description
Accept	Specifies accepted MIME types for the client
Accept-Ranges	Indicates partial request support
Content-Disposition	Indicates how content should be displayed (inline or attachment)
Content-Encoding	Specifies compression used
Content-Length	Size of response body in bytes
Content-Range	Indicates the range of partial content
Content-Type	Media type of the resource
ETag	Identifier for a specific version of a resource
Expect	Indicates expectations from the server
Host	Specifies domain and port number
Last-Modified	Last modified date and time of the resource
Origin	Indicates where fetch request originated from
Range	Requests a specific portion of a resource
Referer	Specifies the source of the request
Transfer-Encoding	Encoding for safely transmitting entity
X-Account-Meta-*	Account-level metadata
X-Auth-Token	Authentication token
X-Container-Bytes-Used	Total used bytes in container
X-Container-Meta-*	Container-level metadata
X-Container-Object-Count	Number of objects in container
X-Object-Manifest	Manifest for segmented large objects
X-Object-Meta-*	Object-level metadata
X-Openstack-Request-Id	Unique request transaction ID
X-Static-Large-Object	Indicates static large object manifest
X-Subject-Token	Token returned upon successful authentication
X-Timestamp	UNIX epoch timestamp of object creation
X-Trans-Id	Unique transaction ID
X-Trans-Id-Extra	Extra information for debugging large transactions