为私有云配置对 API 的 TLS 访问权限

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

Edge 上的虚拟主机定义公开 API 代理的网域和端口,进而定义应用用于访问 API 代理的网址。

虚拟主机还指定是使用 HTTP 协议还是使用 TLS 的加密 HTTPS 协议访问 API 代理。将虚拟主机配置为使用 HTTPS 和 TLS 时,您需要在 Edge 上创建一个虚拟主机,并将虚拟主机配置为使用密钥库信任库

了解详情

创建虚拟主机所需的条件

在创建虚拟主机之前,您应该掌握以下信息:

  • 虚拟主机的公开域名。例如,您应该知道公开名称是否为 api.myCompany.commyapi.myCompany.com 等。系统会在您创建虚拟主机以及为虚拟主机创建 DNS 记录时使用这些信息。
  • 对于单向 TLS,您需要创建一个密钥库,其中密钥库包含以下内容:
    • TLS 证书 - 由证书授权机构 (CA) 签名的证书,或者由 CA 签署最后一个证书的证书链。
    • 私钥 - Edge 最多支持 2048 位的密钥大小。密码是可选的。
  • 对于双向 TLS,您需要一个密钥库,并且需要一个信任库来保存客户端的证书和(可选)证书的 CA 链。即使证书由 CA 签名,您也需要该信任库。

如需详细了解如何创建密钥库和信任库,请参阅密钥库和信任库

TLS 的虚拟主机配置

如需创建虚拟主机,请创建一个定义该虚拟主机的 XML 对象。 以下 XML 对象使用 <SSLInfo> 元素为通过 HTTPS 的单向 TLS 配置定义虚拟主机:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

在此示例中,<Enabled> 元素设置为 true 以启用单向 TLS,<KeyStore> 和 <KeyAlias> 元素指定 TLS 连接使用的密钥库和密钥。

如需启用双向 TLS,请将 <ClientAuthEnabled> 元素设置为 true,并使用 <TrustStore> 元素指定信任库。信任库包含客户端的证书,还可以选择包含证书的 CA 链。

决定如何在虚拟主机中指定密钥库和信任库的名称

在上面的虚拟主机示例中,您使用引用指定了密钥库。引用是一个包含密钥库名称的变量,而不是直接指定密钥库名称。

使用引用的优势在于,您可以更改引用的值,以更改虚拟主机使用的密钥库,这通常是因为当前密钥库中的证书很快就会过期。更改引用的值不需要重启边缘路由器。

或者,您也可以在虚拟主机中使用字面量密钥库名称。但是,如果您修改虚拟主机以更改密钥库名称,则必须重启边缘路由器。

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

使用对密钥库和信任库的引用时,您必须考虑以下限制:

  • 如果您支持 SNI 并在 Apigee 路由器上终止 SSL,则只能在虚拟主机中使用密钥库和信任库引用。
  • 如果您在 Apigee Router 之前有一个负载平衡器,并在负载平衡器上终止 TLS,则不能在虚拟主机中使用密钥库和信任库引用。

修改现有虚拟主机以使用对密钥库和信任库的引用

Apigee 强烈建议虚拟主机使用对密钥库和信任库的引用。通过引用,您可以更改虚拟主机使用的密钥库和信任库,而无需重启边缘路由器。

如果您的虚拟主机当前配置为使用密钥库或信任库的字面量名称,您可以将其转换为使用引用。为此,请更新虚拟主机以使用引用,然后重启边缘路由器。

为 Edge 4.15.07 及更低版本设置 TLS 加密方式和协议

如果您使用的是 Edge 4.15.07 及更低版本,则可以使用 <SSLInfo> 标记的 <Ciphers><Protocols> 子标记来设置虚拟主机使用的 TLS 协议和加密方式。下表中介绍了这些标记。

例如:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

<Cipher> 标记使用密码的 Java 和 JSSE 名称。例如,对于 Java 8,请参阅 http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#cryptosuites

为 Edge 4.16.01 至 4.16.09 指定 TLS 加密方式和协议

在 Edge 4.16.01 到 4.16.09 中,您在路由器上全局为虚拟主机设置默认加密方式和协议。然后,这些默认值将应用于所有虚拟主机。

使用令牌指定默认协议和加密方式:

  • 如需指定默认协议,请使用令牌 conf_load_balancing_load.balancing.driver.server.ssl.protocols
  • 如需指定路由器的默认加密方式,请使用令牌 conf_load_balancing_load.balancing.driver.server.ssl.ciphers

conf_load_balancing_load.balancing.driver.server.ssl.protocols 令牌的默认值为:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

此设置指定路由器支持 TLS 版本 1.0、1.1 和 1.2。为令牌指定以空格分隔的值列表。

conf_load_balancing_load.balancing.driver.server.ssl.ciphers 令牌的默认值为:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

此设置会指定以下内容:

  • 密钥长度必须至少为 128 位 (HIGH)。
  • 排除未经身份验证的加密算法 (!aNULL)
  • 排除使用 MD5 的加密套件 (!MD5)
  • 排除使用 DH 的加密套件(包括匿名 DH、临时 DH 和固定 DH)和三重 DES (!DH+3DES)
  • 排除使用 RSA 密钥交换和三重 DES (!RSA+3DES) 的加密套件

如需了解此令牌允许的语法和值,请参阅 OpenSSL 加密。 请注意,此令牌使用 OpenSSL 加密名称(例如 AES128-SHA256),而不是 Java/JSSE 加密名称(例如 TLS_RSA_WITH_AES_128_CBC_SHA256)。

要为路由器设置令牌,请执行以下操作:

  1. 修改 /opt/apigee/customer/application/router.properties 文件。如果该文件不存在,请创建一个。
  2. 设置 conf_load_balancing_load.balancing.driver.server.ssl.ciphers 令牌。例如,如需仅指定 TLSv1.2 并排除使用预共享密钥的加密套件,请添加 !PSK
    conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
    conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK
  3. 确保 router.properties 文件归 Apigee 所有:
    chown apigee:apigee /opt/apigee/customer/application/router.properties
  4. 重启边缘路由器:
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  5. 检查该令牌的值:
    /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

为 Edge 4.17.01 及更高版本设置 TLS 虚拟主机参数

如果您使用的是 Edge 4.17.01 及更高版本,则可以使用 <VirtualHost> 标记的 <Properties> 子标记为单个虚拟主机设置一些 TLS 属性,例如 TLS 协议和加密方式。虚拟主机属性参考文档中介绍了这些标记。

例如:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

如需了解 ssl_ciphers 令牌允许的语法和值,请参阅 OpenSSL 加密。 请注意,此令牌使用 OpenSSL 加密名称(例如 AES128-SHA256),而不是 Java/JSSE 加密名称(例如 TLS_RSA_WITH_AES_128_CBC_SHA256)。

创建使用 HTTPS 的虚拟主机

此示例使用引用指定了虚拟主机的密钥库。通过使用引用,您可以更改密钥库,而无需重启路由器。

请按照以下步骤创建虚拟主机:

  1. 按照密钥库和 Truststore 中所述的步骤创建和配置名为 myTestKeystore 的密钥库。确保密钥库使用别名 myKeyAlias 作为证书和私钥。
  2. 使用以下 POST API 调用为之前创建的密钥库创建名为 keystoreref 的引用:

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
      -d '<ResourceReference name="keystoreref">
        <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/keystoreref -u uname:password
    
  3. 使用 Create a Virtual Host API 创建虚拟主机,其中 <ms-IP> 是管理服务器节点的 IP 地址或域名。

    请确保指定正确的密钥库引用和密钥别名:

    curl -X POST -H "Content-Type:application/xml" \
      http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
      -d '<VirtualHost  name="newTLSTrustStore2">
        <HostAliases>
          <HostAlias>apiTLS.myCompany.com</HostAlias>
        </HostAliases>
        <Interfaces/>
        <Port>9005</Port>
        <OCSPStapling>off</OCSPStapling>
        <SSLInfo>
          <Enabled>true</Enabled>
          <ClientAuthEnabled>false</ClientAuthEnabled>
          <KeyStore>ref://keystoreref</KeyStore>
          <KeyAlias>myKeyAlias</KeyAlias>
        </SSLInfo>
      </VirtualHost>' \
      -u email:password
  4. 为虚拟主机创建一条与主机别名匹配的 DNS 记录。
  5. 如果您有任何现有的 API 代理,请将虚拟主机添加到 ProxyEndpoint 的 <HTTPConnection> 元素中。系统会自动将虚拟主机添加到所有新的 API 代理。

    请参阅关于虚拟主机中的在创建虚拟主机后更新 API 代理

将 API 代理更新为使用虚拟主机并为主机别名创建 DNS 记录后,您就可以按如下所示访问 API 代理:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

例如:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

创建和修改对密钥库或信任库的引用

您可以视需要配置虚拟主机,以改用对密钥库或信任库的引用。使用引用的优势在于,您可以更新引用以指向其他密钥库或信任库,从而更新 TLS 证书,而无需重启路由器。

例如,下面显示了一个使用对密钥库的引用的虚拟主机:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

使用以下 POST API 调用创建名为 keystoreref 的引用:

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

此引用指定密钥库的名称及其类型。

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

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

以后如需将引用更改为指向其他密钥库,从而确保别名具有相同的名称,请使用以下 PUT 调用:

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