API プロキシへの CORS サポートの追加

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

Apigee Edge ドキュメントを表示する

CORS（クロスオリジンリソースシェアリング）は、ウェブページで実行される JavaScript XMLHttpRequest（XHR）呼び出しがオリジン以外のドメインのリソースとやり取りできるようにする標準的なメカニズムです。CORS は、すべてのブラウザに組み込まれている同一オリジンポリシーに対する一般的な解決策です。たとえば、ブラウザで実行されている JavaScript コードから Twitter API への XHR 呼び出しは失敗します。これは、ブラウザに該当ページを提供しているドメインが、Twitter API を提供しているドメインと異なるためです。CORS は、この制約を解消するための手段です。サーバーが異なるオリジンのリソースを共有したい場合に、サーバーがアクセスをオプトイン（承諾）できるようにします。

CORS の一般的な使用例

次の JQuery コードは架空のターゲットサービスを呼び出します。この呼び出しをブラウザ（ウェブページ）のコンテキストから実行すると、同一オリジンポリシーにより呼び出しが失敗します。

<script>
var url = "http://service.example.com";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This is where we end up!
            }
    });
  });
});
</script>

この制約を回避する一つの方法として、バックエンドでサービス API を呼び出す Apigee API プロキシを作成する方法があります。Apigee はクライアント（この場合はブラウザ）とバックエンド API（サービス）の間に存在します。API プロキシはブラウザではなくサーバー上で実行されるため、サービスを正常に呼び出すことができます。この場合、必要な作業は TargetEndpoint レスポンスに CORS ヘッダーを追加することだけです。ブラウザで CORS がサポートされていれば、これらのヘッダーにより、ブラウザは同一オリジンポリシーを「緩和」しても問題ないことを認識し、クロスオリジン API 呼び出しが正常に動作するようになります。

CORS をサポートするプロキシを作成したら、クライアント側のコードでバックエンドサービスではなく API プロキシ URL を呼び出すことができます。次に例を示します。

<script>
var url = "http://myorg-test.apigee.net/v1/example";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This time, we do not end up here!
            }
    });
  });
});
</script>

ProxyEndpoint のリクエスト PreFlow への CORS ポリシーの接続

新しい API プロキシへの Add CORS ポリシーの接続

API プロキシに CORS サポートを追加するには、次の方法で Add CORS ポリシーを API プロキシに適用します。

[Build a Proxy] ウィザードの [Security] ページで [Add CORS headers] チェックボックスをオンにしてポリシーを作成する
[Add Policy] ダイアログで後で追加する

チェックボックスをオンにして CORS ポリシーを追加すると、「Add CORS」というポリシーが自動的に追加され、TargetEndpoint リクエスト PreFlow に接続します。

Add CORS ポリシーは、レスポンスに適切なヘッダーを追加します。これらのヘッダーにより、リソースを共有するオリジンや許可するメソッドなどをブラウザに知らせることができます。CORS ヘッダーの詳細については、クロスオリジンリソースシェアリングの W3C 勧告をご覧ください。

次のようにポリシーを変更する必要があります。

このコードの抜粋のように、content-type と authorization ヘッダー（基本認証または OAuth2 のサポートに必要）を Access-Control-Allow-Headers ヘッダーに追加します。
OAuth2 認証の場合は、RFC を遵守していない動作を修正する必要があります。

<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, authorization</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

既存のプロキシへの CORS ヘッダーの追加

新しいプロキシエディタ

既存の API プロキシに CORS ポリシーを追加するには:

Cloud コンソールの Apigee UI を使用している場合: [プロキシ開発] > [API プロキシ] を選択します。

従来の Apigee UI を使用している場合: [Develop] > [API Proxies] を選択して、[Proxies] ペインでプロキシの環境を選択します。
CORS ポリシーを追加する API プロキシを選択します。
新しい API プロキシエディタで、[開発] タブをクリックします。
左側のパネルで、[ポリシー] 行の [+] ボタンをクリックします。
[ポリシーの作成] ダイアログで、[Select policy type] フィールドをクリックし、[セキュリティ] まで下にスクロールして、[CORS] を選択します。
ポリシーの詳細を入力し、[作成] をクリックします。
左側のペインで、[ターゲットエンドポイント] > [デフォルト] の下にある [PreFlow] をクリックします。
左側のペインで [Proxy Endpoints] > [デフォルト] > [PreFlow] を選択します。
ビジュアルエディタの右下にある [Response] ペインの [PreFlow] の横にある [+] ボタンをクリックします。
[Add policy step] ダイアログで、[CORS] ポリシーを選択します。
[追加] をクリックしてポリシーを適用します。

従来のプロキシエディタ

既存の API プロキシに CORS ポリシーを追加するには:

Apigee UI にログインします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択します。

今すぐ試す

Develop

[今すぐ試す] ボタンについて

プロキシエディタの新しいバージョンを初めて使用した場合、[開発] ビューの上部に次のバナーが表示されます。

[今すぐ試す] ボタン

[今すぐ試す] ボタンをクリックして、新しい [開発] ビューを表示します。

[開発] ビューを以下に示します。

プロキシエディタの [開発] ビュー

CORS ポリシーを追加する API プロキシを選択します。
新しい API プロキシエディタで、[開発] タブをクリックします。

左側のナビゲータペインで、[ターゲットエンドポイント] > [デフォルト] の下にある [PreFlow] をクリックします。
リクエストの PreFlow に対応する最上部の [+ ステップ] ボタンをクリックします。これにより、作成可能なポリシーの一覧がカテゴリ別に表示されます。
[セキュリティ] カテゴリで [CORS] を選択します。
Add CORS などの名前を指定して、[追加] をクリックします。

CORS プリフライトリクエストの処理

CORS プリフライトとは、サーバーにリクエストを送信して相手が CORS に対応しているかどうかを確認することです。一般的なプリフライトレスポンスには、サーバーが CORS リクエストを受け入れるオリジン、CORS リクエストでサポートされている HTTP メソッドの一覧、リソースリクエストの一部として使用できるヘッダー、プリフライトリクエストがキャッシュに保存される最長時間などが含まれます。サービスが CORS をサポートしていない場合や、クライアントのオリジンからのクロスオリジンリクエストを承諾していない場合、ブラウザのクロスオリジンポリシーが適用され、サーバーにホストされているリソースとやり取りするためにクライアントから送信されたクロスドメインリクエストは失敗します。

通常、CORS プリフライトリクエストは HTTP OPTIONS メソッドによって行われます。CORS をサポートしているサーバーが OPTIONS リクエストを受信すると、CORS サポートのレベルを示す一連の CORS ヘッダーをクライアントに返します。この handshake の結果、クライアントは、オリジン以外のドメインからリクエストできる内容を認識します。

注: プロキシエンドポイント PreFlow に Verify API key ポリシーが設定されている場合、そのポリシーはすべての受信リクエストに適用されます。CORS プリフライトリクエストにポリシーを適用する場合、メソッドが OPTIONS のときにスキップする条件を追加します。たとえば、次の API プロキシ構成を使用します。

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Name>verify-api-key</Name>
            <Condition>request.verb != "OPTIONS"</Condition>
        </Step>
    </Request>
    <Response/>
</PreFlow>

プリフライトの詳細については、クロスオリジンリソースシェアリングの W3C 勧告をご覧ください。CORS については、参考になるブログや記事が他にも多数あります。

Apigee には、すぐに使用できる CORS プリフライトソリューションは用意されていませんが、このセクションの説明に従って実装できます。プロキシが条件付きフローで OPTIONS リクエストを評価できるようにすることで、プロキシは適切なレスポンスをクライアントに返すことができます。

まず、サンプルのフローを示します。その後に、プリフライトリクエストを処理する各部分について説明します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <Description/>
    <Flows>
        <Flow name="OptionsPreFlight">
            <Request>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Request>
            <Response/>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
        </Flow>
    </Flows>

    <PreFlow name="PreFlow">
        <Request/>
        <Response/>

    </PreFlow>
    <HTTPProxyConnection>
        <BasePath>/v1/cnc</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="NoRoute">
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
    </RouteRule>
    <RouteRule name="default">
        <TargetEndpoint>default</TargetEndpoint>
   </RouteRule>
   <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
</ProxyEndpoint>

この ProxyEndpoint では重要な部分は次のとおりです。

RouteRule は、OPTIONS リクエストの条件が指定されている NULL ターゲットに作成されます。TargetEndpoint が指定されていないことに注意してください。OPTIONS リクエストを受信し、Origin と Access-Control-Request-Method リクエストヘッダーが null でない場合、クライアントへのレスポンスでプロキシはすぐに（デフォルトのバックエンドターゲットをバイパスして）CORS ヘッダーを返します。フロー条件と RouteRule の詳細については、フロー変数での条件をご覧ください。
```
<RouteRule name="NoRoute">
    <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
</RouteRule>
```

OPTIONS リクエストを受信し、Origin と Access-Control-Request-Method リクエストヘッダーが null でない場合、CORS ヘッダーのほかに、Add CORS ポリシーをフローに追加する OptionsPreFlight フローが作成されます。

 <Flow name="OptionsPreFlight">
            <Request>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Request>
            <Response/>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
 </Flow>