為 API BaaS 設定傳輸層安全標準 (TLS)

Edge for Private Cloud 4.18.01 版

TLS (傳輸層安全標準，前身為 SSL) 是標準安全性技術，可確保 API 環境中的訊息安全且經過加密。您可以在 API BaaS 入口網站和 API BaaS Stack 節點上設定 TLS。

下圖顯示 API BaaS 的一般部署圖，其中包含一個 BaaS 入口網站節點和三個 API BaaS Stack 節點。

開發人員使用瀏覽器向入口網站提出要求。根據預設，要求會使用入口網站節點通訊埠 9000 上的 HTTP 通訊協定。

這項部署作業包含入口網站和 Stack 節點之間的負載平衡器。在這種設定中，入口網站會向負載平衡器發出 HTTP 要求，然後負載平衡器會將要求轉送至其中一個 Stack 節點。建議您在正式環境系統中採用這個部署環境。

TLS 設定選項

為 API BaaS 設定 TLS 時，有幾種選項：

  • 在入口網站和 Stack 節點的負載平衡器上設定 TLS

    在這個設定中，開發人員會使用 HTTPS 通訊協定存取入口網站，而在瀏覽器中執行的入口網站則會使用 HTTPS，透過負載平衡器向 Stack 節點發出要求。負載平衡器會使用 HTTP 存取 Stack 節點。
  • 在入口網站、負載平衡器和 Stack 節點上設定 TLS

    為提高安全性，請將負載平衡器設為使用 TLS 存取 Stack 節點。
  • 在入口網站和單一 Stack 節點上設定 TLS

    在小型環境 (例如測試或開發環境) 中，您可能只有一個 Stack 節點，因此不需要加入負載平衡器。在這個設定中，請在入口網站和 Stack 節點上設定 TLS。
  • 在入口網站的負載平衡器上設定 TLS

    上圖未顯示的選項是在入口網站節點前方使用負載平衡器。在該設定中，您可以在負載平衡器上設定 TLS，也可以在負載平衡器和入口網站之間的連線上設定 TLS。

確認 TLS 通訊埠已開啟

下列程序會在預設的入口網站通訊埠 9000 和 Stack 節點 8080 上設定 TLS。不過，您可以視需要變更這個通訊埠。

無論使用哪個通訊埠，都必須確保節點上的通訊埠已開啟。舉例來說，您可以使用下列指令開啟通訊埠 8443：

$ iptables -A INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT --verbose

在 API BaaS 堆疊上設定 TLS

根據預設，API BaaS Stack 的 TLS 為停用狀態。接著，您可以使用 Stack 節點的 IP 位址或 DNS 名稱和通訊埠 8080，透過 HTTP 存取 BaaS API。例如：

http://stack_IP:8080

或者，您也可以設定 BaaS API 的 TLS 存取權，以便透過下列格式存取：

https://stack_IP:8080

在本範例中，您會將 TLS 存取權設為使用通訊埠 8080。不過，您不一定要使用通訊埠 8080，可以將 Stack 設為使用其他通訊埠。唯一的要求是防火牆必須允許透過指定通訊埠傳輸流量。

Stack 只能透過單一通訊埠支援一種類型的要求 (HTTP 或 HTTPS)。因此，如果您在通訊埠 8080 設定 HTTPS 存取權，就無法使用 HTTP 存取通訊埠 8080。如果將 Stack 設為透過 HTTPS 使用通訊埠 8443，Stack 就不會再監聽通訊埠 8080。

請按照下列程序，設定 Stack 的 TLS 存取權：

  1. 產生 KeyStore JKS 檔案，其中包含 TLS 憑證和私密金鑰。詳情請參閱「為 Edge On-Premises 設定 TLS/SSL」。
    注意：請確認 KeyStore 和金鑰的密碼相同。
  2. 將 KeyStore JKS 檔案複製到 Stack 節點上的目錄，例如 /opt/apigee/customer/application。「apigee」使用者必須能存取該目錄。
  3. 將 JKS 檔案的擁有權變更為「apigee」使用者：
    > chown apigee:apigee /opt/apigee/customer/application/keystore.jks

    其中 keystore.jks 是 KeyStore 檔案的名稱。
  4. 編輯 /opt/apigee/customer/application/usergrid.properties 檔案，設定下列屬性，包括 JKS 檔案的路徑，以及 KeyStore 和金鑰的密碼。如果該檔案不存在，請建立該檔案：
    tomcat-server_scheme=https
    tomcat-server_secure=true
    tomcat-server_ssl.enabled=true
    tomcat-server_keystore.type=JKS
    tomcat-server_keystore.file=/opt/apigee/customer/application/keystore.jks
    tomcat-server_keystore.password=password
    tomcat-server_keyalias=keystore_alias
    tomcat-server_clientauth.enabled=false
    tomcat-server_ssl.protocols=TLSv1,TLSv1.1,TLSv1.2
    # By default, TLS access uses port 8080.
    # Use this property to specify a different port.
    # tomcat-server_port=8080

    警告：password 值必須為明文。 因此，您應保護 usergrid.properties，防止未經授權的存取。

    使用 tomcat-server_keyalias 屬性指定 KeyStore 別名。您在建立金鑰時設定了金鑰別名。 舉例來說，您可以使用 keytool 指令的 -alias 選項來設定。

    使用 tomcat-server_ssl.protocols 設定 Stack 支援的 TLS 通訊協定。如要查看 Java 8 支援的通訊協定清單，請前往 http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#jssename。
  5. 設定 Stack 節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  6. 重新啟動 BaaS 堆疊：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  7. 使用 HTTPS 在 Stack 節點上執行下列 cURL 指令，確認 TLS 是否正常運作：
    > curl -k https://localhost:8080/status -v

    如果 TLS 設定正確，您應該會看到包含狀態資訊的回應。

    如果您設定透過 8080 以外的通訊埠進行 TLS 存取，請修改上述指令，使用正確的通訊埠。
  8. 在所有 Stack 節點上重複執行。
  9. 如果 Stack 節點前方有負載平衡器，請設定負載平衡器，透過 HTTPS 向 Stack 節點提出要求。詳情請參閱負載平衡器的說明文件。

    如果入口網站直接向 Stack 發出要求，請按照下一節的說明，設定入口網站透過 HTTPS 存取 Stack。
  10. 請按照下方「在 Stack 或入口網站上為 TLS 設定 API BaaS Stack 節點」一節中的程序操作，確保 Stack 節點在產生使用者回應時，具有正確的 TLS 網址。

設定入口網站，透過 TLS 存取 Stack

在瀏覽器中執行的 BaaS 入口網站，會透過對 BaaS 堆疊發出 API 呼叫來運作。如果您將 BaaS Stack 設為使用 TLS，則必須將入口網站設為透過 HTTPS 發出這些呼叫。

API BaaS 安裝作業通常會設定為：

  • 在入口網站和 Stack 節點之間使用負載平衡器

    設定負載平衡器，透過 HTTPS 向 Stack 節點提出要求。詳情請參閱負載平衡器說明文件。

    在這項設定中，入口網站可以透過 HTTP 或 HTTPS 存取負載平衡器，具體取決於您設定負載平衡器的方式。如果負載平衡器使用 TLS，請按照下列程序設定入口網站，向 HTTPS 負載平衡器提出要求。
  • 讓入口網站直接向 Stack 提出要求

    按照下列說明，設定入口網站透過 HTTPS 存取 Stack。

請按照下列程序設定 API BaaS 入口網站，透過 HTTPS 發出 API 呼叫：

  1. 按照上述說明在 BaaS 堆疊上設定 TLS 存取權，或按照負載平衡器說明文件中的指示，在堆疊節點的負載平衡器上設定 TLS 存取權。
  2. 編輯 /opt/apigee/customer/application/portal.properties，設定下列屬性。如果該檔案不存在，請建立該檔案：
    baas.portal.config.overrideUrl=https://stackIP:port

    針對單一節點安裝，請將這個屬性的值指定為 API Stack 節點的 IP 位址或 DNS 名稱和通訊埠；如果您在 API BaaS Stack 節點前方有負載平衡器，請指定負載平衡器的 IP 位址或 DNS 名稱和通訊埠。
  3. 設定入口網站節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
  4. 使用下列指令重新啟動入口網站：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  5. 如果您在設定上述 Stack 的 TLS 存取權時使用自行簽署憑證，瀏覽器可能不允許從入口網站向 Stack 傳送要求。如果瀏覽器顯示錯誤，指出不允許透過 HTTPS 存取 Stack，請在瀏覽器中要求下列網址，並新增安全性例外狀況以允許存取：
    https://stackIP:port/status

    指定 API Stack 節點或負載平衡器的 IP 位址或 DNS 名稱和通訊埠。

在 API BaaS 入口網站設定 TLS

根據預設，使用者會透過入口網站伺服器上的通訊埠 9000 提出未加密的 HTTP 要求，藉此存取入口網站。您可以將入口網站設為使用 HTTPS，加密傳送至入口網站和從入口網站傳出的資料。

根據預設，您可以使用入口網站節點的 IP 位址或 DNS 名稱和通訊埠 9000，透過 HTTP 存取入口網站。例如：

http://portal_IP:9000

或者，您也可以設定入口網站的 TLS 存取權，以便透過下列格式存取：

https://portal_IP:9443

在本範例中，您會將 TLS 存取權設為使用通訊埠 9443。不過，您不一定要使用通訊埠 9443，可以將入口網站設為使用其他通訊埠。

入口網站只能透過單一通訊埠支援一種類型的要求 (HTTP 或 HTTPS)。因此，如果您在通訊埠 9000 設定 HTTPS 存取權，就無法使用 HTTP 存取通訊埠 9000。如果您將入口網站設為使用 HTTPS 的通訊埠 9443，入口網站就不會再監聽通訊埠 9000。

如要為入口網站設定 TLS，請按照下列步驟操作：

  1. 建立 PEM 格式的金鑰檔案和憑證檔案。
    注意：請確認金鑰或憑證沒有密碼/密碼詞組。
  2. 將 PEM 檔案複製到入口網站節點上的目錄，例如 /opt/apigee/customer/application。 「apigee」使用者必須能存取該目錄。
  3. 將 PEM 檔案的擁有權變更為「apigee」使用者：
    > chown apigee:apigee /opt/apigee/customer/application/*.PEM
  4. 編輯 /opt/apigee/customer/application/portal.properties 檔案，設定下列屬性。如果該檔案不存在，請建立該檔案：
    baas.portal.ssl=on
    baas.portal.ssl.certificate=/opt/apigee/customer/application/defaultcert.pem
    baas.portal.ssl.key=/opt/apigee/customer/application/defaultkey.pem
    baas.portal.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2
    # By default, TLS access uses port 9000.
    # Use this property to specify a different port.
    # baas.portal.listen=9000

    使用 baas.portal.ssl.protocols 設定入口網站支援的 TLS 通訊協定。如需支援的通訊協定清單，請參閱 Nginx 定義的 SSL 通訊協定名稱清單：http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols。
  5. 設定入口網站節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
  6. 重新啟動入口網站：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  7. 請按照下方「在 Stack 或入口網站上為 TLS 設定 API BaaS Stack 節點」一節中的程序操作，確保 Stack 節點具有正確的入口網站 TLS 網址。

在 Stack 或入口網站上設定 API BaaS 節點的 TLS

如果您在 Stack 或 Portal 節點前方加入負載平衡器，或直接在 Portal 或 Stack 節點上啟用 TLS，則必須為節點設定正確的網址，才能存取 Stack 和 Portal。舉例來說，Stack 節點在下列情況下需要這項資訊：

  • 在 BaaS API 要求的網址中加入網址。
  • 在重設密碼或傳送其他通知時，在電子郵件範本中新增連結。
  • 將使用者重新導向至特定入口網站頁面。

如果您在 Stack 節點前方使用負載平衡器，或是在 Stack 節點上設定 TLS，請在 /opt/apigee/customer/application/usergrid.properties 中設定下列屬性：

usergrid-deployment_usergrid.api.url.base=http://localhost:8080

將 http://localhost:8080 替換為負載平衡器的網址。如果負載平衡器設為使用 TLS，請使用 HTTPS 通訊協定。只有在使用非標準通訊埠 (即 HTTP 的通訊埠 80 和 HTTPS 的通訊埠 443 以外的通訊埠) 時，才需要加入通訊埠。

如果您在 Stack 節點前方使用負載平衡器，也必須在 /opt/apigee/customer/application/portal.properties 中設定下列屬性：

baas.portal.config.overrideUrl=http://localhost:8080

將 http://localhost:8080 替換為 Stack 負載平衡器的網址。

如果您在入口網站節點前使用負載平衡器，或在 Stack 節點上設定 TLS，請在 usergrid.properties 中設定下列屬性：

usergrid-deployment_portal.url=http://localhost:9000

將 http://localhost:9000 替換為負載平衡器的網址。如果負載平衡器設為使用 TLS，請使用 HTTPS 通訊協定。只有在使用非標準通訊埠 (即 HTTP 的通訊埠 80 和 HTTPS 的通訊埠 443 以外的通訊埠) 時，才需要加入通訊埠。

編輯 usergrid.properties 後：

  1. 設定 Stack 節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid configure
  2. 重新啟動 BaaS 堆疊：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  3. 如果您修改了 portal.properties，請設定入口網站節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
  4. 重新啟動 BaaS 入口網站：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart