S3 CORS

Cross-origin resource sharing (CORS) is a browser-enforced mechanism that controls how resources of a certain origin can be used from outside of that origin. CORS is configured on a bucket so that requests to fetch resources from that bucket succeed only if the bucket's CORS configuration allows using the bucket resources at origins specified in the request.

VAST Cluster supports both simple CORS where the origin sends the fetching request directly, and also CORS with preflight where the origin first sends a preflight OPTIONS request to check if the fetching request will be allowed to proceed.

Bucket CORS configuration consists of one or more CORS rules, each of which has statements to define the following:

Which origins (identified by their URLs) are allowed to fetch resources from the bucket
Which HTTP methods these origins are allowed to use when fetching resources
Which headers are allowed in the client request
Which response headers are exposed to the client
For how long the response to the preflight CORS request can be cached

By default, a bucket has no CORS configuration.

To create CORS configuration and rules for a bucket:

In VAST Web UI, use the S3 -> CORS tab in view settings (Element Store -> Views -> choose to create or edit a view). You can build the configuration in the visual builder or import a JSON file. For complete guidelines on using this tab, see CORS.
In VAST CLI, use the commands: view create-s3cors-configuration, view delete-s3cors-configuration, view show-s3cors-configuration

You can also manage CORS by sending PutBucketCors, DeleteBucketCors and GetBucketCors requests to VAST S3 API.

Managing CORS configuration for a bucket can be allowed or prohibited via identity or bucket policy using the the following actions:

s3:PutBucketCORS
s3:GetBucketCORS
s3:DeleteBucketCORS

In addition to configuring CORS per bucket, there is a legacy cluster-wide setting that configures the cluster to allow all origins for all buckets. This setting is for backward compatibility only and is not recommended.

CORS Rules

You can create up to 100 CORS rules per bucket CORS configuration. The maximum size of a CORS configuration for a bucket is 64kB.

The JSON syntax for a CORS rule is as follows:

[
    {
        "AllowedHeaders": [
            "<header 1>",
            "<header 2>",
            ...
        ],
        "AllowedMethods": [
            "<method 1>",
            "<method 2>",
            ...
        ],
        "AllowedOrigins": [
            "<URL 1>",
            "<URL 2",
            ...
        ],
        "ExposeHeaders": [
            "<response header 1>",
            "<response header 2>",
            ...
        ]
        "MaxAgeSeconds": <seconds>
    }
]

The CORS XML syntax (used when managing CORS through VAST S3 API) is as follows:

<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>URL1</AllowedOrigin>
    <AllowedOrigin>URL2</AllowedOrigin>
    ...
    <AllowedMethod>method1</AllowedMethod>
    <AllowedMethod>method2</AllowedMethod>
    ...
    <AllowedHeader>header1</AllowedHeader>
    <AllowedHeader>header2</AllowedHeader>
    ...
    <ExposeHeader>header1</ExposeHeader>
    <ExposeHeader>header2</ExposeHeader>
    ...
    <MaxAgeSeconds>seconds</MaxAgeSeconds>
  </CORSRule>
</CORSConfiguration>

The following CORS statements are supported:

JSON	XML	Description
`AllowedOrigins` (required)	`AllowedOrigin` (required)	A list of URLs of origins that are allowed to fetch resources from the bucket. You can use a wildcard () to specify all origins. Each entry may contain no more than one wildcard ().
`AllowedMethods` (required)	`AllowedMethod` (required)	A list of methods that allowed origins can use to fetch resources from the bucket. Valid values: PUT, HEAD, GET, POST, DELETE.
`AllowedHeaders`	`AllowedHeader`	A list of headers that are allowed in the client request. Each entry may contain no more than one wildcard (*).
`ExposeHeaders`	`ExposeHeader`	A list of headers that the client will be able to access.
`MaxAgeSeconds`	`MaxAgeSeconds`	A period of time during which response to the preflight CORS request can be cached by the client.

For example, to allow all origins those URLs end with example1.com, to POST and GET resources using requests with Content-MD5 and Authorization headers, where the response would contain the x-amz-meta-custom-header header:

In JSON:

[
    {
        "AllowedHeaders": ["Content-MD5", "Authorization",],
        "AllowedMethods": ["POST", "GET"],
        "AllowedOrigins": ["https://*.example1.com"]
        "ExposeHeaders": ["x-amz-meta-custom-header"]
    }
]

In XML:

<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>https://*.example1.com</AllowedOrigin>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedHeader>Content-MD5</AllowedHeader>
    <AllowedHeader>Authorization</AllowedHeader>
    <ExposeHeader>x-amz-meta-custom-header</ExposeHeader>
  </CORSRule>
</CORSConfiguration>

CORS Request Validation

The following conditions must be met for a CORS request to return the requested headers (or for a preflight CORS request to succeed):

The request origin specified in the Origin header (or, in case of a preflight CORS request, in the Access-Control-Request-Origins header) matches any of the entries in the AllowedOrigins list.
The request method (or, in case of a preflight CORS request, the method from the Access-Control-Request-Method header) matches one of the AllowedMethods entries.
For a preflight CORS request: the header(s) in the Access-Control-Request-Headers header match any of the entries in the AllowedHeaders list.

ExposeHeaders and MaxAgeSeconds values are taken from the first matching rule found in the bucket CORS configuration.

Examples

Creating a CORS Configuration with VAST CLI

Create a CORS configuration for a bucket:

vcli: admin> view create-s3cors-configuration --id 5 --cors-configuration '{
    "cors_rules": [
        {
            "allowed_origins": ["http://example.com"],
            "allowed_methods": ["GET", "HEAD"],
            "allowed_headers": ["Content-MD5"],
            "expose_headers": ["x-amz-server-side-encryption"],
            "max_age_seconds": 3600
        },
        {
            "allowed_origins": ["*"],
            "allowed_methods": ["DELETE"]
        }
    ]
}'

Verify the CORS configuration:

vcli: admin> view show-s3cors-configuration --id 5
+------+------------------------+-----------------+-----------------+----------------------------------+-----------------+
| ID   | Allowed-origins        | Allowed-methods | Allowed-headers | Expose-headers                   | Max-age-seconds |
+------+------------------------+-----------------+-----------------+----------------------------------+-----------------+
| 1759 | ['http://example.com'] | ['GET', 'HEAD'] | ['Content-MD5'] | ['x-amz-server-side-encryption'] | 3600            |
| 1760 | ['*']                  | ['DELETE']      | []              | []                               | None            |
+------+------------------------+-----------------+-----------------+----------------------------------+-----------------+

Creating a CORS Configuration with VAST S3 API

Create a bucket:

aws s3api create-bucket --bucket test-cors2 --endpoint-url http://xxx.xxx.xxx.xxx:9090

Configure CORS for the bucket:

aws s3api put-bucket-cors --bucket test-cors2 --cors-configuration '{"CORSRules": [{"AllowedOrigins": ["http://www.example.com"], "AllowedMethods": ["GET", "PUT"], "AllowedHeaders": ["Content-MD5", "Authorization"], "ExposeHeaders": ["x-amz-server-side-encryption"], "MaxAgeSeconds": 3600}, {"AllowedOrigins": ["*"], "AllowedMethods": ["HEAD"], "AllowedHeaders": ["Content-MD5"], "MaxAgeSeconds": 1000}]}' --endpoint-url http://xxx.xxx.xxx.xxx:9090

Verify the CORS configuration:

aws s3api get-bucket-cors --bucket test-cors2 --endpoint-url http://xxx.xxx.xxx.xxx:9090
{
    "CORSRules": [
        {
            "AllowedHeaders": [
                "Content-MD5",
                "Authorization"
            ],
            "AllowedMethods": [
                "GET",
                "PUT"
            ],
            "AllowedOrigins": [
                "http://www.example.com"
            ],
            "ExposeHeaders": [
                "x-amz-server-side-encryption"
            ],
            "MaxAgeSeconds": 3600
        },
        {
            "AllowedHeaders": [
                "Content-MD5"
            ],
            "AllowedMethods": [
                "HEAD"
            ],
            "AllowedOrigins": [
                "*"
            ],
            "MaxAgeSeconds": 1000
        }
    ]
}

Legacy Cluster-Wide CORS Configuration

VAST Cluster 5.5.0 preserves the ability to configure the cluster so that it includes the Access-Control-Allow-Origin: '*' header with every response, which means that all origins are allowed.

Caution
This setting is for backward compatibility only and is not recommended.

In VAST Web UI, the Enable CORS option in cluster S3 settings (Settings -> Cluster -> S3). Note that the UI option is only available on upgraded clusters that had this setting enabled before the upgrade.
In VAST CLI, the --enable-s3-cors option on the cluster modify command.

By default, the cluster-wide CORS setting is disabled. In case your cluster has it enabled (e.g. after an NDU), any bucket-level CORS configuration takes precedence over the cluster-wide configuration. In particular:

If you have the cluster-wide CORS setting enabled and set a bucket-level CORS configuration for a specific bucket, the bucket-level CORS configuration applies.
If you delete the bucket-level CORS configuration, the cluster-wide CORS configuration will apply, allowing all origins to fetch resources from the bucket.