Accessing TLS connection information in an API proxy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This topic explains how to access TLS connection information in flow variables for an API proxy running on Apigee or Apigee hybrid.

Capturing TLS connection information

During a request to an API proxy, Apigee 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 Apigee depends on whether the Ingress is configured to support one-way or two-way TLS (only applicable with Apigee hybrid). For example, for one-way TLS, Apigee can capture information about the TLS cipher or TLS protocol used in the TLS connection.

For two-way TLS, Apigee can capture all of the same information as captured for one-way TLS, and also capture information about the client's cert. For example, Apigee 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 Apigee and Apigee hybrid, and available for access in the API proxy.

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.

Capturing additional TLS information during two-way TLS

The following table lists the flow variables that contain client cert details captured by Apigee hybrid in two-way TLS:

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.

Configuring Apigee hybrid to enable two-way TLS

To configure the ingress to request a client certificate, add the following details to the overrides file: 

virtualhosts:
  - name: internal
    minTLSProtocolVersion: "1.2" #optional
    maxTLSProtocolVersion: "1.2" #optional
    tlsMode: MUTUAL
    sslSecret: tls-certificates

See also Configuring TLS and mTLS on the Istio ingress.

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 or JavaScript policy to access them.

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: