CORS

  • [アーティクル]

適用対象: すべての API Management レベル

corsポリシーは、クロス オリジン リソース共有 (CORS) のサポートを操作または API に追加して、ブラウザーベースのクライアントからのドメイン間呼び出しを可能にします。

Note

ポリシーの要素と子要素を、ポリシー ステートメントで指定された順序で設定します。 このポリシーの構成に役立つ、ガイド付きのフォーム ベース エディターがポータルに用意されています。 API Management ポリシーを設定または編集する方法について説明します。

ポリシー ステートメント

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

属性

Name 説明 必要 Default
allow-credentials 事前応答内の Access-Control-Allow-Credentials ヘッダーが、この属性の値に設定されます。これは、クライアントがクロス ドメイン要求で資格情報を送信できるかどうかに影響します。 ポリシー式を使用できます。 いいえ false
terminate-unmatched-request ポリシー設定と一致しないクロスオリジン要求の処理を制御します。 ポリシー式を使用できます。

OPTIONS 要求がプレフライト要求として処理され、Origin ヘッダーがポリシー設定と一致しない場合:
- 属性が true に設定されている場合は、空の 200 OK 応答で要求を直ちに終了します
- 属性が false に設定されている場合は、inbound 要素の直接の子である他のスコープ内 cors ポリシーがないか inbound を調べて、それらを適用します。 cors ポリシーが見つからなければ、空の 200 OK 応答で要求を終了します。

GET または HEAD 要求に Origin ヘッダーが含まれ (したがって、単純なクロスオリジン要求として処理されます)、ポリシー設定と一致しない場合:
- 属性が true に設定されている場合は、空の 200 OK 応答で要求を直ちに終了します。
- 属性が false に設定されている場合は、要求が正常に続行されることを許可し、応答に CORS ヘッダーを追加しません。		 No true

要素

名前 説明 必要 Default
allowed-origins クロス ドメイン要求で許可される配信元を示す origin 要素を含みます。 allowed-origins に含めることができるのは、すべての配信元を許可する *を含む 1 つの origin 要素か、URI を含む 1 つ以上の origin 要素です。 はい 該当なし
allowed-methods この要素は、GET または POST 以外のメソッドが許可される場合に必須です。 サポートされる HTTP 動詞を指定する method 要素が含まれます。 * 値は、すべてのメソッドを示します。 いいえ このセクションが存在しない場合、GET と POST がサポートされています。
allowed-headers この要素には、要求に組み込むことができるヘッダーの名前を指定する header 要素が含まれます。 はい 該当なし
expose-headers この要素には、クライアントがアクセスできるヘッダーの名前を指定する header 要素が含まれます。 いいえ 該当なし

注意事項

ポリシー設定では*ワイルドカードを慎重に使用してください。 この構成では制限が過度に緩められ、API が特定の API セキュリティの脅威に対してより脆弱になるおそれがあります。

allowed-origins 要素

Name 説明 必要 Default
origin 値として使用できるのは、すべての配信元を許可する * か、1 つの配信元を指定する URI です。 URI には、スキーム、ホスト、およびポートを含める必要があります。 引用符は含めません。 はい URI でポートが省略されると、HTTP ではポート 80、HTTPS ではポート 443 が使用されます。

allowed-methods の属性

名前 説明 必要 Default
preflight-result-max-age プレフライト応答内の Access-Control-Max-Age ヘッダーが、この属性の値に設定されます。これは、ユーザー エージェントがプレフライト応答をキャッシュできるかどうかに影響します。 ポリシー式を使用できます。 いいえ 0

allowed-methods 要素

Name 説明 必要 Default
method HTTP 動詞を指定します。 ポリシー式を使用できます。 allowed-methods セクションが存在する場合、少なくとも 1 つの method 要素が必要です。 該当なし

allowed-headers 要素

Name 説明 必要 Default
header ヘッダー名を指定します。 このセクションが存在する場合、少なくとも 1 つの header 要素が allowed-headers に必要です。 該当なし

expose-headers 要素

Name 説明 必要 Default
header ヘッダー名を指定します。 このセクションが存在する場合、少なくとも 1 つの header 要素が expose-headers に必要です。 該当なし

使用法

使用上の注意

  • cors ポリシーは複数のスコープ (成果物スコープとグローバル スコープなど) で構成することができます。 親スコープで必要なポリシーを継承するように、base 要素が操作、API、成果物スコープで構成されていることを確認します。
  • プレフライト中に OPTIONS 要求で評価されるのは cors ポリシーだけです。 構成された残りのポリシーは、承認された要求で評価されます。
  • このポリシーは、ポリシー セクションで 1 回だけ使用できます。

CORS について

CORS は HTTP のヘッダーベースの標準で、ブラウザーとサーバーのやり取りを介して、特定のクロスオリジン要求 (Web ページ上の JavaScript から他のドメインに対して行われる XMLHttpRequest 呼び出し) を許可するかどうかを決めることができます。 これにより、単に同一オリジンの要求を許可するよりも高い柔軟性が得られる一方、すべてのクロス オリジン要求を許可するよりも高いセキュリティを実現できます。

CORS では、2 種類のクロスオリジン要求を規定しています。

  • プレフライト要求 - ブラウザーはまず、OPTIONS メソッドを使ってサーバーに HTTP 要求を送信し、実際の要求が送信を許可されているかどうかを判断します。 サーバーの応答に、アクセスを許可する Access-Control-Allow-Origin ヘッダーが含まれている場合、ブラウザーは実際の要求に従います。

  • 単純要求 - これらの要求には、1 つ以上の追加の Origin ヘッダーが含まれますが、CORS プレフライトはトリガーされません。 GET と HEAD メソッドを使う要求と、限られた要求ヘッダーのセットのみが許可されます。

cors ポリシーのシナリオ

次のシナリオでは、API Management で cors ポリシーを構成します。

  • 開発者ポータルの対話型テスト コンソールを有効にします。 詳細については、開発者ポータルのドキュメントを参照してください。

    Note

    対話型コンソールで CORS を有効にすると、既定では API Management によりグローバル スコープで cors ポリシーが構成されます。

  • バックエンドが独自の CORS サポートを提供しない場合に、API Management がプレフライト要求に応答するか、単純な CORS 要求を通過させるようにします。

    Note

    要求が、API で定義されている OPTIONS メソッドでの操作と一致する場合、cors ポリシーに関連付けられているプレフライト要求の処理ロジックは実行されません。 そのため、このような操作を使って、カスタムのプレフライト処理ロジックを実装することができます。たとえば、特定の条件下でのみ cors ポリシーを適用できます。

一般的な構成の問題

  • ヘッダーのサブスクリプション キー - cors ポリシーを "成果物" スコープで構成し、API でサブスクリプション キー認証を使う場合、サブスクリプション キーがヘッダーで渡されるとポリシーは機能しません。 回避策として、サブスクリプション キーをクエリ パラメーターとして含むように要求を変更します。
  • ヘッダーのバージョン管理機能を使う API - cors ポリシーを API スコープで構成した場合、API がヘッダーのバージョン管理スキームを使うと、バージョンがヘッダーで渡されるためポリシーは機能しません。 パスやクエリ パラメーターなど、別のバージョン管理方法を構成する必要がある場合があります。
  • ポリシーの順序 - cors ポリシーが受信セクションの最初のポリシーでない場合、予期しない動作が発生することがあります。 ポリシー エディターで [有効なポリシーの計算] を選び、各スコープでポリシーの評価順序を確認します。 一般に、最初の cors ポリシーだけが適用されます。
  • 空の 200 OK 応答 - 一部のポリシー構成では、特定のクロスオリジン要求が空の 200 OK 応答で完了します。 この応答は、terminate-unmatched-request がその既定値である true に設定され、受信要求が cors ポリシーで構成された許容オリジンに一致しない Origin ヘッダーを持つ場合に予期されます。

例

この例では、カスタム ヘッダーまたは GET や POST 以外のメソッドを含んでいるなどのプレフライト要求に対応する方法を示します。 カスタム ヘッダーやその他の HTTP 動詞をサポートするには、次の例に示すように allowed-methods および allowed-headers セクションを使用します。

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

関連するコンテンツ

ポリシーに対する処理の詳細については、次のトピックを参照してください。