S3のCORS設定 JSON例とput-bucket-cors、エラー原因一覧

S3のCORS設定とは、「どのオリジン（Webサイト）から、どのHTTPメソッドで、このバケットにアクセスしてよいか」をバケットに登録するルールです。 ブラウザ上の JavaScript が別ドメインの S3 から画像やファイルを読み書きするときに必要で、AWS CLI では JSON ファイルを aws s3api put-bucket-cors に渡して設定します。

この記事では、各キーの意味と書ける値、よく使う4パターンの JSON、put / get / delete の CLI と boto3、CLI とコンソールで JSON の形が違う点、curl でプリフライトの応答を確かめる方法、CORS エラーの原因別対応表を、実行結果つきでまとめました。

確認環境：Ubuntu 24.04、AWS CLI 1.46.1、Python 3.11.15、boto3 1.43.103、curl 8.5.0、jq 1.7。AWS の API をローカルで再現するツール（moto 5.2.3）で実行しています。掲載するコマンドは、実際の AWS でそのまま使える形（エンドポイント指定なし、URL は S3 の形式）で書いています。

S3のCORS設定の早見表

1つのバケットに書けるルールは最大100個、設定全体のサイズは 64 KB までです。

JSON 例：よく使う4パターン

以降の JSON は CLI 用の形（CORSRules で包む形）です。ファイルに保存して次のコマンドで設定します。成功すると何も表示されません。

aws s3api put-bucket-cors --bucket example-assets-bucket \
  --cors-configuration file://cors.json

パターン1：GET のみ公開（画像やフォントを読み込ませる）

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://www.example.com"],
      "AllowedMethods": ["GET", "HEAD"],
      "MaxAgeSeconds": 3600
    }
  ]
}

Web ページから S3 上の画像・フォント・JSON を読むだけなら、これで足ります。AllowedHeaders は、特別なリクエストヘッダーを付けない読み取りでは省略できます。

パターン2：署名付き URL での PUT アップロード

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://app.example.com"],
      "AllowedMethods": ["PUT"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag"],
      "MaxAgeSeconds": 3000
    }
  ]
}

ブラウザから署名付き URL へ直接アップロードする構成です。ポイントは2つあります。

パターン3：複数オリジン・用途別に複数ルール

{
  "CORSRules": [
    {
      "ID": "web-read",
      "AllowedOrigins": ["https://www.example.com", "https://admin.example.com", "http://localhost:3000"],
      "AllowedMethods": ["GET", "HEAD"],
      "MaxAgeSeconds": 3600
    },
    {
      "ID": "admin-upload",
      "AllowedOrigins": ["https://admin.example.com"],
      "AllowedMethods": ["PUT", "POST", "DELETE"],
      "AllowedHeaders": ["Content-Type", "x-amz-*"],
      "ExposeHeaders": ["ETag", "x-amz-request-id"],
      "MaxAgeSeconds": 600
    }
  ]
}

AllowedOrigins は配列なので、オリジンを並べて書けます。開発用の http://localhost:3000 のように、ポート番号まで含めて書きます。「読み取りは広く、書き込みは管理画面だけ」のように条件が違うときは、ルールを分けます。S3 は上から順に見て、最初に条件が合ったルールを使います。

パターン4：ワイルドカード（サブドメインをまとめて許可）

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://*.example.com"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}

https://*.example.com は https://shop.example.com などのサブドメインに一致します。誰でも読める公開ファイルなら "AllowedOrigins": ["*"] も選べます。書き込み（PUT・POST・DELETE）を許可するルールでは、オリジンを具体的に書いておくと、どこからの操作を受け付けるかが設定から読み取れます。

put・get・delete を CLI で実行する

確認する（get-bucket-cors の出力）

パターン3を設定したあとの出力です。

aws s3api get-bucket-cors --bucket example-assets-bucket

{
    "CORSRules": [
        {
            "ID": "web-read",
            "AllowedMethods": [
                "GET",
                "HEAD"
            ],
            "AllowedOrigins": [
                "https://www.example.com",
                "https://admin.example.com",
                "http://localhost:3000"
            ],
            "MaxAgeSeconds": 3600
        },
        {
            "ID": "admin-upload",
            "AllowedHeaders": [
                "Content-Type",
                "x-amz-*"
            ],
            "AllowedMethods": [
                "PUT",
                "POST",
                "DELETE"
            ],
            "AllowedOrigins": [
                "https://admin.example.com"
            ],
            "ExposeHeaders": [
                "ETag",
                "x-amz-request-id"
            ],
            "MaxAgeSeconds": 600
        }
    ]
}

ルールが多いときは --query で表にできます。

aws s3api get-bucket-cors --bucket example-assets-bucket \
  --query 'CORSRules[].{ID:ID,Origins:join(`, `,AllowedOrigins),Methods:join(`, `,AllowedMethods)}' \
  --output table

--------------------------------------------------------------------------------------------------------------------
|                                                   GetBucketCors                                                  |
+--------------+--------------------+------------------------------------------------------------------------------+
|      ID      |      Methods       |                                   Origins                                    |
+--------------+--------------------+------------------------------------------------------------------------------+
|  web-read    |  GET, HEAD         |  https://www.example.com, https://admin.example.com, http://localhost:3000   |
|  admin-upload|  PUT, POST, DELETE |  https://admin.example.com                                                   |
+--------------+--------------------+------------------------------------------------------------------------------+

put は全ルールの置き換え

put-bucket-cors は追加ではなく、バケットの CORS 設定全体を置き換えます。 パターン1を put したあとにパターン2を put すると、残るのはパターン2だけです。

aws s3api put-bucket-cors --bucket example-assets-bucket --cors-configuration file://cors-get.json
aws s3api put-bucket-cors --bucket example-assets-bucket --cors-configuration file://cors-put.json
aws s3api get-bucket-cors --bucket example-assets-bucket \
  --query 'CORSRules[].[AllowedOrigins[0],AllowedMethods[0]]' --output text

https://app.example.com PUT

両方を有効にしたいときは、パターン3のように1つのファイルの CORSRules に並べて put します。

削除する（delete-bucket-cors）

aws s3api delete-bucket-cors --bucket example-assets-bucket
aws s3api get-bucket-cors --bucket example-assets-bucket

An error occurred (NoSuchCORSConfiguration) when calling the GetBucketCors operation: The CORS configuration does not exist

削除後、または一度も設定していないバケットに get をすると NoSuchCORSConfiguration が返ります。「CORS 設定が1つもない」という状態を表す応答で、put すれば解消します。

boto3 で設定・確認・削除する

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client("s3", region_name="ap-northeast-1")
BUCKET = "example-assets-bucket"

cors = {
    "CORSRules": [
        {
            "AllowedOrigins": ["https://app.example.com"],
            "AllowedMethods": ["PUT"],
            "AllowedHeaders": ["*"],
            "ExposeHeaders": ["ETag"],
            "MaxAgeSeconds": 3000,
        }
    ]
}

# 設定する（既存の CORS 設定は丸ごと置き換わる）
s3.put_bucket_cors(Bucket=BUCKET, CORSConfiguration=cors)

# 確認する
for rule in s3.get_bucket_cors(Bucket=BUCKET)["CORSRules"]:
    print(rule)

# 削除する
s3.delete_bucket_cors(Bucket=BUCKET)

# 設定が無いバケットに get すると ClientError になる
try:
    s3.get_bucket_cors(Bucket=BUCKET)
except ClientError as e:
    print(e.response["Error"]["Code"], "/", e.response["Error"]["Message"])

{'AllowedHeaders': ['*'], 'AllowedMethods': ['PUT'], 'AllowedOrigins': ['https://app.example.com'], 'ExposeHeaders': ['ETag'], 'MaxAgeSeconds': 3000}
NoSuchCORSConfiguration / The CORS configuration does not exist

boto3 に渡す辞書は、CLI 用 JSON と同じ {"CORSRules": [...]} の形です。JSON ファイルを json.load で読んで、そのまま CORSConfiguration に渡せます。

CLI は CORSRules で包む、コンソールは配列だけ

S3 の CORS 設定でいちばんつまずきやすいのが、同じ JSON でも、CLI とマネジメントコンソールで外側の形が違う点です。

コンソール用の形（配列だけ）は次のとおりです。

[
  {
    "AllowedOrigins": ["https://www.example.com"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedHeaders": [],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3600
  }
]

これをそのまま CLI に渡すと、送信前に止まります。

aws s3api put-bucket-cors --bucket example-assets-bucket --cors-configuration file://console.json

Error parsing parameter '--cors-configuration': Invalid JSON:
[
…（省略：渡した JSON がそのまま表示される）…

Invalid JSON と表示されますが、JSON の書式そのものは正しく、外側が配列になっていることが原因です。jq で相互に変換できます。

# コンソール用（配列） → CLI 用（CORSRules で包む）
jq '{CORSRules: .}' console.json > cli.json
aws s3api put-bucket-cors --bucket example-assets-bucket --cors-configuration file://cli.json

# CLI の設定 → コンソール用（配列だけ取り出す）
aws s3api get-bucket-cors --bucket example-assets-bucket --query CORSRules

[
    {
        "AllowedMethods": [
            "GET",
            "HEAD"
        ],
        "AllowedOrigins": [
            "https://www.example.com"
        ],
        "MaxAgeSeconds": 3600
    }
]

put で出るエラーと直し方（実際の出力）

MalformedXML：AllowedMethods が空

{"CORSRules":[{"AllowedOrigins":["https://www.example.com"],"AllowedMethods":[]}]}

An error occurred (MalformedXML) when calling the PutBucketCors operation: The XML you provided was not well-formed or did not validate against our published schema

JSON で渡しているのに「XML」と出るのは、CLI が JSON を XML に変換して S3 に送っているためです。AllowedMethods に1つ以上のメソッドを書きます。"CORSRules": [] とルールを空にした場合も同じエラーになります（設定を消したいときは delete-bucket-cors を使います）。

InvalidRequest：使えないメソッドを書いた

{"CORSRules":[{"AllowedOrigins":["https://www.example.com"],"AllowedMethods":["GET","OPTIONS"]}]}

An error occurred (InvalidRequest) when calling the PutBucketCors operation: Found unsupported HTTP method in CORS config. Unsupported method is OPTIONS

OPTIONS は AllowedMethods に書けません。 プリフライト（OPTIONS）は、CORS 設定があれば S3 が自動で応答します。書けるのは GET・PUT・POST・DELETE・HEAD の5つです。小文字の get も同じエラーになります。

An error occurred (InvalidRequest) when calling the PutBucketCors operation: Found unsupported HTTP method in CORS config. Unsupported method is get

CLI が送信前に止めるエラー

必須キーの書き忘れ、キー名のつづり、型の違いは、CLI（botocore）が場所つきで教えてくれます。

{"CORSRules":[{"AllowedOrigin":["https://www.example.com"],"AllowedMethods":["GET"]}]}

Parameter validation failed:
Missing required parameter in CORSConfiguration.CORSRules[0]: "AllowedOrigins"
Unknown parameter in CORSConfiguration.CORSRules[0]: "AllowedOrigin", must be one of: ID, AllowedHeaders, AllowedMethods, AllowedOrigins, ExposeHeaders, MaxAgeSeconds

公式ドキュメントの XML 例では AllowedOrigin（単数形）ですが、JSON のキーは AllowedOrigins（複数形）です。

{"CORSRules":[{"AllowedOrigins":"https://www.example.com","AllowedMethods":["GET"]}]}

Parameter validation failed:
Invalid type for parameter CORSConfiguration.CORSRules[0].AllowedOrigins, value: https://www.example.com, type: <class 'str'>, valid types: <class 'list'>, <class 'tuple'>

値が1つでも配列（["…"]）で書きます。

curl でプリフライトの応答を確認する

設定が効いているかは、ブラウザを使わずに curl で確かめられます。Origin ヘッダーを付けることが必須です。Origin が無いリクエストは、S3 がクロスオリジンとして扱わず、CORS 用の応答ヘッダーを返しません。

プリフライト（OPTIONS）を送る

パターン1（https://www.example.com から GET・HEAD を許可）を設定した状態で、ブラウザが送るのと同じプリフライトを再現します。Origin と Access-Control-Request-Method の2つを付けます。

curl -s -D - -o /dev/null -X OPTIONS \
  "https://example-assets-bucket.s3.ap-northeast-1.amazonaws.com/img/logo.png" \
  -H "Origin: https://www.example.com" \
  -H "Access-Control-Request-Method: GET" \
  | grep -i -E '^HTTP|allow-origin|allow-methods|max-age'

HTTP/1.1 200 OK
Access-Control-Allow-Methods: GET, HEAD
Access-Control-Allow-Origin: https://www.example.com
Access-Control-Max-Age: 3600

オリジンが一致しないとき（http と https の違い）

同じ設定のまま、Origin を http:// に変えて送ります。

curl -s -o /dev/null -w '%{http_code}\n' -X OPTIONS \
  "https://example-assets-bucket.s3.ap-northeast-1.amazonaws.com/img/logo.png" \
  -H "Origin: http://www.example.com" \
  -H "Access-Control-Request-Method: GET"

403

応答の本文から、エラーコードとメッセージを取り出します。

curl -s -X OPTIONS \
  "https://example-assets-bucket.s3.ap-northeast-1.amazonaws.com/img/logo.png" \
  -H "Origin: http://www.example.com" \
  -H "Access-Control-Request-Method: GET" | grep -o '<Code>.*</Message>'

<Code>AccessForbidden</Code><Message>CORSResponse: This CORS request is not allowed. This is usually because the evalution of Origin, request method / Access-Control-Request-Method or Access-Control-Request-Headers are not whitelisted by the resource's CORS spec.</Message>

https://www.example.com と http://www.example.com は別のオリジンとして扱われます。メッセージにあるとおり、原因は「オリジン」「メソッド」「リクエストヘッダー」のどれかが設定と合っていないことです。

実際の GET で確認する

プリフライトではなく、GET そのものに Origin を付けても確認できます。

curl -s -D - -o /dev/null \
  "https://example-assets-bucket.s3.ap-northeast-1.amazonaws.com/img/logo.png" \
  -H "Origin: https://www.example.com" | grep -i -E '^HTTP|allow-origin'

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://www.example.com

Access-Control-Allow-Origin が返っていれば、ブラウザはこの応答を JavaScript に渡します。なお、CORS を設定しても ACL やバケットポリシーはそのまま適用されます。CORS は「ブラウザに対して別オリジンからの利用を認める」設定で、オブジェクトを読む権限そのものは別に必要です。

署名付き URL での PUT と ETag の確認

パターン2を設定し、boto3 でアップロード用の署名付き URL を作ります。

import boto3

s3 = boto3.client("s3", region_name="ap-northeast-1")

url = s3.generate_presigned_url(
    "put_object",
    Params={
        "Bucket": "example-assets-bucket",
        "Key": "uploads/photo.jpg",
        "ContentType": "image/jpeg",  # アップロード時に同じ Content-Type を送る
    },
    ExpiresIn=300,  # 有効期間（秒）
)
print(url)

実行すると、署名付き URL が1行表示されます。これをシェル変数 URL に入れて、ブラウザと同じ順序（プリフライト → PUT）で送ります。

URL=$(python3 presign_put.py)

# 1) プリフライト：PUT と Content-Type ヘッダーを送ってよいかを確認
curl -s -D - -o /dev/null -X OPTIONS "$URL" \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: PUT" \
  -H "Access-Control-Request-Headers: content-type" \
  | grep -i -E '^HTTP|allow-origin|allow-methods|max-age'

HTTP/1.1 200 OK
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Max-Age: 3000

# 2) PUT でアップロード
curl -s -D - -o /dev/null -T photo.jpg "$URL" \
  -H "Origin: https://app.example.com" \
  -H "Content-Type: image/jpeg" | grep -i -E '^HTTP|^etag|expose-headers'

HTTP/1.1 200 OK
Access-Control-Expose-Headers: ETag
ETag: "4cd43d1cf5a975e1fbb85b2e57548671"

Access-Control-Expose-Headers: ETag が付いています。ここで設定から "ExposeHeaders": ["ETag"] の行を外して同じ PUT を送ると、応答はこう変わります。

HTTP/1.1 200 OK
ETag: "4cd43d1cf5a975e1fbb85b2e57548671"

アップロードは成功し、ETag ヘッダーも返っていますが、Access-Control-Expose-Headers がありません。 公式ドキュメントでは、ExposeHeaders に書かれていない応答ヘッダーは、クライアント側の JavaScript からアクセスできないと説明されています。curl ではどちらも ETag が見えるため、「curl では取れるのにブラウザでは取れない」ときは ExposeHeaders を確認します。

CORS エラーの原因別対応表

ブラウザのコンソールに CORS エラーが出たときは、次の表を上から順に確認します。「確認方法」は前の章の curl です。

S3 がルールを選ぶ条件は、公式ドキュメントで次の3つと説明されています。3つすべてを満たす最初のルールが使われます。

1. リクエストの Origin が AllowedOrigins のどれかに一致する
2. メソッド（プリフライトでは Access-Control-Request-Method）が AllowedMethods のどれかに一致する
3. プリフライトの Access-Control-Request-Headers に並ぶヘッダーが、すべて AllowedHeaders に一致する

よくある質問

Q. AllowedOrigins をワイルドカード（全オリジン許可）にしてもよいですか？ A. 誰でも読める公開ファイルを GET・HEAD で配るだけなら選択肢になります。書き込みを許可するルールや、限られたサイトだけに使わせたいファイルでは、オリジンを具体的に並べます。

Q. AllowedMethods に OPTIONS は必要ですか？ A. 不要で、書くと InvalidRequest になります。プリフライトの OPTIONS には、CORS 設定があれば S3 が自動で応答します。

Q. 設定を変えたのに、ブラウザでまだエラーになります。 A. ブラウザは MaxAgeSeconds の間、プリフライトの結果を覚えています。まず curl で S3 の応答を直接確かめ、S3 側が正しければブラウザのキャッシュを消して再読み込みします。開発中は MaxAgeSeconds を短めにしておくと確認が楽です。

Q. コンソールで保存した JSON を CLI で使い回せますか？ A. 外側の形が違うので、jq '{CORSRules: .}' で包んでから渡します。逆に CLI の設定をコンソールに貼るときは、--query CORSRules で配列だけを取り出します。

まとめ

• CORS 設定は AllowedOrigins と AllowedMethods が必須。必要に応じて AllowedHeaders・ExposeHeaders・MaxAgeSeconds を足す
• CLI と boto3 は {"CORSRules": […]}、コンソールは配列だけ。jq と --query で相互に変換できる
• put-bucket-cors は全ルールの置き換え。複数の用途は1つのファイルにまとめる
• AllowedMethods に書けるのは GET・PUT・POST・DELETE・HEAD。OPTIONS は書かない
• 確認は curl に Origin と Access-Control-Request-Method を付けた OPTIONS。200 と Access-Control-Allow-Origin が返れば設定が効いている
• オリジンはスキーム・ホスト・ポートまで完全に一致させる。末尾スラッシュは付けない
• JavaScript から ETag を読むには ExposeHeaders が必要

参考・出典

• Amazon S3 ユーザーガイド：Using cross-origin resource sharing (CORS)
• Amazon S3 ユーザーガイド：Elements of a CORS configuration
• Amazon S3 ユーザーガイド：Troubleshooting CORS
• Amazon S3 API リファレンス：PutBucketCors
• AWS re:Post：Configure and confirm CORS in Amazon S3
• MDN Web Docs：Origin header

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。