Private Cloud 用 API への TLS アクセスの構成

Edge 上の仮想ホストは、API プロキシが公開されるドメインとポートを定義します。また、拡張により、アプリから API プロキシへのアクセスに使用される URL も定義します。

さらに、API プロキシへのアクセスに HTTP プロトコルと TLS を使用した暗号化 HTTPS プロトコルのどちらを使用するかも定義します。仮想ホストで HTTPS と TLS を使用する場合は、Edge に仮想ホストを作成し、その仮想ホストでキーストアとトラストストアが使用されるように構成します。

詳細:

• TLS / SSL について
• Edge での TLS の使用
• 仮想ホストについて
• Private Cloud 用仮想ホストの構成
• 仮想ホスト プロパティのリファレンス
• キーストアとトラストストア

仮想ホストを作成するために必要なもの

仮想ホストを作成する前に、以下の情報が必要になります。

• 仮想ホストの公開ドメイン名。たとえば、api.myCompany.com や myapi.myCompany.com などの公開ドメイン名があるかどうかを確認します。この情報は、仮想ホストを作成するときと、仮想ホスト用の DNS レコードを作成するときに使用します。
• 一方向 TLS の場合、次の内容を含むキーストアを作成する必要があります。
  • TLS 証明書 - 認証局（CA）によって署名された証明書、または最後の証明書が CA によって署名されている証明書のチェーン。
  • 秘密鍵 - Edge は最大で 2,048 ビットのキーサイズをサポートします。パスフレーズは任意です。
• 双方向 TLS の場合は、キーストアに加えて、クライアントの証明書を保持するトラストストアも必要です。トラストストアには、必要に応じて証明書の CA チェーンも格納します。トラストストアは、証明書が CA によって署名されている場合でも必要です。

キーストアとトラストストアの作成の詳細については、キーストアとトラストストアをご覧ください。

仮想ホストでの TLS の構成

仮想ホストを作成するには、仮想ホストを定義する XML オブジェクトを作成します。次の XML オブジェクトでは、<SSLInfo> 要素を使用して、HTTPS を介した一方向 TLS 構成を含む仮想ホストを定義しています。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

この例では、<Enabled> 要素を true に設定して一方向 TLS を有効にし、TLS 接続で使用するキーストアと鍵を <KeyStore> 要素と <KeyAlias> 要素で指定しています。

双方向 TLS を有効にするには、<ClientAuthEnabled> 要素を true に設定し、<TrustStore> 要素を使用してトラストストアを指定します。トラストストアにはクライアントの証明書を格納し、必要に応じて証明書の CA チェーンも格納します。

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

上記の仮想ホストの例では、「参照」を使用してキーストアを指定しました。参照とは、キーストアの名前を格納する変数です。これを使用すれば、キーストアの名前を直接指定しなくて済みます。

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

仮想ホストでリテラルのキーストア名を使用することもできます。ただし、仮想ホストで使用するキーストア名を変更する場合は、Edge Router を再起動する必要があります。

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

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

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

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

仮想ホストではキーストアとトラストストアへの参照を使用することを強くおすすめします。参照を使用すれば、仮想ホストで使用するキーストアとトラストストアを変更する際に Edge Router を再起動する必要がなくなります。

現在仮想ホストの構成でキーストアまたはトラストストアのリテラル名を使用している場合は、参照を使用するように変換できます。そのためには、仮想ホストで参照を使用するように構成を変更し、Edge Router を再起動します。

Edge 4.15.07 以前で TLS 暗号とプロトコルを設定する

Edge バージョン 4.15.07 以前を使用している場合は、<SSLInfo> タグの子タグの <Ciphers> と <Protocols> を使用して、仮想ホストで使用する TLS プロトコルと暗号を設定します。これらのタグの説明については、下記の表をご覧ください。

例:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

<Cipher> タグでは、Java の JSSE 暗号名を使用します。たとえば、Java 8 の場合は http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites をご覧ください。

Edge 4.16.01 から 4.16.09 で TLS 暗号とプロトコルを指定する

Edge 4.16.01 から 4.16.09 では、Router 上で仮想ホストのデフォルトの暗号とプロトコルをグローバルに設定します。このデフォルト設定は、すべての仮想ホストに適用されます。

トークンを使用してデフォルトのプロトコルと暗号を指定します。

• デフォルトのプロトコルを指定するには、トークン conf_load_balancing_load.balancing.driver.server.ssl.protocols を使用します。
• Router のデフォルトの暗号を指定するには、トークン conf_load_balancing_load.balancing.driver.server.ssl.ciphers を使用します。

conf_load_balancing_load.balancing.driver.server.ssl.protocols トークンのデフォルト値は次のとおりです。

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

この設定は、Router が TLS バージョン 1.0、1.1、1.2 をサポートしていることを示します。スペースで区切った値のリストをトークンに指定します。

conf_load_balancing_load.balancing.driver.server.ssl.ciphers トークンのデフォルト値は次のとおりです。

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

この設定は、次のことを示します。

• 必要な鍵の長さは 128 ビット以上（HIGH）
• 認証のない暗号を除外（!aNULL）
• MD5 を使用した暗号スイートを除外（!MD5）
• DH（匿名 DH、エフェメラル DH、固定 DH を含む）とトリプル DES を使用した暗号スイートを除外（!DH+3DES）
• RSA 鍵交換とトリプル DES を使用した暗号スイートを除外（!RSA+3DES）

このトークンの構文と指定可能な値については、https://www.openssl.org/docs/man1.0.2/apps/ciphers.html をご覧ください。このトークンで使用するのは OpenSSL 暗号名（AES128-SHA256 など）です。Java / JSSE 暗号名（TLS_RSA_WITH_AES_128_CBC_SHA256 など）ではないのでご注意ください。

Router のトークンを設定するには:

1. /opt/apigee/customer/application/router.properties ファイルを編集します。このファイルが存在しない場合は作成します。
2. conf_load_balancing_load.balancing.driver.server.ssl.ciphers トークンを設定します。たとえば、TLSv1.2 のみを指定し、事前共有鍵を使用した暗号スイートを除外するには、次のように !PSK を追加します。

   conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
   conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK

3. router.properties ファイルの所有者を apigee にします。

   chown apigee:apigee /opt/apigee/customer/application/router.properties

4. Edge Router を再起動します。

   /opt/apigee/apigee-service/bin/apigee-service edge-router restart

5. トークンの値を確認します。

   /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Edge バージョン 4.17.01 以降で TLS 仮想ホストのパラメータを設定する

Edge バージョン 4.17.01 以降を使用している場合は、<VirtualHost> タグの子タグの <Properties> を使用して、個々の仮想ホストの TLS プロパティ（TLS プロトコルや暗号など）を設定できます。これらのタグについては、仮想ホスト プロパティのリファレンスをご覧ください。

例:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

ssl_ciphers トークンの構文と指定可能な値については、https://www.openssl.org/docs/man1.0.2/apps/ciphers.html をご覧ください。このトークンで使用するのは OpenSSL 暗号名（AES128-SHA256 など）です。Java / JSSE 暗号名（TLS_RSA_WITH_AES_128_CBC_SHA256 など）ではないのでご注意ください。

HTTPS を使用する仮想ホストを作成する

この例では、参照を使用して仮想ホストにキーストアを指定します。参照を使用することで、Router を再起動せずにキーストアを変更できます。

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

1. myTestKeystore という名前のキーストアを作成して構成します。手順については、キーストアとトラストストアをご覧ください。このキーストアでは、証明書と秘密鍵のエイリアス名として myKeyAlias を使用します。

2. 次の POST API 呼び出しを使用して、上記で作成したキーストアへの参照を keystoreref という名前で作成します。

   curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
     -d '<ResourceReference name="keystoreref">
       <Refers>myTestKeystore</Refers>
       <ResourceType>KeyStore</ResourceType>
     </ResourceReference>'
     -u email:password
   

   この参照では、キーストアの名前と参照タイプ KeyStore を指定しています。

   次の GET API 呼び出しを使用して、参照を表示します。

   curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
   

3. 仮想ホストの作成 API を使用して仮想ホストを作成します。ここで、<ms-IP> は Management Server ノードの IP アドレスまたはドメイン名です。

   必ず、正しいキーストアへの参照とキーエイリアスを指定してください。

   curl -X POST -H "Content-Type:application/xml" \
     http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
     -d '<VirtualHost  name="newTLSTrustStore2">
       <HostAliases>
         <HostAlias>apiTLS.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9005</Port>
       <OCSPStapling>off</OCSPStapling>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://keystoreref</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u email:password

4. ホスト エイリアスに一致する、仮想ホストの DNS レコードを作成します。

5. 既存の API プロキシがある場合は、この仮想ホストを ProxyEndpoint の <HTTPConnection> 要素に追加します。新しい API プロキシには、この仮想ホストは自動的に追加されます。

   仮想ホストについての「仮想ホストの作成後の API プロキシの更新」をご覧ください。

API プロキシを更新して仮想ホストを追加し、ホスト エイリアスの DNS レコードを作成した後、次のようにして API プロキシにアクセスできます。

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

例:

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

キーストアまたはトラストストアへの参照を作成して変更する

必要に応じて、仮想ホストでキーストアまたはトラストストアへの参照を使用するように構成できます。参照を使用する利点は、TLS 証明書を更新する際に参照先を別のキーストアまたはトラストストアに変更するだけでよく、Router の再起動が必要ないということです。

たとえば、次の仮想ホストではキーストアへの参照を使用しています。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

次の POST API 呼び出しを使用して、keystoreref という名前の参照を作成します。

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

この参照では、キーストアの名前とそのタイプを指定しています。

次の GET API 呼び出しを使用して、参照を表示します。

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

後でこの参照の参照先を別のキーストアに変更する際は、エイリアスの名前が同じになるように、次の PUT 呼び出しを使用します。

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password