CORS ポリシー

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

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

概要

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

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

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

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

ユースケース

CORS の一般的なユースケースの一つとして、デベロッパーポータルの SmartDoc のこの API を試す機能があります。

詳しくは、Try this API パネルをサポートするように API プロキシを構成するをご覧ください。

`<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` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`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

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

注意: プロキシデベロッパーが Access-Control-Allow-Origin ヘッダーをすべて許可（*）に設定した場合、同一オリジン保護が実質的に無効になります。デフォルトをすべて許可（*）に設定しないでください。ポリシーデベロッパーは、リソースを公開する前に慎重に判断する必要があります。

<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-Credentials、Access-Control-Allow-Origin、Access-Control-Expose-Headers）が設定され、CORS 検証済みのレスポンスが返されます。

エラーコード

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

ランタイムエラー

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

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

デプロイエラー

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

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

障害変数

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

注: <GeneratePreflightResponse> が true に設定され、エラーが発生した場合、ポリシーはすぐにクライアントにレスポンスを返し、エラーフローはスキップされます。次の変数には値が入力されません。

変数	説明	例
`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: プリフライトリクエスト	プロキシリクエスト

CORS ポリシー

概要

ユースケース

<CORS> 要素

構文

デフォルト ポリシー

例

子要素のリファレンス

<AllowCredentials>

構文

例

<AllowHeaders>

構文

例

<AllowMethods>

構文

例: list

例: Wildcard

<AllowOrigins>

構文

例: 単一の URL

例: 複数の URL

例: コンテキスト変数

例: フロー変数

例: Wildcard

<DisplayName>

構文

例

<ExposeHeaders>

構文

例

<GeneratePreflightResponse>

構文

例

<IgnoreUnresolvedVariables>

構文

例

<MaxAge>

構文

例: キャッシュに保存

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

使用上の注意

OPTIONS リクエスト

エラーコード

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

フロー変数

`<CORS>` 要素

デフォルトポリシー

`<AllowCredentials>`

`<AllowHeaders>`

`<AllowMethods>`

例:
list

例:
Wildcard

`<AllowOrigins>`

例:
単一の URL

例:
複数の URL

例:
コンテキスト変数

例:
フロー変数

例:
Wildcard

`<DisplayName>`

`<ExposeHeaders>`

`<GeneratePreflightResponse>`

`<IgnoreUnresolvedVariables>`

`<MaxAge>`

例:
キャッシュに保存

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

`OPTIONS` リクエスト

ランタイムエラー

エラーレスポンスの例