このページは Apigee と Apigee ハイブリッドに適用されます。
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 |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
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>
例
This example specifies the HTTP headers that can be used when requesting the resource.
<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.credentialscross_origin_resource_sharing.allow.headerscross_origin_resource_sharing.allow.methodscross_origin_resource_sharing.allow.origincross_origin_resource_sharing.allow.origins.listcross_origin_resource_sharing.expose.headerscross_origin_resource_sharing.max.agecross_origin_resource_sharing.preflight.acceptedcross_origin_resource_sharing.request.headerscross_origin_resource_sharing.request.methodcross_origin_resource_sharing.request.origincross_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 の文字列サイズが大きすぎます。 |
障害変数
次の変数は、このポリシーでランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。
| 変数 | 説明 | 例 |
|---|---|---|
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 リクエストの型。値は次のいずれかです。
|
プロキシ リクエスト |