Accessing TLS connection information in an API proxy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Edge lets you create virtual hosts that support one-way and two-way TLS. With one way TLS, the client issues a session request to a virtual host deployed on an Edge Router and the Router responds with a cert which contains the virtual host's public key. For a signed cert, the client can then make a request to the Certificate Authority (CA) to authenticate the certificate.

In two-way TLS, both the client and Edge pass certs that are validated as part of a request:

The Edge Router presents its certificate to the TLS client to authenticate itself. The client then verifies the identity of the server prior to sending its cert to the server.
The TLS client presents its certificate to Edge to authenticate itself.

See About virtual hosts for more information.

Capturing TLS connection information

During a request to an API proxy through a virtual host that supports TLS, Edge can capture information about the TLS connection. Your API proxy can then access that information through flow variables to perform additional analysis and validation.

The type of TLS information captured by Edge depends on whether the virtual host supports one-way or two-way TLS. For example, for one-way TLS, Edge can capture information about the TLS cipher or TLS protocol used in the TLS connection.

For two-way TLS, Edge can capture all of the same information as captured for one-way TLS, and also capture information about the client's cert. For example, Edge can capture the SHA1 fingerprint of the client cert and the client cert in the PEM format.

Capturing information for both one-way and two-way TLS

The following table lists the flow variables that contain TLS connection information captured by Edge and available for access in the API proxy. This information is captured for both one-way and two-way TLS by setting <ConnectionProperties> to true in the virtual host definition:

Flow variable	Description
`tls.cipher`	The cipher used by the TLS connection.
`tls.protocol`	The protocol used by the TLS connection.
`tls.server.name`	The requested SNI server name.
`tls.session.id`	The session identifier. This flow variable is available when you set either `<ConnectionProperties>` or `<ClientProperties>` or to true.

Capturing additional TLS information during two-way TLS

The following table lists the flow variables that contain client cert details captured by Edge in two-way TLS. This information is captured for two-way TLS by setting <ClientProperties> to true in the virtual host definition:

Flow variable	Description
`tls.client.s.dn`	The subject Distinguished Name (DN) of the client cert.
`tls.client.i.dn`	The issuer Distinguished Name (DN) of the client cert.
`tls.client.raw.cert`	The client cert in the PEM format.
`tls.client.cert.serial`	The serial number of the client cert.
`tls.client.cert.fingerprint`	The SHA1 fingerprint of the client cert.
`tls.session.id`	The session identifier. This flow variable is available when you set either `<ConnectionProperties>` or `<ClientProperties>` to true.

Configuring a virtual host to capture TLS information

To configure the virtual host to capture TLS information, set the following properties under <PropagateTLSInformation> to true.

See Virtual host property reference for more information about <PropagateTLSInformation>, including availability information.

<ConnectionProperties>: Enable the capture of TLS connection information for both one-way and two-way TLS. The default value is false.
<ClientProperties>: Enable the capture of additional information for two-way TLS. The default value is false.

For example, the following virtual host definition uses two-way TLS and enables the capturing of both types of TLS information:

<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>

If you are passing a JSON body, set the properties as:

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

Set header size limits

When you enable the capture of TLS information on a virtual host, Edge passes that information using HTTP headers. You must therefore ensure that the header size limits are set appropriately based on whether you are using Edge for the Cloud or Edge for the Private Cloud:

Edge for the Cloud: Apigee sets the header sizes appropriately.
Edge for the Private Cloud: Feature not available.

Accessing the flow variables in an API proxy

From within your API proxy, you can access and inspect the TLS flow variables. For example, you can use the AssignMessage policy to access them, access them in JavaScript with the JavaScript policy.

You can also reference the flow variables in a <Condition> element of a proxy or target flow, or in a <Step> or <RouteRule>. For example, you could route a request to different targets based on the SN of the client.

For more, see: