用于配置 TLS 的选项

本页面适用于 Apigee 和 Apigee Hybrid。

查看 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 与目标后端之间启用双向 (two-way) TLS（也称为双向 (mutual) 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>

Apigee 强烈建议您始终使用对密钥库和信任库的引用。引用是一个包含密钥库或信任库名称的变量，而不是直接指定密钥库名称。在此示例中：

myKeystoreRef 是包含密钥库名称的引用。在此示例中，密钥库的名称为 myKeystore。
myTruststoreRef 是包含信任库名称的引用。在此示例中，信任库的名称为 myTruststore。

当证书到期时，您必须更新目标端点/目标服务器，以指定包含新证书的密钥库或信任库。引用的优势在于，您可以修改此引用的值来更改密钥库或信任库，而无需修改目标端点/目标服务器本身：

更改引用值不需要联系 Apigee 支持团队。

或者，您也可以直接指定密钥库名称和信任库名称：

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

如果您直接指定密钥库或信任库的名称，则必须与 Apigee 支持团队联系。

第三个选项是使用流变量：

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

通过流变量，您可以更新密钥库或信任库，如引用。如需了解详情，请参阅使用流变量动态设置 TLS/SSL 值。

关于配置 TLS

所有付费和评估的 Apigee 客户都可完全控制目标端点/目标服务器的配置。此外，付费 Apigee 客户还可完全控制 TLS 属性。

处理过期证书

如果 TLS 证书过期，或您的系统配置更改导致该证书不再有效，则您需要更新证书。为目标端点/目标服务器配置 TLS 时，您应先决定如何执行该更新，然后再执行任何配置。

当证书过期时

在 Apigee 上，您将证书存储在以下两个位置之一：

密钥库 - 包含 TLS 证书和私钥，用于在 TLS 握手过程中标识实体。
信任库 - 包含 TLS 客户端上的可信证书，用于验证提供给客户端的 TLS 服务器证书。这些证书通常是自签名证书、由可信 CA 签名的证书或用作双向 (two-way) TLS（也称为双向 (mutual) TLS 或 mTLS）一部分的证书。

当果密钥库中的证书过期，并且您使用的是密钥库的引用时，您将无法向密钥库上传新证书。而是：

创建新密钥库。
使用与旧密钥库相同的别名将新证书上传到新的密钥库。
更新目标服务器/目标端点中的引用以使用新的密钥库。

当信任库中的证书过期，并且您使用的是信任库的引用时，您可以：

新建信任库。
将新证书上传到新信任库。别名不会影响信任库。注意：如果证书是链的一部分，则您必须创建一个包含所有证书的文件，并将该文件上传到单个别名，或者每个证书使用一个不同的别名，将链中的所有证书单独上传到信任库。
更新目标服务器/目标端点中的引用以使用新的信任库。

更新过期证书的方法摘要

用于在目标端点/目标服务器中指定密钥库和信任库的名称的方法决定了证书更新方式。您可以使用：

参考
直接名称
流变量

其中每种方法在更新流程中都有不同的反应，如下表所示：

配置类型	如何更新/替换证书	用量
引用（推荐）	对于密钥库，使用新名称以及与旧别名具有相同名称的别名创建新密钥库。对于信任库，使用新名称创建信任库。	更新密钥库或信任库的引用。不需要联系 Apigee 支持团队。
流变量	对于密钥库，使用新名称以及具有相同名称或新名称的别名创建新密钥库。对于信任库，使用新名称创建信任库。	使用新密钥库、别名或信任库的名称在每个请求中传递更新后的流变量。不需要联系 Apigee 支持团队。
直接	创建新的密钥库、别名和信任库。	重新部署代理。
直接	删除密钥库或信任库，然后使用相同的名称重新创建密钥库或信任库。	在设置新的密钥库和别名之前，API 请求会失败。如果密钥库用于 Apigee 和后端服务之间的双向 (two-way) TLS（也称为双向 (mutual) TLS 或 mTLS），请联系 Apigee 支持团队以重新启动消息处理器。
直接	仅针对信任库，将新证书上传到信任库。	联系 Apigee 支持团队以重启消息处理器。