您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
Edge 上的虛擬主機會定義要公開 API Proxy 的網域和通訊埠,以及應用程式用來存取 API Proxy 的網址。
虛擬主機也會定義要透過 HTTP 通訊協定或採用 TLS 的加密 HTTPS 通訊協定存取 API Proxy。將虛擬主機設為使用 HTTPS 和 TLS 時,請在 Edge 中建立虛擬主機,並將虛擬主機設為使用 Keystore 和 Truststore。
瞭解詳情:
建立虛擬主機的必要條件
建立虛擬主機之前,您必須具備以下資訊:
- 虛擬主機的公開網域名稱。舉例來說,您應該瞭解公開名稱是否為
api.myCompany.com
、myapi.myCompany.com
等。您建立虛擬主機時,以及為虛擬主機建立 DNS 記錄時,也會使用這項資訊。 -
如為單向傳輸層安全標準 (TLS),您必須建立 KeyStore,並在其中含有下列項目:
- TLS 憑證:是由憑證授權單位 (CA) 簽署的憑證,或是最後一個憑證由 CA 簽署的憑證鏈結。
- 私密金鑰 - Edge 支援高達 2048 位元的金鑰大小。通關密語為選用項目。
- 如果採用雙向傳輸層安全標準 (TLS),您需要 KeyStore,以及需要可保存用戶端憑證的信任儲存庫,以及選用憑證的 CA 鏈結。即使憑證是由 CA 簽署,您還是需要信任儲存庫。
如要進一步瞭解如何建立 KeyStore 和信任儲存庫,請參閱 Keystore 和 Truststore。
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 連線使用的 KeyStore 和金鑰。
如要啟用雙向傳輸層安全標準 (TLS),請將 <ClientAuthEnabled>
元素設為 true
,並使用 <TrustStore>
元素指定信任儲存庫。信任儲存庫存放了用戶端的憑證,以及 (選用) 憑證的 CA 鏈結。
決定在虛擬主機中指定 KeyStore 和信任儲存庫名稱的方式
在上方的虛擬主機範例中,您已使用「參照」指定 KeyStore。參照是一種包含 KeyStore 名稱的變數,而非直接指定 KeyStore 名稱。
使用參照的優點是,您可以變更參照的值來變更虛擬主機使用的 KeyStore,原因通常是因為目前 KeyStore 中的憑證將於近期到期。變更參照值時,不需要重新啟動邊緣路由器。
您也可以在虛擬主機中使用常值 KeyStore 名稱。不過,如果您為了變更 KeyStore 名稱來修改虛擬主機,則須重新啟動邊緣路由器。
使用 KeyStore 和 Truststore 的參照限制
使用 KeyStore 和信任儲存庫的參照時,必須考量下列限制:
- 您必須支援 SNI,並在 Apigee 路由器上終止 SSL,才能在虛擬主機中使用 KeyStore 和 Truststore 參照。
- 如果 Apigee 路由器前方有負載平衡器,且您在負載平衡器上終止 TLS,您就無法在虛擬主機中使用 KeyStore 和 Truststore 參照。
修改現有虛擬主機,以使用 KeyStore 和 Truststore 的參照
Apigee 強烈建議虛擬主機使用 KeyStore 和 Truststore 的參照。 參照可讓您變更虛擬主機使用的 KeyStore 和信任儲存庫,而不必重新啟動邊緣路由器。
如果虛擬主機目前設定為使用 KeyStore 或 Truststore 的常值名稱,您可以將這些主機轉換為使用參照。如要這麼做,請更新虛擬主機以使用參照,然後重新啟動邊緣路由器。
設定 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#ciphersuites。
指定 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
- 重新啟動 Edge Router:
/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 的虛擬主機
這個範例透過參照指定虛擬主機的 KeyStore。使用參照可讓您變更 KeyStore,無須重新啟動路由器。
請按照下列程序建立虛擬主機:
- 按照以下所述流程,建立及設定名為 myTestKeystore 的 KeyStore:Keystore 和 Truststores。確認 KeyStore 針對憑證和私密金鑰使用 myKeyAlias 的別名名稱。
-
請使用下列 POST API 呼叫,為您在上方建立的 KeyStore 建立名為 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 名稱和參照類型指定為
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 位址或網域名稱。請務必指定正確的 KeyStore 參照和金鑰別名:
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 Proxy,請將虛擬主機新增至 Proxy 端點的
<HTTPConnection>
元素。系統會自動將虛擬主機新增至所有新的 API Proxy。請參閱「關於虛擬主機」中的「建立虛擬主機後更新 API Proxy」一節。
將 API Proxy 更新為使用虛擬主機,並為主機別名建立 DNS 記錄後,您可以按照下列步驟存取 API Proxy:
https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}
例如:
https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282
建立及修改 KeyStore 或 Truststore 的參照
您可以選擇將虛擬主機設定為改用 KeyStore 或信任儲存庫的「參照」。使用參照的優點是,您可以將參照更新為指向其他 KeyStore 或信任儲存庫,這樣就能更新傳輸層安全標準 (TLS) 憑證,而不必重新啟動路由器。
例如,下列是使用 KeyStore 參照的虛擬主機:
<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
參照會指定 KeyStore 的名稱及其類型。
請使用下列 GET API 呼叫來查看參照:
curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
如要在日後將參照變更為指向其他 KeyStore,並確保別名使用相同的名稱,請使用下列 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