Access-Control-Allow-Headers

使い方

ブラウザがプリフライトの OPTIONS リクエストを発行すると、Access-Control-Request-Headers ヘッダーが、クライアントが送信しようとしているセーフリスト外のヘッダーを列挙します。サーバーは、それらのうちどのヘッダーを受け入れるかを示す Access-Control-Allow-Headers で応答します。

CORS セーフリストのヘッダーは常に許可されており、このリストに現れる必要はありません。セーフリストには Accept、Accept-Language、Content-Language、Content-Type（メディアタイプと値の長さに制限あり）、Range（形式に制限あり）が含まれます。セーフリストのヘッダーを明示的に列挙すると、値に対する追加の制限が解除されます。

複数のヘッダー名はカンマ区切りのリストとして現れます。

ヘッダー名のリスト

サーバーが実際のリクエストで受け入れるヘッダー名を、カンマ区切りで並べたものです。

Access-Control-Allow-Headers: Content-Type, Authorization

*（ワイルドカード）

アスタリスクは認証情報を伴わないリクエストに対するワイルドカードとして機能し、任意のヘッダー名を許可します。

Access-Control-Allow-Headers: *

注意

認証情報を伴うリクエストでは、ワイルドカード * はワイルドカードではなくリテラル文字列として扱われます。認証情報が存在する場合、許可する各ヘッダーを明示的に列挙しなければなりません。Authorization ヘッダーはワイルドカードの対象になることが決してないため、常に明示的に指定する必要があります。

例

プリフライトのリクエストが、Content-Type とカスタムの X-Request-ID ヘッダーが許可されているかを尋ねます。サーバーは両方を許可することを伝えます。

リクエスト

OPTIONS /api/data HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Request-ID

レスポンス

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-Request-ID
Access-Control-Max-Age: 86400

認証情報を伴わないリクエスト向けにワイルドカードを使うサーバーは、1 文字だけで応答します。

Access-Control-Allow-Headers: *

トラブルシューティング

リクエストヘッダーに関連するプリフライトの失敗は、コンソールにエラーを出力し、実際のリクエストをブロックします。

コンソールに「Request header field X is not allowed by Access-Control-Allow-Headers in preflight response.」と表示される。サーバーが Access-Control-Allow-Headers の値にそのヘッダー名を列挙していません。不足しているヘッダーをプリフライトのレスポンスに追加してください。nginx では add_header Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”; Apache では Header set Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID” とします。

プリフライトのレスポンスにヘッダーがまったく含まれない。サーバーは OPTIONS リクエストを処理していますが、レスポンスに Access-Control-Allow-Headers を含めていません。多くのフレームワークでは、プリフライトのルートに対して明示的な CORS の設定が必要です。OPTIONS のハンドラーまたはミドルウェアが、Access-Control-Allow-Methods や Access-Control-Allow-Origin と併せてこのヘッダーを設定していることを確認してください。

ワイルドカード * が認証情報を伴うリクエストで機能しない。Access-Control-Allow-Credentials が true の場合、ワイルドカードはリテラル文字列 * として扱われ、何にも一致しません。許可する各ヘッダーを明示的に列挙してください。Authorization ヘッダーは、認証情報を伴わないリクエストであってもワイルドカードの対象にならないため、常に明示する必要があります。

一部のサーバーでヘッダー名が大文字小文字を区別するように見える。プロトコル上、HTTP のヘッダー名は大文字小文字を区別しませんが、一部のサーバーフレームワークは許可リストを確認する際に大文字小文字を区別した文字列照合を行います。サーバーが Content-Type しか列挙していない場合、content-type を送るリクエストは失敗することがあります。クライアントが送る表記に合わせるか、CORS の設定で双方を小文字に正規化してください。

Content-Type: application/json を送ると想定外のプリフライトが発生する。Content-Type ヘッダーがセーフリストに含まれるのは、値が application/x-www-form-urlencoded、multipart/form-data、text/plain の場合だけです。application/json はセーフリストの範囲外であり、プリフライトを強制します。Content-Type を Access-Control-Allow-Headers のリストに追加してください。プリフライトが発生していることを確認するには、DevTools の Network タブを開き、メソッドでフィルタリングして実際のリクエストの前にある OPTIONS リクエストを見つけます。