CORS ポリシー

このページは 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 なし 必須

ポリシーの内部名。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

此示例指定允许访问资源的单个网址源。

<CORS continueOnError="false" enabled="true"< name="add-cors">
<  AllowOrigins&<gt;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>

例:
フロー変数

此示例指定一个流变量,该变量表示允许访问资源的一个源。

<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-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 リクエストの型。値は次のいずれかです。

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