API プロキシの TLS 接続情報へのアクセス

Edge では、一方向 TLS と双方向 TLS をサポートする仮想ホストを作成できます。一方向 TLS では、クライアントは Edge Router にデプロイされた仮想ホストにセッション リクエストを発行し、Router は仮想ホストの公開鍵を含む証明書をレスポンスとして返します。署名付き証明書の場合、クライアントはその証明書を認証するよう認証局(CA)にリクエストできます。

双方向 TLS では、クライアントと Edge の両方が証明書を提示し、それらの証明書がリクエストの一環として検証されます。

  • Edge Router は、自身を認証するための証明書を TLS クライアントに提示します。クライアントは、受け取った証明書でサーバーの ID を検証してから、自身の証明書をサーバーに送信します。
  • TLS クライアントは、自身を認証するための証明書を Edge に提示します。

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

TLS 接続情報のキャプチャ

Edge には、TLS をサポートする仮想ホストを介して API プロキシへのリクエストを処理する際に TLS 接続に関する情報をキャプチャする機能があります。この情報には API プロキシからフロー変数を通じてアクセスできるので、これを基に追加の分析や検証を行うことができます。

Edge によってキャプチャされる TLS 情報の種類は、仮想ホストでサポートされる TLS が一方向か双方向かによって異なります。たとえば、一方向 TLS の場合は、TLS 接続で使用される TLS 暗号や TLS プロトコルに関する情報がキャプチャされます。

双方向 TLS の場合は、一方向 TLS でキャプチャされるすべての情報に加えて、クライアントの証明書に関する情報もキャプチャされます。たとえば、クライアント証明書の SHA1 フィンガープリントや PEM 形式のクライアント証明書をキャプチャできます。

一方向 TLS と双方向 TLS の両方に関する情報のキャプチャ

次の表に、Edge がキャプチャした TLS 接続情報を含むフロー変数を示します。これらのフロー変数には API プロキシからアクセスできます。この情報は、一方向 TLS と双方向 TLS のどちらにおいても、仮想ホストの定義で <ConnectionProperties> を true に設定することでキャプチャされます。

フロー変数 説明
tls.cipher TLS 接続で使用される暗号。
tls.protocol TLS 接続で使用されるプロトコル。
tls.server.name リクエストされた SNI サーバー名。
tls.session.id

セッション ID。

このフロー変数は、<ConnectionProperties> または <ClientProperties> を true に設定した場合に使用できます。

双方向 TLS での追加の TLS 情報のキャプチャ

次の表に、双方向 TLS で Edge がキャプチャしたクライアント証明書の詳細を含むフロー変数を示します。この情報は、双方向 TLS において、仮想ホストの定義で <ClientProperties> を true に設定することでキャプチャされます。

フロー変数 説明
tls.client.s.dn クライアント証明書のサブジェクトの識別名(DN)。
tls.client.i.dn クライアント証明書の発行元の識別名(DN)。
tls.client.raw.cert PEM 形式のクライアント証明書。
tls.client.cert.serial クライアント証明書のシリアル番号。
tls.client.cert.fingerprint クライアント証明書の SHA1 フィンガープリント。
tls.session.id

セッション ID。

このフロー変数は、<ConnectionProperties> または <ClientProperties> を true に設定した場合に使用できます。

TLS 情報をキャプチャするための仮想ホストの構成

TLS 情報をキャプチャするように仮想ホストを構成するには、<PropagateTLSInformation> 内の次のプロパティを true に設定します。

  • <ConnectionProperties>: 一方向 TLS と双方向 TLS の両方の TLS 接続情報のキャプチャを有効にします。デフォルト値は false です。
  • <ClientProperties>: 双方向 TLS の追加情報のキャプチャを有効にします。デフォルト値は false です。

たとえば、次の仮想ホストの定義では双方向 TLS が使用されていて、両方のタイプの TLS 情報がキャプチャされるようになっています。

<VirtualHost name="secure">
    ....
    <SSLInfo>
        <Enabled>true</Enabled>
        # Enable two-way TLS.
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <KeyAlias>ks-alias</KeyAlias>
        <KeyStore>ref://ks-ref</KeyStore>
        <TrustStore>ref://ts-ref</TrustStore>
    </SSLInfo>
    <PropagateTLSInformation>
        <ConnectionProperties>true</ConnectionProperties>
        <ClientProperties>true</ClientProperties>
    </PropagateTLSInformation>
</VirtualHost>

JSON 本文を渡す場合は、これらのプロパティを次のように設定します。

  "propagateTLSInformation" : {
    "connectionProperties" : true,
    "clientProperties" : true
  }

詳細については、仮想ホスト プロパティのリファレンスをご覧ください。

ヘッダーサイズの上限の設定

仮想ホストで TLS 情報のキャプチャを有効にすると、Edge はこの情報を HTTP ヘッダーで渡します。そのため、Edge for Cloud と Edge for Private Cloud のどちらを使用しているかに応じて、ヘッダーサイズの上限を適切に設定する必要があります。

  • Edge for Cloud: ヘッダーサイズは Apigee によって適切に設定されます。
  • Edge for Private Cloud: この機能は使用できません。

API プロキシでのフロー変数へのアクセス

API プロキシから TLS フロー変数にアクセスし、その値を調べることができます。たとえば、AssignMessage ポリシーを使用してフロー変数にアクセスしたり、JavaScript ポリシーを使用して JavaScript でアクセスしたりできます。

さらに、プロキシまたはターゲット フローの <Condition> 要素、あるいは <Step> または <RouteRule> でフロー変数を参照することもできます。たとえば、クライアントの SN に基づいて異なるターゲットにリクエストをルーティングするといったことが可能です。

詳細については、以下をご覧ください。