用于配置 TLS 的选项

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

本文档简要介绍如何在 Edge 上为两个功能区域配置 TLS：

1. API 客户端对 API 代理的访问权限。在 Edge Router 路由器上使用虚拟主机配置 TLS。
2. 通过 Edge 访问您的后端服务。在 Edge 消息处理器上使用目标端点和目标服务器配置 TLS。

这两种访问类型如下所示：

关于在虚拟主机或目标端点/目标服务器中设置 TLS 选项

虚拟主机可以由 XML 对象表示，格式如下：

<VirtualHost name="secure">
    ...
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://myKeystoreRef</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://myTruststoreRef</TrustStore> 
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
</VirtualHost>

您修改以配置 TLS 的虚拟主机区域由 <SSLInfo> 标记定义。您可以使用相同的 <SSLInfo> 标记来配置目标端点或目标服务器。

下表介绍了 <SSLInfo> 标记使用的 TLS 配置元素：

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

关于设置 <KeyStore> 和 <TrustStore> 元素

在上面的虚拟主机示例中，密钥库和信任库可使用references来指定，格式如下：

<KeyStore>ref://myKeystoreRef</KeyStore>
<TrustStore>ref://myTruststoreRef</TrustStore>

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

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

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

• 对于 Cloud 客户：更改引用值不需要联系 Apigee Edge 支持团队。
• 对于私有云客户：更改引用的值不需要重启 Edge 组件，例如路由器和消息处理器。

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

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

如果您直接指定密钥库或信任库的名称，则 Cloud 客户必须联系 Apigee Edge 支持团队，而私有云客户必须重启某些 Edge 组件以更新证书。

第三个选项（仅适用于目标端点/目标服务器）是使用流变量：

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

流变量适用于目标端点/目标服务器，允许您更新密钥库或信任库，例如引用。但是，它们不适用于虚拟主机，并且要求您在每个请求中传递有关密钥库、别名和信任库的信息。

使用密钥库和信任库的引用时的限制

付费 Cloud 客户和所有配置 TLS 的 Private Cloud 客户在使用对密钥库和信任库的引用时，必须考虑以下限制：

• 仅当在 Apigee 路由器上终止 TLS 时，才能在虚拟主机中使用密钥库和信任库引用。

• 如果您在 Apigee 路由器前面具有负载平衡器，并且您在负载平衡器上终止 TLS，则无法在虚拟主机中使用密钥库和信任库引用。

如果您的现有虚拟主机使用字面量密钥库或信任库名称

可能未将 Edge 上的现有虚拟主机配置为使用密钥库和信任库的引用。在这种情况下，您可以更新虚拟主机以使用引用。

1. Edge for the Cloud

   如需将虚拟主机更改为使用对密钥库的引用，您必须与 Apigee Edge 支持合作。

2. 私有云的 Edge

   如需将虚拟主机转换为使用引用，请执行以下操作：

   1. 更新虚拟主机以使用引用。
   2. 重启路由器。
   如需了解详情，请参阅为私有云配置对 API 的 TLS 访问权限中的“修改虚拟主机以使用对密钥库和信任存储区的引用”。

关于使用 Apigee 免费试用证书和密钥

如果您有付费的 Edge for Cloud 帐号，还没有 TLS 证书和密钥，可以创建一个使用 Apigee 免费试用证书和密钥的虚拟主机。这意味着您可以创建虚拟主机，而无需先创建密钥库。

使用 Apigee 免费试用证书和密钥定义虚拟主机的 XML 对象省略了 <KeyStore> 和 <KeyAlias> 元素，并将其替换为 <UseBuiltInFreeTrialCert> 元素，如下所示：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>myapi.apigee.net</HostAlias>
    </HostAliases>
    <Port>443</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
    </SSLInfo>
    <UseBuiltInFreeTrialCert>true</UseBuiltInFreeTrialCert>
</VirtualHost>

如果您要执行双向 TLS，则仍必须将 <ClientAuthEnabled> 元素设置为 true，并使用带有 <TrustStore> 元素的引用来指定信任库。

如需了解详情，请参阅为 Cloud 配置虚拟主机。

关于配置 TLS

有两个主要因素决定了您如何执行 TLS 配置：

• 您是 Edge Cloud 或 Private Cloud 客户吗？
• 如何更新已过期或即将过期的证书？

云端和私有云配置选项

下表显示了 Cloud 和 Private Cloud 客户的不同配置选项：

私有云客户可以完全控制虚拟主机和目标端点/目标服务器的配置。该控制机制包括创建和删除虚拟主机，以及在虚拟主机上设置所有属性。

所有 Cloud 客户（包括付费客户和评估客户）都可以完全控制目标端点/目标服务器的配置。此外，付费 Cloud 客户可以完全控制虚拟主机，包括 TLS 属性。

处理过期证书

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

当证书过期时

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

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

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

1. 创建新密钥库。
2. 使用与旧密钥库相同的别名将新证书上传到新的密钥库。
3. 更新虚拟主机或目标服务器/目标端点中的引用以使用新的密钥库。

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

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

更新过期证书的方法摘要

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

• 参考编号
• 直接名称
• 流变量

每种方法对更新过程的影响各不相同，如下表所示。如您所见，参考资料为云和私有云客户提供了最大的灵活性：