CORS ポリシー

このページは ApigeeApigee ハイブリッドに適用されます。

Apigee Edge のドキュメントはこちらをご覧ください。

ポリシー アイコン

概要

クロスオリジン リソース シェアリング(CORS)は、ウェブページで実行される JavaScript XMLHttpRequest(XHR)呼び出しがオリジン以外のドメインのリソースとやり取りできるようにする標準メカニズムです。CORS は、すべてのブラウザに組み込まれている同一オリジン ポリシーに対する一般的な解決策です。

たとえば、ブラウザで実行されている JavaScript コードから Twitter API への XHR 呼び出しは失敗します。その理由は、ブラウザに該当ページをサービスしているドメインが、Twitter API をサービスしているドメインと同じでないからです。CORS は、この制約を解消するための手段です。サーバーが異なるオリジンのリソースを共有したい場合に、サーバーがアクセスをオプトイン(承諾)できるようにします。

この CORS ポリシーを使用すると、ウェブ アプリケーションで使用される API に CORS ポリシーを設定できます。

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプでの利用可否については、ポリシータイプをご覧ください。

<CORS> 要素

CORS ポリシーを定義します。

デフォルト値 下の「デフォルト ポリシー」タブをご覧ください。
要否 必須
複合オブジェクト
親要素 なし
子要素 <AllowCredentials>
<AllowHeaders>
<AllowMethods>
<AllowOrigins>
<DisplayName>
<ExposeHeaders>
<GeneratePreflightResponse>
<IgnoreUnresolvedVariables>
<MaxAge>

<CORS> 要素の構文は次のとおりです。

構文

<CORS> 要素の構文は次のとおりです。


<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <DisplayName>DISPLAY_NAME</DisplayName>
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
  <MaxAge>[integer|-1]</MaxAge>
  <AllowCredentials>[false|true]</AllowCredentials>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

デフォルト ポリシー

次の例は、Edge UI でフローに CORS ポリシーを追加した場合のデフォルト設定を示しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

新しい CORS ポリシーを Apigee UI に挿入すると、テンプレートには使用可能なオペレーションすべてのスタブが含まれます。通常は、このポリシーで実行する操作を選択して、残りの子要素を削除します。たとえば、リソースへのアクセスを許可する HTTP メソッドを指定する場合は、<AllowMethods> 要素を使用してポリシーから他の子要素を削除して読みやすくします。

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

後続のセクションでは、これらの子要素についてそれぞれ説明します。

以下のセクションに、すべての子要素の例を示します。

子要素のリファレンス

このセクションでは、<CORS> の子要素について説明します。

<AllowCredentials>

呼び出し元が、認証情報を使用して実際のリクエスト(プリフライトではない)を送信できるかどうかを示します。Access-Control-Allow-Credentials ヘッダーに変換されます。

デフォルト値 指定しない場合、Access-Control-Allow-Credentials は設定されません。
要否 省略可
ブール値
親要素 <CORS>
子要素 なし

<AllowCredentials> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowCredentials>[false|true]</AllowCredentials>
</CORS>
      

この例では、Access-Control-Allow-Credentials ヘッダーを false に設定しています。つまり、呼び出し元は、認証情報を使用して(プリフライトではない)実際のリクエストを送信することはできません。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowCredentials>false</AllowCredentials>
</CORS>

<AllowHeaders>

リソースのリクエストに使用できる HTTP ヘッダーのリスト。Access-Control-Allow-Headers ヘッダーにシリアル化されます。

デフォルト値 Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
要否 省略可
文字列(メッセージ テンプレート* のサポートあり)
親要素 <CORS>
子要素 なし

* 詳細については、メッセージ テンプレートとはをご覧ください

<AllowHeaders> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
</CORS>

CORS AllowOrigins の例

この例では、リソースのリクエストに使用できる HTTP ヘッダーを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
</CORS>

<AllowMethods>

リソースへのアクセスが許可される HTTP メソッドのリスト。コンテンツは Access-Control-Allow-Methods ヘッダーにシリアル化されます。

デフォルト値 GET, POST, HEAD, OPTIONS
要否 省略可
文字列(メッセージ テンプレート* のサポートあり)
親要素 <CORS>
子要素 なし

* 詳細については、メッセージ テンプレートとはをご覧ください

<AllowMethods> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
</CORS>

例:
list

この例では、リソースへのアクセスが許可された HTTP メソッドを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

例:
Wildcard

この例では、すべての HTTP メソッドにリソースへのアクセスが許可されることを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

リソースへのアクセスを許可される送信元のリスト。アスタリスク(*)を使用して、任意の送信元からのリソースへのアクセスを有効にします。それ以外の場合は、送信元のカンマ区切りのリストを指定します。一致が見つかった場合、送信 Access-Control-Allow-Origin はクライアントから指定された送信元に設定されます。

デフォルト値 なし
要否 必須
文字列(メッセージ テンプレート* のサポートあり)
親要素 <CORS>
子要素 なし

* 詳細については、メッセージ テンプレートとはをご覧ください

<AllowOrigins> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
</CORS>

例:
単一の URL

この例では、リソースへのアクセスが許可された単一 URL オリジンを指定します。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

例:
複数の URL

この例では、リソースへのアクセスが許可された複数のオリジンを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

例:
コンテキスト変数

この例では、リソースへのアクセスが許可された 1 つ以上のオリジンを表すコンテキスト変数を指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

例:
フロー変数

この例では、リソースへのアクセスが許可された 1 つのオリジンを表すフロー変数を指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

例:
Wildcard

この例では、すべてのオリジンがリソースへのアクセスを許可されていることを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値 なし
必須かどうか 省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<ExposeHeaders>

ブラウザでアクセスを許可する HTTP ヘッダーのリスト。すべての HTTP ヘッダーを許可する場合はアスタリスク(*)。Access-Control-Expose-Headers ヘッダーにシリアル化します。

デフォルト値 指定しない場合、Access-Control-Expose-Headers は設定されません。単純ではないヘッダーは、デフォルトでは公開されません。
要否 省略可
文字列(メッセージ テンプレート* のサポートあり)
親要素 <CORS>
子要素 なし

* 詳細については、メッセージ テンプレートとはをご覧ください

<ExposeHeaders> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
</CORS>

この例では、ブラウザにすべての HTTP ヘッダーへのアクセスが許可されることを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <ExposeHeaders>*</ExposeHeaders>
</CORS>

<GeneratePreflightResponse>

CORS プリフライト レスポンスを生成してポリシーで返す必要があるかどうかを示します。false の場合、レスポンスは送信されません。代わりに、次のフロー変数が入力されます。

  • cross_origin_resource_sharing.allow.credentials
  • cross_origin_resource_sharing.allow.headers
  • cross_origin_resource_sharing.allow.methods
  • cross_origin_resource_sharing.allow.origin
  • cross_origin_resource_sharing.allow.origins.list
  • cross_origin_resource_sharing.expose.headers
  • cross_origin_resource_sharing.max.age
  • cross_origin_resource_sharing.preflight.accepted
  • cross_origin_resource_sharing.request.headers
  • cross_origin_resource_sharing.request.method
  • cross_origin_resource_sharing.request.origin
  • cross_origin_resource_sharing.request.type
デフォルト値 true
要否 省略可
ブール値
親要素 <CORS>
子要素 なし

<GeneratePreflightResponse> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</CORS>

この例では、ポリシーで CORS プリフライト レスポンスを生成して返すことを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <GeneratePreflightResponse>true</GeneratePreflightResponse>
</CORS>

<IgnoreUnresolvedVariables>

未解決の変数に突き当たった場合に、処理を停止するかどうかを決定します。true を設定すると、未解決の変数を無視して処理を続行できます。それ以外の場合は false を設定します。

デフォルト値 true
要否 省略可
ブール値
親要素 <CORS>
子要素 なし

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

この例では、未解決の変数が検出された場合に処理を続行するように指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

<MaxAge>

プリフライト リクエストの結果をキャッシュに保存できる期間を秒単位で指定します。-1 の値では、Access-Control-Max-Age ヘッダーに -1 の値が設定されます。これによりキャッシュが無効になり、プリフライト OPTIONS が必要になります。すべての呼び出しを確認します。これは Access-Control-Max-Age 仕様で定義されています。

デフォルト値 1800
要否 省略可
整数
親要素 <CORS>
子要素 なし

<MaxAge> 要素の構文は次のとおりです。

構文

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <MaxAge>[integer|-1]</MaxAge>
</CORS>

例:
キャッシュに保存

この例では、プリフライト リクエストの結果を 3628800 秒間キャッシュに保存できることを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

例:
キャッシュに保存なし

この例では、プリフライト リクエストの結果がキャッシュに保存できないことを指定しています。

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>-1</MaxAge>
</CORS>

使用上の注意

OPTIONS リクエスト

OPTIONS リクエストを受信して CORS ポリシーによって処理した場合、プロキシフローの実行はプロキシ レスポンスの PreFlow に直接転送され、リクエスト フローは完全にスキップされて、そこから実行が続行されます。プロキシ リクエスト フローで OPTIONS リクエストを無視する条件を作成する必要はありません。

以降の呼び出しで CORS ポリシーが実行されるときに、ポリシーに設定された MaxAge の期限が切れていない場合、フローは通常どおり続行されます。「Response Sent to Client」の直前の最後のレスポンス フロー内で、特別な CORS 実行ステップ「CORSResponseOrErrorFlowExecution」によって CORS レスポンス ヘッダー(Access-Control-Allow-CredentialsAccess-Control-Allow-OriginAccess-Control-Expose-Headers)が設定され、CORS 検証済みのレスポンスが返されます。

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因
steps.cors.UnresolvedVariable 500 このエラーは、CORS ポリシーで指定された変数が次のいずれかの場合に発生します。
  • 範囲外(ポリシーが実行されている特定のフローで使用できない)
  • または

  • 解決不能(未定義)

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名 原因
InvalidMaxAge MaxAge が数値ではありません。
MissingAllowOrigins AllowOrigins が指定されていません。
InvalidHTTPMethods AllowMethods のメソッドのいずれかが無効です。
AllowHeadersSizeTooLarge AllowHeaders の文字列サイズが大きすぎます。
ExposeHeadersSizeTooLarge ExposeHeaders の文字列サイズが大きすぎます。

障害変数

次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数 説明
fault.name = "FAULT_NAME" FAULT_NAME は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed POLICY_NAME は、障害が発生したポリシーのユーザー指定の名前です。 cors.AddCORS.failed = true

エラー レスポンスの例

{
   "fault":{
      "detail":{
         "errorcode":"steps.cors.UnresolvedVariable"
      },
      "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var"
   }
}

障害ルールの例

<FaultRule name="Add CORS Fault">
    <Step>
        <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Condition>(cors.Add-CORS.failed = true) </Condition>
</FaultRule>

フロー変数

CorsFlowInfo FlowInfo オブジェクトが追加され、トレースに使用可能になります。

プロパティ 読み取りと書き込み 説明 スコープの開始
cross_origin_resource_sharing.allow.credentials ブール値 読み取りと書き込み <AllowCredentials> からの値 プロキシ リクエスト
cross_origin_resource_sharing.allow.headers 文字列 読み取りと書き込み <AllowHeaders> からの値 プロキシ リクエスト
cross_origin_resource_sharing.allow.methods 文字列 読み取りと書き込み <AllowMethods> からの値 プロキシ リクエスト
cross_origin_resource_sharing.allow.origin 文字列 読み取りと書き込み 許可されたリクエストの送信元。許可リストに含まれていない場合は空 プロキシ リクエスト
cross_origin_resource_sharing.allow.origins.list 文字列 読み取りと書き込み <AllowOrigins> からの値 プロキシ リクエスト
cross_origin_resource_sharing.expose.headers 文字列 読み取りと書き込み <ExposeHeaders> からの値 プロキシ リクエスト
cross_origin_resource_sharing.max.age 整数 読み取りと書き込み <MaxAge> からの値 プロキシ リクエスト
cross_origin_resource_sharing.preflight.accepted ブール値 読み取りと書き込み プリフライト リクエストが受け入れられるかどうかを示します プロキシ リクエスト
cross_origin_resource_sharing.request.headers 文字列 読み取りと書き込み リクエスト Access-Control-Request-Headers ヘッダーの値 プロキシ リクエスト
cross_origin_resource_sharing.request.method 文字列 読み取りと書き込み リクエスト Access-Control-Request-Method ヘッダーの値 プロキシ リクエスト
cross_origin_resource_sharing.request.origin 文字列 読み取りと書き込み request.header.origin と同じ プロキシ リクエスト
cross_origin_resource_sharing.request.type 文字列 読み取りと書き込み

CORS リクエストの型。値は次のいずれかです。

  • ACTUAL: プリフライト リクエストではないリクエスト
  • PRE_FLIGHT: プリフライト リクエスト
プロキシ リクエスト