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

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

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

詳細:

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

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

  • 仮想ホストの公開ドメイン名。たとえば、公開名は api.myCompany.commyapi.myCompany.com、などであることを知っている必要があります。この情報は仮想ホストを作成するときに使用しますが、仮想ホストの DNS レコードを作成するときにも使用します。
  • 一方向 TLS の場合、キーストアを作成する必要がありますが、このキーストアには以下が含まれます。
    • TLS 証明書 - 認証局(CA)によって署名された証明書、または最後の証明書が CA により署名されている証明書のチェーン。
    • 秘密鍵 - Edge は最大で 2048 ビットのキーサイズをサポートします。パスフレーズは任意です。
  • 双方向 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>
    

この例では、一方向 TLS を有効にするために <Enabled> 要素が true に設定されており、<KeyStore> および <KeyAlias> 要素に TLS 接続で使用するキーストアとキーが指定されています。

双方向 TLS を有効にするには、<ClientAuthEnabled> 要素を true に設定し、<TrustStore> 要素を使用してトラストストアを指定します。トラストストアはクライアントの証明書を保持し、さらに任意で証明書の CA チェーンを保持します。

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

上の仮想ホストの例では、参照を使用してキーストアを指定しました。参照とは、キーストア名を直接指定するのではなく、キーストアの名前を含んだ変数です。

参照を使用するメリットは、現行のキーストアの証明書が近い将来に期限切れになるため、仮想ホストが使用するキーストアを変更する際に、参照の値を変更すれば済むことです。参照の値を変更する際、Edge Router を再起動する必要はありません。

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

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

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

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

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

Apigee では、仮想ホストでキーストアとトラストストアへの参照を使用することを強くおすすめします。参照を使用することで、仮想ホストが使用するキーストアとトラストストアを、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. Create a Virtual Host 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

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

任意で、仮想ホストがキーストアまたはトラストストアへの参照を代わりに使用するよう構成できます。参照を使用する利点は、別のキーストアかトラストストアを指すように参照を更新することで、Router を再起動する必要なく TLS 証明書を更新できることです。

たとえば、以下に示すのはキーストアへの参照を使用する仮想ホストです。

    <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