TLS 構成のオプション

このドキュメントでは、次の 2 つの機能領域について Edge で TLS を構成する方法の概要を示します。

1. API クライアントによる API プロキシへのアクセス。Edge Router 上の仮想ホストを使用して TLS を構成します。
2. Edge によるバックエンド サービスへのアクセス。Edge Message Processor 上のターゲット エンドポイントとターゲット サーバーを使用して TLS を構成します。

これらのアクセスタイプを図示すると、次のようになります。

仮想ホストまたはターゲット エンドポイント / ターゲット サーバーでの TLS オプションの設定について

仮想ホストは、XML オブジェクトによって次の形式で表すことができます。

<VirtualHost name="secure">
    ...
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

TLS を構成する際に変更する仮想ホストの領域は、<SSLInfo> タグによって定義されます。ターゲット エンドポイントまたはターゲット サーバーの構成にも、同じ <SSLInfo> タグを使用します。

次の表に、<SSLInfo> タグ内の TLS 構成の要素を示します。

要素	説明
<Enabled>	Edge と API クライアント間または Edge とターゲット バックエンド間の一方向 TLS を有効にします。 仮想ホストの場合、証明書と秘密鍵を含むキーストアを定義する必要があります。
<ClientAuthEnabled>	Edge と API クライアント間または Edge とターゲット バックエンド間の双方向 TLS を有効にします。 双方向 TLS を有効にするには、通常、Edge 上のトラストストアとトラストストアを設定する必要があります。
<KeyStore>	キーストア。
<KeyAlias>	証明書と秘密鍵をキーストアにアップロードしたときに指定されたエイリアス。
<TrustStore>	トラストストア。
<IgnoreValidationErrors>	true の場合、TLS 証明書のエラーは無視されます。これは、ターゲット サーバーとターゲット エンドポイントに対して TLS を構成する場合、および双方向 TLS を使用する仮想ホストを構成する場合に有効です。デフォルト値は false です。 ターゲット エンドポイント / ターゲット サーバーでこの設定を使用した場合に、SNI が有効なバックエンド システムからサブジェクトの識別名（DN）がホスト名と一致しない証明書が返されたとき、このエラーは無視できず、接続は失敗します。

<KeyStore> 要素と <TrustStore> 要素の設定について

上記の仮想ホストの例では、キーストアとトラストストアは次の形式の参照を使用して指定されています。

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

キーストアとトラストストアには常に参照を使用することを強くおすすめします。参照とは、キーストアの名前を格納する変数です。これを使用すれば、キーストアの名前を直接指定しなくて済みます。この例は、次のことを示しています。

• myKeystoreRef は、キーストアの名前を含む参照です。この例では、キーストアの名前は myKeystore です。
• myTruststoreRef は、トラストストアの名前を含む参照です。この例では、トラストストアの名前は myTruststore です。

証明書が期限切れになると、仮想ホストまたはターゲット エンドポイント / ターゲット サーバーを更新して、新しい証明書を含むキーストアまたはトラストストアを指定する必要があります。参照の利点は、仮想ホストまたはターゲット エンドポイント / ターゲット サーバー自体を変更せずに、参照の値を変更することでキーストアまたはトラストストアを変更できることです。

• Cloud のお客様の場合: 参照の値を変更する際に、Apigee サポートに連絡する必要はありません。
• Private Cloud のお客様の場合: 参照の値を変更する際に、Router や Message Processor などの Edge コンポーネントを再起動する必要はありません。

別の方法として、キーストア名とトラストストア名を直接指定することもできます。

<KeyStore>myKeystore</KeyStore>
<TrustStore>myTruststore</TrustStore>

キーストアまたはトラストストアの名前を直接指定する場合、Cloud のお客様は Apigee サポートに連絡する必要があります。Private Cloud のお客様は、証明書を更新するために特定の Edge コンポーネントを再起動する必要があります。

ターゲット エンドポイント / ターゲット サーバーの場合にのみ、3 つ目のオプションとして、フロー変数を使用する方法があります。

<KeyStore>{ssl.keystore}</KeyStore>
<TrustStore>{ssl.truststore}</TrustStore>

フロー変数は、ターゲット エンドポイント / ターゲット サーバーに対して機能し、参照と同様にキーストアまたはトラストストアを更新できます。ただし、仮想ホストでは機能しません。また、リクエストごとにキーストア、エイリアス、トラストストアに関する情報を渡す必要があります。

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

有料プランにご加入の Cloud のお客様、および Private Cloud のすべてのお客様は、TLS の構成でキーストアとトラストストアへの参照を使用する際に、以下の制限事項を考慮する必要があります。

• 仮想ホストでキーストアとトラストストアへの参照を使用できるのは、TLS を Apigee Router で終端する場合だけです。

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

既存の仮想ホストでリテラルのキーストア名またはトラストストア名が使用されている場合

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

1. Edge for Cloud

   キーストアの参照を使用するように仮想ホストを変更するには、Apigee サポートとの協力が必要になります。

2. Edge for Private Cloud

   参照を使用するように仮想ホストを変換するには:

   1. 参照を使用するように仮想ホストを更新します。
   2. Router を再起動します。
   詳細については、Private Cloud 用 API への TLS アクセスの構成の「キーストアとトラストストアへの参照を使用するために仮想ホストを変更する」をご覧ください。

Apigee 無料トライアル証明書と鍵の使用について

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

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>

双方向 TLS を行う場合は、通常どおり <ClientAuthEnabled> 要素を true に設定し、<TrustStore> 要素で参照を使用してトラストストアを指定する必要があります。

詳細については、Cloud 用仮想ホストの構成をご覧ください。

TLS の構成について

TLS を構成する方法は、次の 2 つの主な要因によって決まります。

• Edge Cloud のお客様か Private Cloud のお客様か。
• 期限切れの証明書または期限切れが近い証明書をどのように更新するか。

Cloud と Private Cloud の構成オプション

次の表に、Cloud のお客様と Private Cloud のお客様向けの構成オプションを示します。

	Private Cloud	Cloud
仮想ホスト	完全な制御	有料アカウントのみ完全な制御
ターゲット エンドポイント / ターゲット サーバー	完全な制御	完全な制御

Private Cloud のお客様は、仮想ホストとターゲット エンドポイント / ターゲット サーバーの両方の構成を完全に制御できます。これには、仮想ホストを作成および削除する機能や、仮想ホストのすべてのプロパティを設定する機能が含まれます。

Cloud のすべてのお客様（有料プランにご加入のお客様と評価版をご利用のお客様の両方）は、ターゲット エンドポイント / ターゲット サーバーの構成を完全に制御できます。また、有料プランにご加入の Cloud のお客様は、TLS のプロパティを含め、仮想ホストを完全に制御できます。

期限切れの証明書の処理

TLS 証明書が期限切れになった場合、またはシステム構成が変更されて証明書が無効になった場合は、証明書の更新が必要です。仮想ホストまたはターゲット エンドポイント / ターゲット サーバー用に TLS を構成する場合は、その更新をどのように行うかを事前に決定する必要があります。

証明書が期限切れになったとき

Edge では、次の 2 つの場所のどちらかに証明書を格納します。

• キーストア - TLS handshake 中にエンティティの識別に使用される TLS 証明書と秘密鍵が格納されます。
• トラストストア - クライアントに提示された TLS サーバーの証明書の検証に使用される、TLS クライアント上の信頼済み証明書が格納されます。これらの証明書は通常、自己署名証明書、信頼できる CA によって署名されている証明書、または双方向 TLS の一環として使用される証明書です。

キーストアへの参照を使用している場合に、キーストア内の証明書が期限切れになったとき、新しい証明書を同じキーストアにアップロードすることはできません。その代わりに、次の手順に従います。

1. 新しいキーストアを作成します。
2. 古いキーストアと同じエイリアス名を使用して、新しい証明書を新しいキーストアにアップロードします。
3. 仮想ホストまたはターゲット サーバー / ターゲット エンドポイント内の参照を更新し、新しいキーストアが使用されるようにします。

トラストストアへの参照を使用している場合に、トラストストア内の証明書が期限切れになったときは、次の手順に従います。

1. 新しいトラストストアを作成します。
2. 新しい証明書を新しいトラストストアにアップロードします。トラストストアのエイリアス名は重要ではありません。注: 証明書がチェーンの一部である場合は、すべての証明書を含む 1 つのファイルを作成してそのファイルを 1 つのエイリアスにアップロードするか、チェーン内のすべての証明書をトラストストアに個別にアップロードして証明書ごとに異なるエイリアスを使用する必要があります。
3. 仮想ホストまたはターゲット サーバー / ターゲット エンドポイント内の参照を更新し、新しいトラストストアが使用されるようにします。

期限切れの証明書を更新する方法の概要

証明書を更新する方法は、仮想ホストまたはターゲット エンドポイント / ターゲット サーバーでキーストアとトラストストアの名前がどのように指定されているかによって異なります。次の方法を使用できます。

• 参照
• 直接名
• フロー変数

どの方法が使用されているかによって、更新プロセスは次の表のように変わります。これを見るとわかるように、Cloud と Private Cloud のどちらのお客様にとっても、最も柔軟性の高い方法は参照です。

構成タイプ	証明書の更新 / 置換方法	Private Cloud	Cloud
参照（推奨）	キーストアについては、新しいキーストアを新しい名前で作成し、エイリアスを古いエイリアスと同じ名前にします。 トラストストアについては、トラストストアを新しい名前で作成します。	キーストアまたはトラストストアの参照を更新します。 Router または Message Processor の再起動は必要ありません。	キーストアまたはトラストストアの参照を更新します。 Apigee サポートに連絡する必要はありません。
フロー変数（ターゲット エンドポイントのみ）	キーストアについては、新しいキーストアを新しい名前で作成し、エイリアスを同じ名前または新しい名前にします。 トラストストアについては、トラストストアを新しい名前で作成します。	リクエストごとに新しいキーストア、エイリアス、またはトラストストアの名前を指定して、更新されたフロー変数を渡します。 Router または Message Processor の再起動は必要ありません。	リクエストごとに新しいキーストア、エイリアス、またはトラストストアの名前を指定して、更新されたフロー変数を渡します。 Apigee サポートに連絡する必要はありません。
直接	新しいキーストア、エイリアス、トラストストアを作成します。	仮想ホストを更新し、Router を再起動します。 トラストストアがターゲット エンドポイント / ターゲット サーバーによって使用されている場合は、プロキシを再デプロイします。	仮想ホストの場合は、Apigee サポートに連絡して Router を再起動します。 トラストストアがターゲット エンドポイント / ターゲット サーバーによって使用されている場合は、プロキシを再デプロイします。
直接	キーストアまたはトラストストアを削除し、同じ名前で再作成します。	仮想ホストの更新と Router の再起動は必要ありません。ただし、新しいキーストアとエイリアスが設定されるまで、API リクエストは失敗します。 キーストアが Edge とバックエンド サービス間の双方向 TLS に使用されている場合は、Message Processor を再起動します。	仮想ホストを更新する必要はありません。ただし、新しいキーストアとエイリアスが設定されるまで、API リクエストは失敗します。 キーストアが Edge とバックエンド サービス間の双方向 TLS に使用されている場合は、Apigee サポートに連絡して Message Processor を再起動します。
直接	トラストストアについてのみ、新しい証明書をトラストストアにアップロードします。	トラストストアが仮想ホストによって使用されている場合は、Router を再起動します。 トラストストアがターゲット エンドポイント / ターゲット サーバーによって使用されている場合は、Message Processor を再起動します。	仮想ホストの場合は、Apigee サポートに連絡して Edge Router を再起動します。 トラストストアがターゲット エンドポイント / ターゲット サーバーによって使用されている場合は、Apigee サポートに連絡して Message Processor を再起動します。