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

Private Cloud v. 4.16.09 版本

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

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

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

這項部署作業會在 Portal 和 Stack 節點之間加入負載平衡器。在這個設定中，Portal 會向負載平衡器提出 HTTP 要求，而負載平衡器則會將要求轉送至其中一個堆疊節點。這是正式系統的建議部署環境。

TLS 設定選項

為 API BaaS 設定 TLS 時，您可以選擇：

  • 在入口網站和負載平衡器上為堆疊節點設定 TLS

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

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

    在測試或開發環境等小型環境中，您可能只有一個堆疊節點，這表示不需要加入負載平衡器。在這個配置中，請在 Portal 和 Stack 節點上設定 TLS。
  • 在 Portal 的負載平衡器上設定 TLS

    上方未提及的選項之一，是使用 Portal 節點前端的負載平衡器。在該設定中，您可以在負載平衡器上設定 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。接著，您可以使用堆疊節點的 IP 位址或 DNS 名稱以及通訊埠 8080，透過 HTTP 存取 BaaS API。例如：

http://stack_IP:8080

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

https://stack_IP:8080

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

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

請使用下列程序設定堆疊的 TLS 存取權：

  1. 產生包含 TLS 認證和私密金鑰的 KeyStore JKS 檔案。詳情請參閱「為 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
    # 根據預設，TLS 存取權會使用 8080 連接埠。
    # 請使用這項屬性指定不同的通訊埠。
    # tomcat-server_port=8080

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

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

    使用 tomcat-server_ssl.protocols 設定堆疊支援的 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. 將變更部署至 Tomcat：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid deploy
  7. 重新啟動 BaaS 堆疊：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  8. 使用 HTTPS 在堆疊節點上執行下列 cURL 指令，確認 TLS 是否運作：
    > curl -k https://localhost:8080/status -v

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

    如果您已設定 TLS 存取權，但使用的是 8080 以外的通訊埠，請修改上述指令，以便使用正確的通訊埠。
  9. 對所有 Stack 節點重複上述步驟。
  10. 如果您在資料結構節點前端有負載平衡器，請設定負載平衡器，以便透過 HTTPS 向資料結構節點提出要求。詳情請參閱負載平衡器的說明文件。

    如果入口網站直接向資料堆疊提出要求，請按照下一個章節所述，將入口網站設為透過 HTTPS 存取資料堆疊。
  11. 請按照「在堆疊或入口網站上為 TLS 設定 API BaaS 堆疊節點」一節所述的程序操作，確保堆疊節點在產生使用者回應時，能使用正確的 TLS 網址。

將入口網站設為透過傳輸層安全標準 (TLS) 存取堆疊

向 BaaS 堆疊發出 API 呼叫，以使用瀏覽器功能執行的 BaaS 入口網站。如果您將 BaaS 堆疊設為使用 TLS，則必須將入口網站設為透過 HTTPS 發出這些呼叫。

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

  • 在 Portal 和 Stack 節點之間使用負載平衡器

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

    在這種情況下，Portal 可以透過 HTTP 或 HTTPS 存取負載平衡器，具體取決於您如何設定負載平衡器。如果負載平衡器使用 TLS，請按照下列程序設定入口網站，以便向 HTTPS 負載平衡器提出要求。
  • 要求入口網站直接向 Stack 傳送要求

    按照以下說明將入口網站設為透過 HTTPS 存取堆疊。

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

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

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

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

在 API BaaS Portal 上設定 TLS

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

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

http://portal_IP:9000

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

https://portal_IP:9443

在這個範例中，您會將 TLS 存取權設為使用 9443 通訊埠。不過，您不一定要使用 9443 通訊埠，也可以將 Portal 設定為使用其他通訊埠。

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

如何為入口網站設定 TLS：

  1. 以 PEM 格式建立金鑰檔案和憑證檔案。
    注意：請確認金鑰或憑證上沒有密碼/密碼短句。
  2. 將 PEM 檔案複製到 Portal 節點上的目錄，例如 /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
    # 根據預設，TLS 存取權會使用通訊埠 9000。
    # 使用這個屬性指定不同的通訊埠。
    # baas.portal.listen=9000

    使用 baas.portal.ssl.protocols 設定 Portal 支援的 TLS 通訊協定。如要查看支援的通訊協定清單，請參閱 Nginx 定義的安全資料傳輸層 (SSL) 通訊協定名稱清單：http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols。
  5. 設定入口網站節點：
    > /opt/apigee-service/bin/apigee-service baas-portal Configuration
  6. 部署設定：
    > /opt/apigee-service/bin/apigee-service baas-portal deploy
  7. 重新啟動 Portal：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart
  8. 請按照「在堆疊或入口網站上，為 TLS 設定 API BaaS 堆疊節點」一節中的步驟操作，確保堆疊節點有正確的入口網站 TLS 網址。

在堆疊或入口網站上設定適用傳輸層安全標準 (TLS) 的 API BaaS 節點

如果您在堆疊和入口網站節點前方加入了負載平衡器，或是直接在入口網站或堆疊節點上啟用傳輸層安全標準 (TLS)，則必須使用正確的網址設定節點，才能存取堆疊和入口網站。例如，堆疊節點在下列情況中需要這項資訊：

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

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

usergrid-deployment_swagger.basepath=http://localhost:8080
usergrid-deployment_usergrid.organization.activation.url=http://localhost:8080/management/organizations/%s/activate
usergrid-deployment_usergrid.admin.activation.url=http://localhost:8080/management/users/%s/activate
usergrid-deployment_usergrid.admin.resetpw.url=http://localhost:8080/management/users/%s/resetpw
usergrid-deployment_usergrid.admin.confirmation.url=http://localhost:8080/management/users/%s/confirm
usergrid-deployment_usergrid.user.activation.url=http://localhost:8080/%s/%s/users/%s/activate
usergrid-deployment_usergrid.user.confirmation.url=http://localhost:8080/%s/%s/users/%s/confirm
usergrid-deployment_usergrid.user.resetpw.url=http://localhost:8080/%s/%s/users/%s/resetpw

將 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 替換為資料夾的負載平衡器網址。

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

usergrid-deployment_usergrid.view.management.organizations.organization.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.organizations.organization.confirm=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.activate=http://localhost:9000
usergrid-deployment_usergrid.view.management.users.user.confirm=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. 將變更部署至 Tomcat：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid deploy
  3. 重新啟動 BaaS Stack：
    > /opt/apigee/apigee-service/bin/apigee-service baas-usergrid restart
  4. 如果您修改了 portal.properties，請設定 Portal 節點：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal configure
  5. 部署變更：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal deploy
  6. 重新啟動 BaaS 入口網站：
    > /opt/apigee/apigee-service/bin/apigee-service baas-portal restart