您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息
Edge 上的虚拟主机定义公开 API 代理的网域和端口,进而定义应用用于访问 API 代理的网址。
虚拟主机还指定是使用 HTTP 协议还是使用 TLS 的加密 HTTPS 协议访问 API 代理。将虚拟主机配置为使用 HTTPS 和 TLS 时,您需要在 Edge 上创建一个虚拟主机,并将虚拟主机配置为使用密钥库和信任库。
了解详情:
创建虚拟主机所需的条件
在创建虚拟主机之前,您应该掌握以下信息:
- 虚拟主机的公开域名。例如,您应该知道公开名称是否为
api.myCompany.com
、myapi.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)。
要为路由器设置令牌,请执行以下操作:
- 修改
/opt/apigee/customer/application/router.properties
文件。如果该文件不存在,请创建一个。 - 设置
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
- 确保
router.properties
文件归 Apigee 所有:chown apigee:apigee /opt/apigee/customer/application/router.properties
- 重启边缘路由器:
/opt/apigee/apigee-service/bin/apigee-service edge-router restart
- 检查该令牌的值:
/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 的虚拟主机
此示例使用引用指定了虚拟主机的密钥库。通过使用引用,您可以更改密钥库,而无需重启路由器。
请按照以下步骤创建虚拟主机:
- 按照密钥库和 Truststore 中所述的步骤创建和配置名为 myTestKeystore 的密钥库。确保密钥库使用别名 myKeyAlias 作为证书和私钥。
-
使用以下 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
使用 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
- 为虚拟主机创建一条与主机别名匹配的 DNS 记录。
如果您有任何现有的 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