用于配置 TLS 的选项

<ph type="x-smartling-placeholder"></ph> 您正在查看 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 配置元素:

元素 说明
<Enabled>

在 Edge 和 API 客户端之间或者在 Edge 和目标后端之间提供单向 TLS。

对于虚拟主机,您必须定义一个包含证书和私钥的密钥库。

<ClientAuthEnabled>

在 Edge 和 API 客户端之间或者在 Edge 和目标后端之间提供双向 TLS。

启用双向 TLS 通常需要您在 Edge 上设置信任库。

<KeyStore> 密钥库。
<KeyAlias> 将证书和私钥上传到密钥库时指定的别名。
<TrustStore> 信任库。
<IgnoreValidationErrors>

如果为 true,Edge 会忽略 TLS 证书错误。为目标服务器和目标端点配置 TLS 时,以及配置使用双向 TLS 的虚拟主机时有效。默认值为 false。

当与目标端点/目标服务器搭配使用时,如果后端系统使用 SNI,并返回主题标识名 (DN) 与主机名不匹配的证书,则您无法忽略该错误且连接会失败。

&lt;CommonName&gt;

如果指定,则是一个值,用于验证目标证书的常用名称。 此值仅对 TargetEndpoint 和 TargetServer 配置有效。不是 适用于 VirtualHost 配置。

默认情况下,指定的值与目标证书的通用名称完全匹配。 例如,使用 *.myhost.com 作为 <CommonName> 的值只有 如果将确切值 *.myhost.com 指定为 目标证书。

Apigee 可选择性地使用 wildcardMatch 属性执行带有通配符的匹配。

例如,系统将匹配并验证目标证书中指定为 abc.myhost.com 的常用名称 如果<CommonName>元素指定如下:

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

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

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

<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

    要将虚拟主机更改为使用对密钥库的引用,您必须使用 Apigee Edge 支持

  2. 适用于私有云的 Edge

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

    1. 更新虚拟主机以使用引用。
    2. 重启路由器。
    。 请参阅“修改虚拟主机以使用对密钥库和信任库的引用”请参阅配置 TLS 访问 适用于私有云的 API

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

如果您有付费的 Cloud Edge 账号,但尚未拥有 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 配置的方式主要由以下两个因素决定:

  • 您是边缘云客户还是私有云客户?
  • 如何更新已过期或即将过期的证书?

云端和私有云配置选项

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

Private Cloud Cloud
虚拟主机 完全控制 仅完全控制付费账号
目标端点/目标服务器 完全控制 完全控制

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

所有 Cloud 客户(包括付费客户和评估客户)都可以完全控制 目标端点/目标服务器。此外,付费 Cloud 客户可以完全控制 包括 TLS 属性

处理过期证书

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

当证书过期时

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

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

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

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

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

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

更新过期证书的方法摘要

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

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

每种方法对更新过程的影响各不相同,如 表格。如您所见,引用可为 Cloud 和 Private Cloud 客户:

配置类型 如何更新/替换证书 Private Cloud Cloud
引用(推荐) 对于密钥库,使用新名称以及与旧别名具有相同名称的别名创建新密钥库。

对于信任库,使用新名称创建信任库。

更新密钥库或信任库的引用。

无需重启路由器或消息处理器。

更新密钥库或信任库的引用。

不需要联系 Apigee 支持团队。

流变量(仅限目标端点) 对于密钥库,使用新名称以及具有相同名称或新名称的别名创建新密钥库。

对于信任库,使用新名称创建信任库。

使用新密钥库、别名或信任库的名称在每个请求中传递更新的流变量。

无需重启路由器或消息处理器。

使用新密钥库、别名或信任库的名称在每个请求中传递更新的流变量。

不需要联系 Apigee 支持团队。

直接 创建新的密钥库、别名、信任库。 更新虚拟主机并重启路由器。

如果目标端点/目标服务器使用信任库,请重新部署代理。

对于虚拟主机,请联系 Apigee Edge 支持团队以重启路由器。

如果目标端点/目标服务器使用信任库,请重新部署代理。

直接 删除密钥库或信任库,然后使用相同的名称重新创建密钥库或信任库。 无需更新虚拟主机,也无需重启路由器。但是,API 请求会失败 直到设置了新的密钥库和别名为止。

如果密钥库用于 Edge 和后端服务之间的双向 TLS,请重启 消息处理器

不需要更新虚拟主机。但是,在设置新的密钥库和别名之前,API 请求会失败。

如果将密钥库用于 Edge 和后端服务之间的双向 TLS, 联系 Apigee Edge 支持,以重启消息处理器。

直接 仅针对信任库,将新证书上传到信任库。 如果虚拟主机使用了信任库,请重启路由器。

如果目标端点/目标服务器使用信任库,请重启消息 处理器。

对于虚拟主机,请联系 Apigee Edge 支持团队,以重启边缘路由器。

如果目标端点/目标服务器使用信任库,请联系 Apigee Edge 支持团队,以重启消息处理器。