您正在查看 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊
本文件概要說明如何為兩個功能領域設定 Edge 上的 TLS:
- 讓 API 用戶端存取 API Proxy。請使用 Edge Router 上的虛擬主機設定 TLS。
- Edge 可存取後端服務。請使用 Edge Message Processor 上的目標端點和目標伺服器設定 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 設定元素:
元素 | 說明 |
---|---|
<已啟用> |
啟用 Edge 和 API 用戶端之間,或在 Edge 和目標後端之間的單向傳輸層安全標準 (TLS)。 如果是虛擬主機,您必須定義包含憑證和私密金鑰的 KeyStore。 |
<ClientAuthEnabled> |
啟用 Edge 和 API 用戶端之間,或在 Edge 和目標後端之間進行雙向傳輸層安全標準 (TLS)。 一般來說,啟用雙向傳輸層安全標準 (TLS) 時,您必須在 Edge 上設定信任儲存庫。 |
<KeyStore> | KeyStore。 |
<KeyAlias> | 您將憑證和私密金鑰上傳到 KeyStore 時指定的別名。 |
<TrustStore> | 信任儲存庫。 |
<IgnoreValidationErrors> | 如果設為 True,Edge 會忽略 TLS 憑證錯誤。適用於目標伺服器和目標端點的 TLS,以及設定使用雙向 TLS 的虛擬主機時有效。預設值為否。 與目標端點/目標伺服器搭配使用時,如果後端系統使用 SNI,而傳回的憑證有主體名稱 (DN) 與主機名稱不符,您就無法忽略錯誤且連線會失敗。 |
<CommonName> | 如有指定,系統會驗證目標憑證通用名稱所用的值。 這個值僅適用於 TargetEndpoint 和 TargetServer 設定。但不適用於 VirtualHost 設定。 根據預設,指定的值會與目標憑證的一般名稱「完全」相符。
舉例來說,如果使用 或者,Apigee 也可使用 舉例來說,如果指定以下 <CommonName> 元素後,系統會在目標憑證中指定為 <CommonName wildcardMatch="true">*.myhost.com</CommonName> |
關於設定 <KeyStore> 和 <TrustStore> 元素
在上方的虛擬主機範例中,KeyStore 和信任儲存庫是依照references指定,格式如下:
<KeyStore>ref://myKeystoreRef</KeyStore> <TrustStore>ref://myTruststoreRef</TrustStore>
Apigee 強烈建議您一律使用 KeyStore 和信任儲存庫的參照。參照是包含 KeyStore 或信任儲存庫名稱的變數,而不是直接指定 KeyStore 名稱。在這個例子中:
myKeystoreRef
是包含 KeyStore 名稱的參照。在這個範例中,KeyStore 的名稱是 myKeystore。myTruststoreRef
是包含信任儲存庫名稱的參照。在這個範例中,信任儲存庫的名稱為 myTruststore。
憑證到期後,您必須更新虛擬主機或目標端點/目標伺服器,才能指定含有新憑證的 KeyStore 或 TrustStore。參照的好處是您可以修改參照值來變更 KeyStore 或信任儲存庫,而不必修改虛擬主機或目標端點/目標伺服器本身:
- Cloud 客戶:變更參考值不需要與 Apigee Edge 支援團隊聯絡。
- 針對私有雲客戶:變更參照值時不需要重新啟動 Edge 元件,例如路由器和訊息處理器。
您也可以直接指定 KeyStore 名稱和信任儲存庫名稱:
<KeyStore>myKeystore</KeyStore> <TrustStore>myTruststore</TrustStore>
如果您直接指定 KeyStore 或信任儲存庫的名稱,Cloud 客戶就必須與 Apigee Edge 支援團隊聯絡,而 Private Cloud 客戶必須重新啟動特定 Edge 元件才能更新憑證。
第三個選項僅適用於目標端點/目標伺服器:使用流程變數:
<KeyStore>{ssl.keystore}</KeyStore> <TrustStore>{ssl.truststore}</TrustStore>
流程變數適用於目標端點/目標伺服器,可讓您更新 KeyStore 或信任儲存庫 (例如參照)。不過,這些主機不適用於虛擬主機,且會要求您在每次要求時傳送 KeyStore、別名和信任儲存庫的相關資訊。
對 KeyStore 和信任儲存庫的參照限制
付費 Cloud 客戶,以及設定傳輸層安全標準 (TLS) 的所有私有雲客戶,在使用 KeyStore 和信任儲存庫時,都必須考量下列限制:
- 如果您在 Apigee 路由器上終止傳輸層安全標準 (TLS),則只能在虛擬主機中使用 KeyStore 和信任儲存庫參照。
- 如果您在 Apigee 路由器的前面有負載平衡器,且您終止負載平衡器的 TLS,則您無法在虛擬主機中使用 KeyStore 和 Truststore 參照。
如果現有虛擬主機使用常值 KeyStore 或信任儲存庫名稱
Edge 上現有的虛擬主機可能未設定為使用 KeyStore 和信任儲存庫的參照。在這種情況下,您可以更新虛擬主機來使用參照。
雲端邊緣
如要將虛擬主機變更為使用 KeyStore 的參照,您必須與 Apigee Edge 支援團隊合作。
適用於私有雲的邊緣
如何將虛擬主機轉換為使用參照:
- 更新虛擬主機以使用參照。
- 重新啟動路由器。
關於使用 Apigee 免費試用憑證和金鑰
如果您有付費的 Cloud Edge for Cloud 帳戶,但沒有 TLS 憑證和金鑰,則可建立使用 Apigee 免費試用憑證和金鑰的虛擬主機。也就是說,您不必先建立 KeyStore,就能建立虛擬主機。
這個 XML 物件使用 Apigee 免費試用憑證和金鑰定義虛擬主機,會省略 <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 設定取決於以下兩個主要因素:
- 您是 Edge Cloud 還是 Private Cloud 客戶?
- 您要如何更新已過期或即將到期的憑證?
雲端和私人雲端設定選項
下表列出 Cloud 和 Private Cloud 客戶的不同設定選項:
Private Cloud | 雲端 | |
---|---|---|
虛擬主機 | 完全掌控 | 僅對付費帳戶進行完全控管 |
目標端點/目標伺服器 | 完全掌控 | 完全掌控 |
私有雲客戶能完全掌控虛擬主機和目標端點/目標伺服器的設定。這個控制項包括建立及刪除虛擬主機,以及在虛擬主機上設定所有屬性的功能。
所有 Cloud 客戶 (包括付費和評估人員) 都能完全控管目標端點/目標伺服器的設定。此外,Google Cloud 付費客戶可全面控管虛擬主機,包括 TLS 屬性。
處理過期的憑證
如果 TLS 憑證過期,或是您的系統設定變更導致憑證失效,您就必須更新憑證。為虛擬主機或目標端點/目標伺服器設定 TLS 時,請先決定如何執行更新作業,再執行任何設定。
憑證過期時
在 Edge 上,憑證會儲存在下列兩個位置的其中之一:
- Keystore:包含傳輸層安全標準 (TLS) 憑證和私密金鑰,可在 TLS 使用期間識別實體。
- Truststore:在 TLS 用戶端包含信任的憑證,用於驗證向用戶端提供的 TLS 伺服器憑證。這類憑證通常是自行簽署的憑證、由信任的 CA 簽署的憑證,或做為雙向傳輸層安全標準 (TLS) 的一部分憑證。
如果 KeyStore 中的憑證過期,且您正在使用 KeyStore 的參照,則無法將新的憑證上傳至 KeyStore。而是會執行下列動作:
- 建立新的 KeyStore。
- 使用與舊 KeyStore 相同的別名名稱,將新憑證上傳到新的 KeyStore。
- 請更新虛擬主機或目標伺服器/目標端點中的參照,以使用新的 KeyStore。
如果信任儲存庫中的憑證到期,且您使用信任儲存庫的參照,
- 建立新的信任存放區。
- 將新憑證上傳到新的信任儲存庫。別名名稱對信任儲存庫無關。注意:如果憑證屬於鏈結的一部分,您必須建立包含所有憑證的單一檔案,然後將該檔案上傳至單一別名,或為鏈結中的所有憑證,使用不同的別名,分別上傳至信任儲存庫。
- 請更新虛擬主機或目標伺服器/目標端點中的參照,以使用新的信任儲存庫。
過期憑證的更新方法摘要
您用於指定虛擬主機或目標端點/目標伺服器中 KeyStore 和信任存放區的名稱的方法,會決定如何更新憑證。例如:
- 參考資料
- 直接名稱
- 流程變數
每一種方法在更新程序中都會受到不同的影響,如下表所述。如您所見,參考資料可為 Cloud 和 Private Cloud 客戶提供最大的彈性:
設定類型 | 如何更新/替換憑證 | Private Cloud | 雲端 |
---|---|---|---|
參考資料 (建議) |
針對 KeyStore,請以「新名稱」和與舊別名「相同」的別名建立新的 KeyStore。 如果是信任儲存庫,請以新名稱建立信任儲存庫。 |
更新 KeyStore 或信任儲存庫的參照。 您不必重新啟動路由器或訊息處理器。 |
更新 KeyStore 或信任儲存庫的參照。 您不需要與 Apigee 支援團隊聯絡。 |
流程變數 (僅限目標端點) |
如果是 KeyStore,請以新名稱和別名來建立新的 KeyStore,或使用新名稱的別名。 如果是信任儲存庫,請以新名稱建立信任儲存庫。 |
針對每個要求,使用新 KeyStore、別名或信任儲存庫的名稱傳遞更新後的資料流變數。 您不必重新啟動路由器或訊息處理器。 |
針對每個要求,使用新 KeyStore、別名或信任儲存庫的名稱傳遞更新後的資料流變數。 您不需要與 Apigee 支援團隊聯絡。 |
直接 | 建立新的 KeyStore、別名、信任儲存庫。 |
更新虛擬主機,然後重新啟動路由器。
如果目標端點/目標伺服器使用了信任儲存庫,請重新部署 Proxy。 |
如果是虛擬主機,請與 Apigee Edge 支援團隊聯絡,以便重新啟動路由器。 如果目標端點/目標伺服器使用了信任儲存庫,請重新部署 Proxy。 |
直接 | 請刪除 KeyStore 或信任存放區,並以相同名稱重新建立。 |
無須更新虛擬主機,不必重新啟動路由器。然而,在設定新的 KeyStore 和別名之前,API 要求會失敗。 如果 KeyStore 用於 Edge 和後端服務之間的雙向傳輸層安全標準 (TLS),請重新啟動訊息處理器。 |
不必更新虛擬主機。不過,在設定新的 KeyStore 和別名之前,API 要求會失敗。 如果 KeyStore 用於 Edge 和後端服務之間的雙向 TLS,請聯絡 Apigee Edge 支援團隊來重新啟動訊息處理器。 |
直接 | 僅適用於信任儲存庫,請將新的憑證上傳到信任儲存庫。 |
如果虛擬主機使用信任儲存庫,請重新啟動路由器。 如果目標端點/目標伺服器使用了信任儲存庫,請重新啟動訊息處理器。 |
如果是虛擬主機,請與 Apigee Edge 支援團隊聯絡,以便重新啟動 Edge Router。 如果目標端點/目標伺服器使用了信任儲存庫,請與 Apigee Edge 支援團隊聯絡,重新啟動訊息處理器。 |