# Let a web page use the bucket (CORS)

Add CORS rules so that a web page on another site can upload to or read from your bucket from the browser.

A browser lets a page on `https://app.example.com` upload to or read from your bucket (a presigned
PUT, a file preview, `fetch()`) only when the bucket allows that origin. Without CORS rules,
browsers on other sites cannot call the bucket; servers, the CLI and SDKs are not affected.
Replace _example-uploads_ with your bucket's name.

## Prerequisites

- Permission for `s3:PutBucketCORS` on the bucket (also to remove rules); without it, **Add rule**
  is unavailable and says `Needs s3:PutBucketCORS on this bucket.`
- In the console, also `s3:GetBucketCORS`: without it the tab says "Reading this bucket’s CORS
  rules needs s3:GetBucketCORS."

## Add a rule

**Console**
1. Open **Object Storage**, open the bucket, then choose **CORS**.
2. Choose **Add rule**. The **Add a CORS rule** sheet opens.
3. (Optional) Under **Start from**, choose **Browser uploads from my app**, **Read from any site**
   or **Full access from my app**.
4. For **Allowed origins**, enter `https://app.example.com` (one origin per line).
5. For **Allowed methods**, select the methods. **GET** and **HEAD** are selected.
6. (Optional) Fill in **Allowed headers**, **Exposed headers** and **Max age (seconds)** (`3600`
   is filled in).
7. Choose **Add rule**.

The rule is saved at once. The **JSON** view edits every rule as one document; choose **Save
rules** there.

**CLI**
```sh
dcloud s3 bucket-cors set example-uploads \
  --rules '{"allowedOrigins":["https://app.example.com"],"allowedMethods":["GET","PUT","HEAD"],"allowedHeaders":["*"],"exposeHeaders":["ETag"],"maxAgeSeconds":3000}'
```

**API**
```http
PUT /s3/api/buckets/example-uploads/cors
{ "rules": [{ "allowedOrigins": ["https://app.example.com"], "allowedMethods": ["GET", "PUT", "HEAD"], "allowedHeaders": ["*"], "exposeHeaders": ["ETag"], "maxAgeSeconds": 3000 }] }
```

**Terraform**
```hcl
resource "dcloud_bucket_cors" "uploads" {
  bucket = dcloud_bucket.uploads.id
  rules = jsonencode([
    {
      allowedOrigins = ["https://app.example.com"]
      allowedMethods = ["GET", "PUT", "HEAD"]
      allowedHeaders = ["*"]
      exposeHeaders  = ["ETag"]
      maxAgeSeconds  = 3600
    },
  ])
}
```

Over S3, as on AWS:

```sh
aws --profile dcloud --endpoint-url https://s3.<domain> s3api put-bucket-cors --bucket example-uploads \
  --cors-configuration '{"CORSRules":[{"AllowedOrigins":["https://app.example.com","https://*.preview.example.com"],
    "AllowedMethods":["GET","PUT","HEAD"],"AllowedHeaders":["*"],"ExposeHeaders":["ETag"],"MaxAgeSeconds":3000}]}'
```

## How the rules apply

- The browser's preflight (`OPTIONS`) is answered from the rules without a signature.
  `Access-Control-Allow-Origin` (and `-Expose-Headers`, `-Max-Age`) is added to every matching
  response, presigned URLs and public objects included.
- The first matching rule wins. Up to 100 rules; each has up to 100 origins, allowed headers and
  exposed headers, and a max age of up to 86400 seconds.
- An origin or a header may hold one `*`. Methods are `GET`, `PUT`, `POST`, `DELETE` and `HEAD`.
- A named origin is answered with `Access-Control-Allow-Credentials: true`; `*` is not.
- The Deutsche Cloud Console's own uploads and downloads work without a CORS rule (see
  [Upload and download objects](upload-and-download-objects.md)).

## Remove every rule

Delete the last rule in the console (it says "CORS removed."), run
`dcloud s3 bucket-cors delete example-uploads`, call
`DELETE /s3/api/buckets/example-uploads/cors`, or destroy the `dcloud_bucket_cors`.

## If the browser is refused

A preflight no rule matches is answered `403 AccessForbidden`, with "CORSResponse: CORS is not
enabled for this bucket." when the bucket has no rules, and "CORSResponse: This CORS request is
not allowed. …" when it has rules but none matches the origin, method or headers.

A rule with more than one `*` in an origin or header is refused with `400` (`An origin may hold
at most one *`, `A header may hold at most one *`).

## Related

- [Share an object with a presigned URL](share-an-object.md)
- `s3.bucket-cors.set` · `dcloud s3 bucket-cors set` · `dcloud_bucket_cors`
