TLS の構成オプション

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

このセクションでは、プロキシからターゲットへのトラフィック用に TLS を構成する方法について説明します。

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

ターゲットは、次のような XML オブジェクトで表すことができます。

<HTTPTargetConnection>
    <Properties/>
    <URL>https:myTargetAddress</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <Enforce>true</Enforce>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://myKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://myTruststoreRef</TrustStore>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</HTTPTargetConnection>

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

<SSLInfo> の子要素の詳細については、TLS/SSL TargetEndpoint 構成をご覧ください。

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

要素 説明
<Enabled>

Apigee と API クライアントとの間、または Apigee とターゲット バックエンドとの間の一方向 TLS を有効にします。
<Enforce>

Apigee とターゲット バックエンドの間に厳格な SSL を適用します。

true に設定すると、無効な証明書、期限切れの証明書、自己署名証明書、ホスト名の一致しない証明書、信頼できないルートの証明書を使用するターゲットが接続に失敗します。4xx または 5xx のエラーコードが返されます。

未設定または false に設定すると、証明書に問題があるターゲット バックエンドへの接続結果は、<IgnoreValidationErrors> の設定によって異なります（以下をご覧ください）。<IgnoreValidationErrors> が true に設定されている場合、特定の条件下で成功レスポンス（2xx）が発生することがあります。
<ClientAuthEnabled>

Apigee と API クライアント間、または Apigee とターゲット バックエンド間の双方向 TLS（相互 TLS または mTLS）を有効にします。

双方向 TLS を有効にするには、通常、Apigee 上にトラストストアを設定する必要があります。
<KeyStore> キーストア。
<KeyAlias> 証明書と秘密鍵をキーストアにアップロードしたときに指定されたエイリアス。
<TrustStore> トラストストア。
<IgnoreValidationErrors>

true の場合、Apigee で TLS 証明書のエラーは無視されます。デフォルト値は false です。

バックエンド システムが SNI を使用し、ホスト名と一致しないサブジェクトの識別名（DN）を持つ証明書を返す場合、エラーを無視する方法がなく、接続が失敗します。

注: <Enforce> が true に設定されている場合、<IgnoreValidationErrors> の値は無視されます。

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

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

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

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

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

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

参照の値を変更する際に、Apigee サポートに連絡する必要はありません。

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

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

キーストアやトラストストアの名前を直接指定する場合は、Apigee サポートに連絡する必要があります。

3 つ目の方法として、フロー変数を使用する方法があります。

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

フロー変数を使用することで、参照と同様にキーストアまたはトラストストアを更新できます。詳細については、フロー変数を使用して TLS / SSL 値を動的に設定するをご覧ください。

TLS の構成について

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

期限切れの証明書の処理

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

証明書が有効期限切れになった場合

Apigee では、次の 2 か所のいずれかに証明書を格納します。

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

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

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

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

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

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

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

  • リファレンス
  • 直接名
  • フロー変数

どの方法が使用されているかによって、更新プロセスは次の表のように変わります。

構成タイプ 証明書の更新 / 置換方法 用途
参照（推奨） キーストアについては、新しいキーストアを新しい名前で作成し、エイリアスを古いエイリアスと同じ名前にします。

トラストストアの場合は、トラストストアを新しい名前で作成します。

 キーストアまたはトラストストアへの参照を更新します。

Apigee サポートに連絡する必要はありません。
フロー変数 キーストアについては、新しいキーストアを新しい名前で作成し、エイリアスを同じ名前または新しい名前にします。

トラストストアの場合は、トラストストアを新しい名前で作成します。

 リクエストごとに新しいキーストア、エイリアス、またはトラストストアの名前を指定して、更新されたフロー変数を渡します。

Apigee サポートに連絡する必要はありません。
直接 新しいキーストア、エイリアス、トラストストアを作成します。 プロキシを再デプロイします。
直接 キーストアまたはトラストストアを削除し、同じ名前で再作成します。 新しいキーストアとエイリアスが設定されるまで、API リクエストは失敗します。

キーストアが Apigee とバックエンド サービス間の双方向 TLS（相互 TLS または mTLS）に使用されている場合は、Apigee サポートに連絡して、Message Processor を再起動します。
直接 トラストストアの場合のみ、新しい証明書をトラストストアにアップロードします。 Message Processor を再起動するために、Apigee サポートに連絡します。