Cloud 用仮想ホストの構成

有料アカウントをお持ちの Cloud のお客様は、組織内に仮想ホストを作成できます。

詳細:

• 仮想ホストについて
• 仮想ホストの構成
• TLS の構成
• キーストアとトラストストア

Cloud で仮想ホストを作成、変更できるユーザー

Edge Cloud では、有料アカウントのユーザーのみ、仮想ホストの作成と変更をご利用いただけます。仮想ホストを作成するユーザーには、組織管理者のロールか、仮想ホストの変更権限を持つカスタムロールが割り当てられている必要があります。これら以外のロールのユーザーには仮想ホストを作成する権限がありません。

たとえば、有料アカウントのお客様は、以下の操作が可能です。

• 一方向と双方向の TLS の有効化
• 仮想ホストで使用するキーストア / トラストストアの指定

無料アカウントまたはトライアル アカウントでは、仮想ホストの作成や変更ができません。Edge 登録時に作成した仮想ホストのみをご利用いただけます。Edge の料金プランの詳細については、https://apigee.com/api-management/#/pricing をご覧ください。

Cloud 用仮想ホストの構成の要件

次の表は、仮想ホスト作成の要件をまとめたものです。

ブラウザを使用した仮想ホストの作成

下記の例の大部分は、Edge API を使用して仮想マシンの作成や変更を行っていますが、仮想ホストは Edge UI で作成できます。

Edge UI を使用して仮想ホストを作成するには:

1. apigee.com/edge にログインします。
2. [Admin] > [Virtual Hosts] を選択します。
3. prod、test などの環境を選択します。
4. [+ Virtual Host] を選択して仮想ホストを作成するか、既存の仮想ホストの名前を選択して編集します。
5. 仮想ホストの各フィールドへのデータ入力について詳しくは、上記の表をご覧ください。

一方向 TLS の仮想ホストの定義

仮想ホストを定義する XML オブジェクトです。たとえば、次の XML オブジェクトでは、一方向 TLS の仮想ホストが定義されます。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

この定義の内容は以下のとおりです。

• 名前に myTLSVHost を指定します。この名前を使用して、API プロキシまたは API 呼び出しで仮想ホストを参照します。
• ホスト エイリアスに api.myCompany.com を指定します。これは、DNS 定義と CNAME レコードによる定義に従って API にアクセスするために使用される公開ドメインです。
• ポート番号に 443 を指定します。省略した場合は、デフォルトでポートが 443 に設定されます。
• 必要に応じて TLS を有効にします。
  
  <Enable> 要素が true に設定されると一方向の TLS が有効になります。<KeyStore> 要素には、TLS 接続で使用されるキーストアと鍵のエイリアスを指定します。
  
  双方向の TLS を有効にするには、<ClientAuthEnabled> を true に設定し、<TrustStore> 要素を使用してトラストストアを指定します。トラストストアにクライアントの証明書が格納されます。また、必要に応じて証明書の CA チェーンも格納できます。
  
  注: Edge では元々 SSL がサポートされていたため、TLS の構成に使用するタグの名前は <SSLInfo> です。

仮想ホストには、これら以外にも設定可能なプロパティが存在します。すべてのプロパティのリファレンスについては、仮想ホストのプロパティ リファレンスをご覧ください。

仮想ホストにキーストアとトラストストア名を指定する方法を決定する

TLS をサポートするように仮想ホストを構成する際は、参照を使用してキーストアを指定します。参照とは、キーストアやトラストストアの名前を直接指定するのではなく、以下に示すように、キーストアやトラストストアの名前を格納する変数です。

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>

通常、現在のキーストア内の証明書は近い将来に期限切れになります。そのため、参照を使用することには、仮想ホストで使用するキーストアを変更する際にその値を変更するだけでよいという利点があります。参照の値を変更する際、Edge Router を再起動する必要はありません。参照の作成と変更について詳しくは、参照の使用をご覧ください。

参照はキーストアとトラストストアに対してのみ使用できます。エイリアスへの参照は使用できません。キーストアへの参照を変更するときは、証明書のエイリアス名が古いキーストアのものと同じであることを確認してください。

キーストアとトラストストアへの参照の使用に関する制限事項

キーストアとトラストストアへの参照を使用する際は、以下の制限事項を考慮する必要があります。

• 仮想ホストでキーストアとトラストストアへの参照を使用できるのは、SNI をサポートしていて、SSL を Apigee Router で終端する場合だけです。
• Apigee Router の前にロードバランサが存在し、TLS をロードバランサで終端している場合、仮想ホストでキーストアとトラストストアへの参照は使用できません。

双方向 TLS の仮想ホストの定義

双方向の TLS を有効にするには、<ClientAuthEnabled> 要素を true に設定し、<TrustStore> 要素で reference を使用してトラストストアを指定します。トラストストアにクライアントの証明書が格納されます。また、必要に応じて証明書の CA チェーンも格納できます。クライアントでも双方向 TLS が正しく構成されている必要があります。

双方向 TLS の仮想ホストを作成するには、仮想ホストを定義する XML オブジェクトを作成します。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
</VirtualHost>

この定義の内容は以下のとおりです。

• <ClientAuthEnabled> を true に設定して、双方向 TLS を有効にします。
• <TrustStore> 要素を使用して、トラストストアへの参照を指定します。トラストストアにクライアントの証明書が格納されます。また、必要に応じて証明書の CA チェーンも格納できます。

Apigee 無料トライアルの証明書とキーを使用する仮想ホストの定義

有料の Edge for Cloud アカウントをお持ちで、まだ TLS 証明書と鍵を準備していない場合は、Apigee 無料トライアル証明書と鍵を使用する仮想ホストを作成できます。つまり、先にキーストアを作成しなくても仮想ホストを作成できます。

Apigee 無料トライアルの証明書は、*.apigee.net のドメインに定義されています。したがって、仮想ホストの <HostAlias> も *.apigee.net の形式にする必要があります。

双方向 TLS を実行する場合は、双方向 TLS の仮想ホストの定義の説明に従って、<ClientAuthEnabled> 要素に true を設定し、<TrustStore> 要素で reference を使用してトラストストアを指定する必要があります。

Apigee 無料トライアルの証明書と鍵を使用して仮想ホストを定義する XML オブジェクトでは、次のように <KeyStore> 要素と <KeyAlias> 要素が省略され、<UseBuiltInFreeTrialCert> 要素に置き換えられます。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

<UseBuiltInFreeTrialCert> 要素のデフォルト値は false です。

双方向 TLS の場合は、仮想ホストを次のように定義します。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <TrustStore>ref://myTestTruststoreRef</TrustStore>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

仮想ホストの作成時に Edge UI で [Use built-in free trial certificate] オプションを選択して、無料の Apigee 証明書と鍵を使用します。

仮想ホストの作成

仮想ホストを作成する手順は次のとおりです。

1. 公開ドメイン（この例では api.myCompany.com）用に、[org]-[environment].apigee.net を参照する DNS エントリと CNAME レコードを作成します。
2. Edge UI を使用したキーストアとトラストストアの作成に記載された手順を使用して、キーストア（この例では myTestKeystore という名前のキーストア）を作成して構成します。この例では、キーストアで証明書と秘密鍵に myKeyAlias のエイリアス名が確実に使用されるようにします。
3. 証明書と鍵をキーストアにアップロードします。証明書で指定されているドメイン名が仮想ホストに使用するホストのエイリアスと一致していることを確認します。

4. Edge UI または API を使用して、キーストアへの参照を作成します。この参照では、キーストアの名前と参照タイプ（KeyStore）を指定します。参照の作成と変更について詳しくは、参照の使用をご覧ください。

5. Create a Virtual Host API を使用して仮想ホストを作成します。必ず、正しいキーストアへの参照とキーエイリアスを指定してください。API を使用するには、次の POST API 呼び出しを使用して myTLSVHost という名前のキーストアを作成します。

   curl -X POST -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u orgAdminEmail:password

   クライアントで双方向 TLS を実行する場合は、<ClientAuthEnabled> を true に設定し、<TrustStore> 要素を使用してトラストストアを指定します。クライアントで双方向 TLS が正しく構成されている必要があります。つまり、Edge にはクライアントの証明書と証明書チェーンが格納されたトラストストアが必要です。Edge UI を使用したキーストアとトラストストアの作成の手順に沿ってトラストストアを作成します。

6. 既存の API プロキシがある場合は、この仮想ホストを ProxyEndpoint の <HTTPConnection> 要素に追加します。仮想ホストがすべての新しい API プロキシに自動的に追加されます。詳しくは、仮想ホストを使用する API プロキシの構成をご覧ください。

仮想ホストを使用するように API プロキシを更新し、ホスト エイリアスの DNS エントリと CNAME レコードを作成すると、以下のようにして API プロキシにアクセスできます。

https://api.myCompany.com/v1/{project-base-path}/{resource-path}

例:

https://api.myCompany.com/v1/weather/forecastrss?w=12797282

仮想ホストの変更

Cloud の有料アカウントのお客様が既存の仮想ホストを変更する際に実施する主なタスクは次の 2 つです。

1. キーストアかトラストストアへの参照の値の変更。
   
   注: 参照を使用するように <KeyStore> または <TrustStore> を設定すると、参照の値をいつでも変更できます。ただし、<KeyStore> または <TrustStore> を別の参照が使用されるように変更する場合や、別のエイリアスが使用されるように <KeyAlias> を変更する場合は、Apigee サポートへのご連絡が必要になります。
2. 仮想ホストの TLS プロパティの変更。

参照の値の変更

参照の値を変更することで、仮想ホストで使用されるキーストアやトラストストアを変更できます。

参照の値を変更する前に、次の処理を行います。

1. Edge UI を使用したキーストアとトラストストアの作成の説明に従って新しいキーストアを作成し、証明書と鍵をアップロードします。新しいキーストアでは、既存のキーストアで使用していたキーエイリアスと同じものを使用してください。
2. 必要であれば、Edge UI を使用したキーストアとトラストストアの作成の説明に従って新しいトラストストアを作成し、証明書をアップロードします。
3. 参照の使用の説明に従って参照を変更します。

仮想ホストの TLS プロパティの変更

有料アカウントのお客様は Update a Virtual Host API を使用して仮想ホストを更新できます。この API を使用すると、仮想ホストのプロパティ リファレンスに記載されている仮想ホストのすべてのプロパティを設定できます。

仮想ホストを変更する際は、仮想ホストの作成時と同様の検証が Edge によって実行されます。変更時に Edge で実行される検証は次のとおりです。

• ホストのエイリアスによって指定されるドメインが別の組織や環境で使用されていないこと。
• お客様がドメイン名を所有していること。具体的には、証明書内の以下の情報がホストのエイリアスと一致していることを確認します。
  • CN - 共通名
  • SAN - サブジェクトの代替名
  • 証明書が期限切れでないことが Edge によって検証されます

Edge API を使用して仮想ホストを変更するには、次の手順を実行します。

1. Update a Virtual Host API を使用して仮想ホストを更新します。この API を使用する際は、リクエストの本文で変更対象の要素だけではなく、仮想ホストの定義全体を指定する必要があります。次の例では、proxy_read_timeout プロパティの値を設定しています。

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost name="myTLSVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Port>443</Port>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://myTestKeystoreRef</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
       <Properties>
          <Property name="proxy_read_timeout">50</Property>
            </Properties>
     </VirtualHost>' \
     -u orgAdminEmail:password

キーストアとトラストストアへの参照を使用するための仮想ホストの変更

Cloud 内の Edge の新しい仮想ホストはすべて、キーストアとトラストストアへの参照を使用します。参照を使用することで、キーストアとトラストストアの変更時に Apigee サポートへのご連絡が不要になります。

Apigee Edge の以前の仮想ホストでは、キーストアとトラストストアに対する参照を使用するよう構成されていない場合があります。これに該当する場合は、参照を使用するように仮想ホストを更新できます。

参照を使用するよう仮想ホストを更新する

仮想ホストを更新する手順は次のとおりです。

1. 必要であれば、Edge UI を使用したキーストアとトラストストアの作成の説明に従って新しいキーストアを作成し、証明書をアップロードします。キーストアがすでにある場合は、それを指定するように参照を構成できます。
2. キーストアへの新しい参照を作成します。
3. 必要に応じて新しいトラストストアを作成し、証明書をアップロードします。トラストストアがすでにある場合は、それを指定するように参照を構成できます。
4. トラストストアへの新しい参照を作成します。
5. キーストア、エイリアス、トラストストア、およびその他の TLS プロパティを設定して仮想ホストを更新します。呼び出しのペイロードは次のとおりです。

   curl -X PUT -H "Content-Type:application/xml" \
     https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/virtualhosts/{vhost_name} \
     -d '<VirtualHost  name="myTLSVHost">
           <HostAliases>
             <HostAlias>api.myCompany.com</HostAlias>
           </HostAliases>
           <Port>443</Port>
           <OCSPStapling>off</OCSPStapling>
           <SSLInfo>
             <Enabled>true</Enabled>
             <ClientAuthEnabled>true</ClientAuthEnabled>
             <KeyStore>ref://myKeyStore2Way</KeyStore>
             <KeyAlias>keyAlias</KeyAlias>
             <TrustStore>ref://myTrustStore2Way</TrustStore>
             <IgnoreValidationErrors>false</IgnoreValidationErrors>
           </SSLInfo>
         </VirtualHost>' \
       -u orgAdminEmail:pWord

6. Apigee サポートに連絡して Edge Router を再起動し、処理を完了します。