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>

例

This example sets the Access-Control-Allow-Credentials header to false. That is, the caller is not allowed to send the actual request (not the preflight) using credentials.

<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> に追加する値は 50 個以下にすることをおすすめします。

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

<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

This example specifies the HTTP methods that are allowed to access the resource.

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

例:
Wildcard

This example specifies that all HTTP methods are allowed to access the resource.

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

`<AllowOrigins>`

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

デフォルト値	なし
必須かどうか	必須
型	文字列（メッセージテンプレート* のサポートあり）
親要素	`<CORS>`
子要素	なし

ヒント: <AllowOrigins> に追加する値は 50 個以下にすることをおすすめします。

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

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

構文

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

例:
単一の URL

This example specifies a single URL origin that is allowed to access the resource.

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

例:
複数の URL

This example specifies multiple origins that are allowed to access the resource.

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

例:
コンテキスト変数

This example specifies a context variable that represents one or more origins that are allowed to access the resource.

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

例:
フロー変数

This example specifies a flow variable that represents one origin that is allowed to access the resource.

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

例:
Wildcard

This example specifies that all origins are allowed to access the resource.

Caution: If a proxy developer sets the Access-Control-Allow-Origin header to allow all (*), it effectively disables the same-origin protection. The default should not be set to allow all (*). Policy developers should make cautious decisions before exposing their resources.

<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> に追加する値は 50 個以下にすることをおすすめします。

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

<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>

例

This example specifies that the browsers are allowed to access all HTTP headers.

<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>

例

This example specifies that the policy should generate and return the CORS preflight response.

<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>

例

This example specifies that processing continues when an unresolved variable is encountered.

<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>

例:
キャッシュに保存

This example specifies that the results of a preflight request can be cached for 3628800 seconds.

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

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

This example specifies that the results of a preflight request cannot be cached.

<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 検証済みのレスポンスが返されます。

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.cors.UnresolvedVariable`	`500`	This error occurs if a variable specified in the CORS policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`InvalidMaxAge`	`MaxAge` is not number
`MissingAllowOrigins`	`AllowOrigins` is not specified
`InvalidHTTPMethods`	One of the methods in `AllowMethods` is not valid
`AllowHeadersSizeTooLarge`	The string size in `AllowHeaders` is too large.
`ExposeHeadersSizeTooLarge`	The string size in `ExposeHeaders` is too large.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Note : If <GeneratePreflightResponse> is set to true and an error occurs, the policy returns a response to the client immediately and the error flow is skipped. The following variables are not populated:

Variables	Where	Example
`fault.name = "FAULT_NAME"`	`FAULT_NAME` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "UnresolveVariable"`
`cors.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`cors.AddCORS.failed = true`

Example error response

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

Example fault rule

<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 リクエスト

エラーコード

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

フロー変数

CORS ポリシー

`<CORS>` 要素

デフォルトポリシー

`<AllowCredentials>`

`<AllowHeaders>`

`<AllowMethods>`

例:
list

例:
Wildcard

`<AllowOrigins>`

例:
単一の URL

例:
複数の URL

例:
コンテキスト変数

例:
フロー変数

例:
Wildcard

`<DisplayName>`

`<ExposeHeaders>`

`<GeneratePreflightResponse>`

`<IgnoreUnresolvedVariables>`

`<MaxAge>`

例:
キャッシュに保存

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

`OPTIONS` リクエスト