Cloud 用仮想ホストの構成

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

詳細:

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

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

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

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

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

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

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

カテゴリ 要件 説明
アカウントの種類 有料 無料アカウントとトライアル アカウントでは、仮想ホストの作成と変更はできません。
ユーザーの役割 組織管理者 仮想ホストを作成できるのは、組織管理者または仮想ホストの変更権限を持つカスタム役割のユーザーのみです。
仮想ホストの数 最大 20

仮想ホストの数は、Cloud 内の組織 / 環境ごとに最大 20 個に制限されます。

: Private Cloud では仮想ホストの数に制限がありません。

ほとんどの組織 / 環境では、HTTP 用に 1 つ、HTTPS アクセス用に 1 つの計 2 つの仮想ホストを使用しています。組織 / 環境で複数のドメイン名を使用するアクセスを許可している場合は、追加の仮想ホストが必要になることがあります。

ベース URL プロトコルを含む UI または API で仮想ホストのベース URL を定義する場合は、URL にプロトコル(http://、https:// など)を指定する必要があります。
ポート 443

仮想ホストは、ポート 443 のみで作成できます。

ポート 443 上に複数の仮想ホストを作成する場合は、それらに一意のホスト エイリアスが設定され、すべて TLS をサポートするようにする必要があります。

TLS 必須

HTTPS を介する TLS をサポートする仮想ホストのみを作成できます。ご使用の TLS 証明書と鍵が格納されたキーストアが事前に作成されている必要があります。また、トラストストアは必要に応じて作成できます。

Symantec、VeriSign などの信頼できる事業体による証明書の署名が必要です。自己署名証明書は使用できません。

HTTP アクセスが必要な場合は、Apigee サポートにお問い合わせください。

TLS プロトコル TLS 1.2

Cloud での Edge は、TLS バージョン 1.2 のみをサポートします。

ホスト エイリアス 組織と環境内で一意 別の組織 / 環境の組み合わせにそのホスト エイリアスが存在しないこと。
ドメイン名 お客様の所有

仮想ホストで指定するドメイン名を所有している必要があります。Edge は、ホスト エイリアスによって定義されたドメイン名が TLS 証明書のメタデータと一致することを確認します。

具体的に言うと、Edge は証明書の以下の情報を確認します。

  • CN - 共通名
  • SAN - サブジェクトの代替名

SAN や CN では、たとえば *.myco.net のように、ワイルドカードを使用できます。

Edge は、証明書が期限切れでないことも検証します。

クライアント アプリの SNI サポート 仮想ホストにアクセスするすべてのクライアント アプリは SNI のサポートが必須

すべてのアプリで SNI のサポートが必須です。

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

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

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

  1. apigee.com/edge にログインします。
  2. [Admin] > [Virtual Hosts] を選択します。
  3. prodtest などの環境を選択します。
  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>
    

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

  • namemyTLSVHost を指定します。この名前を使用して、API プロキシまたは API 呼び出しで仮想ホストを参照します。
  • host aliasapi.myCompany.com として指定します。これは、DNS 定義と CNAME レコードによる定義に従って API にアクセスするために使用される公開ドメインです。
  • port 番号に 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 をサポートし、Apigee Router 上で SSL を終端している場合にのみ、仮想ホストでキーストアとトラストストアへの参照を使用できます。
  • 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 チェーンも格納できます。

仮想ホストの作成

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

  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

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

クラウド内の 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 を再起動し、処理を完了します。