访问 API 代理中的 TLS 连接信息

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

借助 Edge，您可以创建支持单向和双向 TLS 的虚拟主机。使用单向 TLS 时，客户端会向部署在边缘路由器上的虚拟主机发出会话请求，该路由器会使用包含虚拟主机公钥的证书进行响应。对于已签名的证书，客户端随后可以向证书授权机构 (CA) 发出请求以对证书进行身份验证。

在双向 TLS 中，客户端和边缘都会通过作为请求一部分验证的证书：

  • 边缘路由器将其证书提供给 TLS 客户端以对自身进行身份验证。然后，客户端会在将其证书发送到服务器之前验证服务器的身份。
  • TLS 客户端向 Edge 提供其证书以对自身进行身份验证。

如需了解详情，请参阅关于虚拟主机。

捕获 TLS 连接信息

在通过支持 TLS 的虚拟主机向 API 代理发出请求期间，Edge 可以捕获有关 TLS 连接的信息。然后，您的 API 代理可以通过流变量访问该信息，以执行额外的分析和验证。

Edge 捕获的 TLS 信息类型取决于虚拟主机支持单向 TLS 还是双向 TLS。例如，对于单向 TLS，Edge 可以捕获有关 TLS 连接中使用的 TLS 加密或 TLS 协议的信息。

对于双向 TLS，Edge 可以捕获与单向 TLS 相同的所有信息，也可以捕获有关客户端证书的信息。例如，Edge 可以 PEM 格式捕获客户端证书和客户端证书的 SHA1 指纹。

捕获单向 TLS 和双向 TLS 的信息

下表列出了流变量，其中包含由 Edge 捕获并可在 API 代理中访问的 TLS 连接信息。通过在虚拟主机定义中将 <ConnectionProperties> 设置为 true，单向 TLS 和双向 TLS 都会捕获此信息：

流变量 说明
tls.cipher TLS 连接使用的加密。
tls.protocol TLS 连接使用的协议。
tls.server.name 所请求的 SNI 服务器名称。
tls.session.id

会话标识符。

当您设置 <ConnectionProperties>、<ClientProperties> 或 true 时，此数据流变量可用。

在双向 TLS 期间捕获其他 TLS 信息

下表列出了流变量，其中包含 Edge 通过双向 TLS 捕获的客户端证书详情。对于双向 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

会话标识符。

当您将 <ConnectionProperties> 或 <ClientProperties> 设置为 true 时，此数据流变量可用。

配置虚拟主机以捕获 TLS 信息

如需配置虚拟主机以捕获 TLS 信息，请将 <PropagateTLSInformation> 下的以下属性设置为 true。

  • <ConnectionProperties>：启用单向和双向 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 还是适用于私有云的 Edge 来适当设置标头大小限制：

  • Edge for the Cloud：Apigee 会适当设置标头大小。
  • Edge for the Private Cloud：功能不可用。

访问 API 代理中的流变量

在 API 代理中，您可以访问和检查 TLS 流变量。例如，您可以使用 AssignMessage 政策来访问它们，并使用 JavaScript 政策在 JavaScript 中访问它们。

您还可以在代理或目标流的 <Condition> 元素中或者 <Step> 或 <RouteRule> 中引用流变量。例如，您可以根据客户端的 SN 将请求路由到不同的目标。

如需了解详情，请参阅：