配置从边缘到后端的 TLS(Cloud 和私有云)

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档

API 代理充当公开端点到后端服务的映射。虚拟主机定义面向公众的 API 代理向应用公开的方式。例如,虚拟主机决定了是否可以使用 TLS 访问 API 代理。配置 API 代理时,请修改其 ProxyEndpoint 定义以配置其使用的虚拟主机。

TargetEndpoint 是 ProxyEndpoint 的出站等效函数。TargetEndpoint 充当从 Edge 到后端服务的 HTTP 客户端。创建 API 代理时,您可以将其配置为使用零个或多个 TargetEndpoint。

了解详情

配置 TargetEndpoint 或 TargetServer

如要配置 TargetEndpoint,请修改用来定义 TargetEndpoint 的 XML 对象。您可以修改 API 代理中定义 TargetEndpoint 的 XML 文件,或者在 Edge 管理界面中修改 TargetEndpoint。

如要使用边缘管理界面修改 TargetEndpoint,请执行以下操作:

  1. 访问 https://enterprise.apigee.com 并登录 Edge 管理界面。
  2. 选择要更新的 API 代理的名称。
  3. 选择开发标签页。
  4. 目标端点下,选择默认
  5. 代码区域会显示 TargetEndpoint 定义,如下所示:
    <TargetEndpoint name="default">
      <Description/>
      <FaultRules/>
      <Flows/>
      <PreFlow name="PreFlow">
        <Request/>
        <Response/>
      </PreFlow>
      <PostFlow name="PostFlow">
        <Request/>
        <Response/>
      </PostFlow>
      <HTTPTargetConnection>
        <Properties/>
        <SSLInfo>
          <Enabled>true</Enabled>
          <TrustStore>ref://myTrustStoreRef</TrustStore>
        </SSLInfo>
        <URL>https://mocktarget.apigee.net</URL>
      </HTTPTargetConnection>
    </TargetEndpoint>
  6. 按照关于后端的 TLS 配置简介中的说明,配置信任库。
  7. 进行所需更改,然后保存代理。如果已部署 API 代理,则保存此代理以使用新设置重新部署。

请注意,TargetEndpoint 定义包含一个 name 属性。您可以使用 name 属性的值将 API 代理的 ProxyEndpoint 定义配置为使用 TargetEndpoint。 如需了解详情,请参阅 API 代理配置参考文档

可以将 TargetEndpoint 配置为引用 TargetServer,而不是显式目标网址。TargetServer 配置用于将具体端点网址与 TargetEndpoint 配置分离开来。TargetServers 用于在多个后端服务器实例上支持负载均衡和故障切换。

下面显示的是一个示例 TargetServer 定义:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>80</Port>
  <IsEnabled>true</IsEnabled>
</TargetServer> 

TargetServer 定义中的 <HTTPTargetConnection> 元素中按名称引用。您可以配置一个或多个命名的 ServerServer,如下所示。

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <LoadBalancer>
      <Server name="target1" />
      <Server name="target2" />
    </LoadBalancer>
    <Path>/test</Path>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

如需了解详情,请参阅跨后端服务器进行负载均衡

关于使用后端进行 TLS 配置

在配置对后端的 TLS 访问之前,您应该了解两个要点:

  1. 默认情况下,Edge 不会验证后端证书。您必须创建 Truststore 才能配置 Edge,以验证证书。
  2. 使用引用来指定 Edge 使用的密钥库或信任库。

下文介绍了这两种注意事项。

定义可信存储区以启用证书验证

通过 TargetEndpoint 或 TargetServer 发出 TLS 请求时,Edge 默认不会验证从后端服务器收到的 TLS 证书。 这意味着 Edge 不会验证:

  • 该证书已由受信任的 CA 签名。
  • 证书未过期。
  • 该证书会显示通用名称。如果存在通用名称,Edge 不会验证该通用名称是否与网址中指定的主机名匹配。

如需配置 Edge 以验证后端证书,您必须:

  1. 在 Edge 上创建信任存储区。
  2. 将服务器的证书或证书链上传到信任库。如果服务器证书由第三方签名,则您需要将完整的证书链(包括根 CA 证书)上传到信任库。没有隐式信任的 CA。
  3. 将 Truststore 添加到 TargetEndpoint 或 TargetServer 定义。

如需了解详情,请参阅密钥库和信任存储区

例如:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

使用对密钥库或信任库的引用

以下示例展示了如何配置 TargetEndpoint 或 TargetServer 以支持 TLS。在配置 TLS 时,您可以在 TargetEndpoint 或 TargetServer 定义中指定 Truststore 和密钥库。

Apigee 强烈建议您在 Target Endpoints 或 TargetServer 定义中使用对密钥库和信任库的引用。使用引用的好处是,您只需将引用更新为指向其他密钥库或信任库即可更新 TLS 证书。

在 TargetEndpoint 或 TargetServer 定义中引用密钥库和信任库的方式与在虚拟主机中引用的方式相同。

将 TargetEndpoint 或 TargetServer 转换为使用引用

您可能拥有使用密钥库和信任库的字面量名称的现有 TargetEndpoint 或 TargetServer 定义。如需将 TargetEndpoint 或 TargetServer 定义转换为使用引用,请执行以下操作:

  1. 更新 TargetEndpoint 或 TargetServer 定义,以使用引用。
  2. 重启边缘消息处理器:
    • 对于公有云客户,请与 Apigee Edge 支持团队联系以重启消息处理器。
    • 对于私有云客户,请重新启动边缘消息处理器。
  3. 确认您的 TargetEndpoint 或 TargetServer 正常工作。

配置到后端服务器的单向 TLS

使用 TargetEndpoint 定义时,无需在 Edge 上进行任何额外配置,即可配置从 Edge(TLS 客户端)到后端服务器(TLS 服务器)的单向 TLS 访问。正确配置 TLS 由后端服务器决定。

您只需确保 TargetEndpoint 定义中的 <URL> 元素通过 HTTPS 协议引用后端服务,并确保启用 TLS:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

如果您使用 TargetServer 定义后端服务,请在 TargetServer 定义中启用 TLS:

<TargetServer name="target1">
  <Host>mocktarget.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
  </SSLInfo> 
</TargetServer> 

但是,如果您希望 Edge 验证后端证书,则必须创建包含后端证书或证书链的信任库。然后,您可以在 TargetEndpoint 定义中指定 Truststore:

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <TrustStore>ref://myTrustStoreRef</TrustStore>
    </SSLInfo>
    <URL>https://myservice.com</URL>
  </HTTPTargetConnection>
  …
</TargetEndpoint>

或者,在 TargetServer 定义中:

<TargetServer name="target1">
  <Host>mockserver.apigee.net</Host>
  <Port>443</Port>
  <IsEnabled>true</IsEnabled>
  <SSLInfo>
    <Enabled>true</Enabled>
    <TrustStore>ref://myTrustStoreRef</TrustStore>
  </SSLInfo> 
</TargetServer>

如需配置单向 TLS,请执行以下操作:

  1. 如果您想验证后端证书,请在 Edge 上创建信任存储区,然后上传后端证书或 CA 链,如密钥库和 Truststores 中所述。在本例中,如果您必须创建信任库,请将其命名为 myTrustStore
  2. 如果您已创建 Truststore,请使用以下 POST API 调用创建名为 myTrustStoreRef 的引用(指向您在上面创建的信任库):

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
      -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
      </ResourceReference>' -u email:password
    
  3. 使用边缘管理界面更新 API 代理的 TargetEndpoint 定义(或者,如果您在 XML 中定义 API 代理,请修改代理的 XML 文件):
    1. 访问 https://enterprise.apigee.com 登录 Edge 管理界面。
    2. 在边缘管理界面菜单中,选择 API
    3. 选择要更新的 API 代理的名称。
    4. 选择开发标签页。
    5. 目标端点下,选择默认
    6. 在代码区域中,修改 <HTTPTargetConnection> 元素以添加 <SSLInfo> 元素。 请务必指定正确的信任库引用,并将 <Enabled> 设置为 true:
      <TargetEndpoint name="default">
        …
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        …
      </TargetEndpoint>
    7. 保存 API 代理。如果已部署 API 代理,则保存此代理以使用新设置重新部署。

配置到后端服务器的双向 TLS

如果您希望支持 Edge(TLS 客户端)与后端服务器(TLS 服务器)之间的双向 TLS,请执行以下操作:

  • 在 Edge 中创建一个密钥库,然后上传 Edge 证书和私钥。
  • 如果您要验证后端证书,请在 Edge 上创建一个信任库,其中包含您从后端服务器收到的证书和 CA 链。
  • 更新引用后端服务器的 API 代理的 TargetEndpoint,以便配置 TLS 访问权限。

使用密钥别名指定密钥库证书

您可以在同一个密钥库中定义多个证书,每个证书都有自己的别名。默认情况下,Edge 会使用密钥库中定义的第一个证书。

(可选)您可以将 Edge 配置为使用 <KeyAlias> 属性指定的证书。这样,您就可以为多个证书定义单个密钥库,然后选择要在 TargetServer 定义中使用的密钥库。如果 Edge 找不到别名与 <KeyAlias> 匹配的证书,则会使用默认操作,即选择密钥库中的第一个证书。

面向公有云的 Edge 用户必须与 Apigee Edge 支持团队联系,才能启用此功能。

配置双向 TLS

如需配置双向 TLS,请执行以下操作:

  1. 在 Edge 中创建密钥库,并按照下述过程(密钥库和 Truststore)上传证书和私钥。 在此示例中,创建一个名为 myTestKeystore 的密钥库,它使用 myKey 的别名作为证书和私钥。
  2. 使用以下 POST API 调用创建名为 myKeyStoreRef 的引用(指向您在上面创建的密钥库):

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myKeyStoreRef">
        <Refers>myTestKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    

    该引用将密钥库的名称和引用类型指定为 KeyStore

    使用以下 GET API 调用来查看引用:

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/myKeyStoreRef /
    -u email:password
    
  3. 如果您想验证后端证书,请在 Edge 上创建信任存储区,然后上传证书和 CA 链,如下所述:密钥库和 Truststores。在此示例中,您必须创建一个可信商店名称 myTrustStore
  4. 如果您已创建 Truststore,请使用以下 POST API 调用创建名为 myTrustStoreRef 的引用(指向您在上面创建的信任库):

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
    -d '<ResourceReference name="myTrustStoreRef">
        <Refers>myTrustKeystore</Refers>
        <ResourceType>KeyStore</ResourceType>
    </ResourceReference>' -u email:password
    
  5. 使用边缘管理界面更新 API 代理的 TargetEndpoint 定义(或者,如果您在 XML 中定义 API 代理,请修改代理的 XML 文件):
    1. 访问 https://enterprise.apigee.com 并登录 Edge 管理界面。
    2. 在边缘管理界面菜单中,选择 API
    3. 选择要更新的 API 代理的名称。
    4. 选择开发标签页。
    5. 目标端点下,选择默认
    6. 在代码区域中,修改 <HTTPTargetConnection> 元素以添加 <SSLInfo> 元素。请务必指定正确的密钥库和密钥别名,并将 <Enabled><ClientAuthEnabled> 元素均设置为 true:
      <TargetEndpoint name="default">
        ...
        <HTTPTargetConnection>
          <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>true</ClientAuthEnabled>
            <KeyStore>ref://myKeyStoreRef</KeyStore>
            <KeyAlias>myKey</KeyAlias>
          </SSLInfo>
          <URL>https://myservice.com</URL>
        </HTTPTargetConnection>
        ...
      </TargetEndpoint>
    7. 保存 API 代理。如果已部署 API 代理,则保存此代理以使用新设置重新部署。

如需详细了解 <TargetEndpoint> 中提供的选项(包括使用变量提供 TargetEndpoint <SSLInfo> 值),请参阅 API 代理配置参考文档

启用 SNI

Edge 支持使用来自消息处理器的服务器名称指示 (SNI),以定位 Apigee Edge 中适用于 Cloud 和私有云的端点。

对于私有云的 Edge,为了向后兼容您现有的目标后端,Apigee 默认停用 SNI。如果您的目标后端配置为支持 SNI,您可以启用此功能。如需了解详情,请参阅将 SNI 与 Edge 搭配使用