503 服務無法使用 - SSL 握手失敗

API Monitoring

程序 #1：使用 API 監控功能

如何使用 API Monitoring 診斷錯誤：

1. 以下列使用者身分登入 Apigee Edge UI： 擔任適當角色

2. 切換到您要調查問題的機構。

   
3. 前往「Analyze」(分析) >「API 監控 >調查頁面。
4. 請選取您發現錯誤的確切時間範圍。

5. 根據「時間」繪製「Fault Code」指標。

6. 選取含有錯誤程式碼的儲存格 messaging.adaptors.http.flow.SslHandshakeFailed，如圖所示 如下：

   ( 查看較大的圖片)

   

7. 錯誤程式碼相關資訊 messaging.adaptors.http.flow.SslHandshakeFailed 會顯示為 如下所示：

   ( 查看較大的圖片)

   

8. 按一下「查看記錄」 ，然後展開失敗要求的資料列。

   ( 查看較大的圖片)

   
9. 在「Logs」(記錄檔) 視窗中，記下下列詳細資料：
   • 要求訊息 ID
   • 狀態碼： 503
   • 錯誤來源： target
   • 錯誤代碼： messaging.adaptors.http.flow.SslHandshakeFailed

Trace

程序 2：使用追蹤工具

如何使用追蹤工具診斷錯誤：

1. 啟用追蹤工作階段，並
   • 等待傳回錯誤代碼的 503 Service Unavailable 錯誤 messaging.adaptors.http.flow.SslHandshakeFailed即將發生，或
   • 如果可以重現問題，請發出 API 呼叫以重現問題 503 Service Unavailable

2. 確保已啟用「Show all FlowInfos」：

   
3. 請選取其中一個失敗的要求，然後檢查追蹤記錄。
4. 瀏覽追蹤記錄的各個階段，找出失敗的部分。

5. 錯誤通常會在「目標要求流程已開始」階段之後出現 如下所示：

   ( 查看較大的圖片)

   
6. 請留意追蹤記錄中的下列值：
   • 錯誤： SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.cause: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
   • error.class: com.apigee.errors.http.server.ServiceUnavailableException
   • 這個錯誤值 SSL Handshake failed sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target 表示 SSL 握手失敗。 因為 Apigee Edge 的訊息處理器無法驗證後端伺服器的 憑證
7. 前往追蹤記錄中的「AX」AX(已記錄 Analytics 資料) 階段，並按一下該階段。

8. 向下捲動至「Phase Details Error Headers」部分 X-Apigee-fault-code 和 X-Apigee-fault-source 的值，以及 X-Apigee-Message-ID，如下所示：

   ( 查看較大的圖片)

   
9. 請記下 X-Apigee-fault-code、X-Apigee-fault-source 的值。 和 X-Apigee-Message-ID：

錯誤標頭	值
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

程序 #3：使用 NGINX 存取記錄檔

如何使用 NGINX 存取記錄診斷錯誤：

1. 如果您是 Private Cloud 使用者，可以透過 NGINX 存取記錄檔判斷 取得 HTTP 503 Service Unavailable 的重要資訊

2. 查看 NGINX 存取記錄：

   /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

3. 搜尋是否有任何 503 錯誤和錯誤代碼 在特定時間範圍內的messaging.adaptors.http.flow.SslHandshakeFailed (如果 )，或是仍有任何要求因 503 而失敗。

4. 如果在 X-Apigee-fault-code 比對中發現任何 503 錯誤 messaging.adaptors.http.flow.SslHandshakeFailed的值，那麼 判斷 X-Apigee-fault-source. 的價值。

   NGINX 存取記錄中的 503 錯誤示例：

   ( 查看較大的圖片)

   

   上述 NGINX 存取記錄的範例項目如下 X-Apigee-fault-code 和 X-Apigee-fault-code

   標頭	值
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

訊息處理器記錄

程序 #4：使用訊息處理器記錄

1. 利用 API Monitoring、Trace 工具，確定其中一個失敗要求的訊息 ID。 或 NGINX 存取記錄 (如常見診斷步驟中所述)。

2. 在訊息處理器記錄中搜尋特定要求訊息 ID (/opt/apigee/var/log/edge-message-processor/logs/system.log)。你可能會觀察到 下列錯誤：

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR HTTP.CLIENT - HTTPClient$Context.handshakeFailed() :
   SSLClientChannel[Connected: Remote:X.X.X.X:443
   Local:192.168.194.140:55102]@64596 useCount=1
   bytesRead=0 bytesWritten=0 age=233ms  lastIO=233ms
   isOpen=true handshake failed, message: General SSLEngine problem
   

   上述錯誤表示訊息處理器之間的 SSL 交握失敗 和後端伺服器

   其後就會發生例外狀況，並提供詳細堆疊追蹤，如下所示：

   org:myorg env:test api:MyProxy rev:1
   messageid:myorg-28247-3541813-1
   NIOThread@1 ERROR ADAPTORS.HTTP.FLOW - RequestWriteListener.onException() :
   RequestWriteListener.onException(HTTPRequest@1522922c)
   javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1478)
   	at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
   	... <snipped>
   Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
   	at sun.security.ssl.Alerts.getSSLException(Alerts.java:203)
   	at sun.security.ssl.SSLEngineImpl.fatal(SSLEngineImpl.java:1728)
   	... <snipped>
   Caused by: sun.security.validator.ValidatorException: PKIX path building failed:
   sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid
   certification path to requested target
   	at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:397)
   	at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:302)
   	... <snipped>
     

   請注意，因下列原因導致握手失敗：

   Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

   這表示 SSL 握手失敗，因為 Apigee Edge 的訊息處理器 無法驗證後端伺服器的憑證。

第 1 階段

第 1 階段：決定後端伺服器的憑證鏈結

使用下列其中一種方法確認後端伺服器的憑證鏈結：

openssl s_client -connect BACKEND_SERVER_HOST_NAME:PORT#

Certificate chain
 0 s:/CN=mocktarget.apigee.net
   i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
 1 s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
 2 s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
   i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1

第 2 階段

第 2 階段：比較後端伺服器的憑證和儲存於 訊息處理者的信任存放區

1. 決定後端伺服器的憑證鏈結。
2. 使用以下程式碼判斷儲存在訊息處理器信任存放區中的憑證： 步驟如下：

   1. 從 TrustStore 元素取得信任儲存庫參照名稱 TargetEndpoint 的 SSLInfo 區段中。

      我們來看看 TargetEndpoint 中的 SSLInfo 部分範例 設定：

      <TargetEndpoint name="default">
      ...
         <HTTPTargetConnection>
            <Properties />
            <SSLInfo>
               <Enabled>true</Enabled>
               <ClientAuthEnabled>true</ClientAuthEnabled>
               <KeyStore>ref://myKeystoreRef</KeyStore>
               <KeyAlias>myKey</KeyAlias>
               <TrustStore>
                  ref://myCompanyTrustStoreRef
               </TrustStore>
            </SSLInfo>
         </HTTPTargetConnection>
         ...
      </TargetEndpoint>
      

   2. 在上述範例中，TrustStore 參照名稱是 myCompanyTruststoreRef。

   3. 在 Edge UI 中，選取「Environments」(環境) >「參考資料。請記下 特定信任儲存庫參考資料的「參考資料」欄。這將成為 信任儲存庫名稱

      ( 查看較大的圖片)

      

   4. 在上述範例中，信任儲存庫名稱是：

      myCompanyTruststoreRef：myCompanyTruststore

3. 取得儲存在信任存放區的憑證 (在前一個步驟中決定) 使用下列 API：

   1. 取得 KeyStore 或信任儲存庫的所有憑證。這個 API 會列出 專屬憑證

      公有雲使用者：

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      Private Cloud 使用者：

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs -H "Authorization: Bearer $TOKEN"
      

      地點：

      • ORGANIZATION_NAME 是機構名稱
      • ENVIRONMENT_NAME 是環境的名稱。
      • KEYSTORE_NAME 是 KeyStore 的名稱
      • $TOKEN 已設定為您的 OAuth 2.0 存取權杖，如下列所述： 取得 OAuth 2.0 存取權杖
      • 本例中使用的 curl 選項說明 使用 curl

      輸出內容範例：

      範例信任存放區 myCompanyTruststore 中的憑證如下：

      [
        "serverCert"
      ]
      

   2. 取得 KeyStore 或 Truststore 中特定憑證的認證詳細資料。 這個 API 會傳回 信任儲存庫

      公有雲使用者：

      curl -v -X GET https//api.enterprise.apigee.com/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      Private Cloud 使用者

      curl -v -X GET http://MANAGEMENT_HOST:PORT_#>/v1/organizations/ORGANIZATION_NAME/environments/ENVIRONMENT_NAME/keystores/KEYSTORE_NAME/certs/CERT_NAME -H "Authorization: Bearer $TOKEN"
      

      地點：

      • ORGANIZATION_NAME 是機構名稱
      • ENVIRONMENT_NAME 是環境的名稱。
      • KEYSTORE_NAME 是 KeyStore 的名稱
      • CERT_NAME 是憑證的名稱
      • $TOKEN 已設定為您的 OAuth 2.0 存取權杖，如下列所述： 取得 OAuth 2.0 存取權杖
      • 本例中使用的 curl 選項說明 使用 curl

      輸出內容範例

      serverCert 顯示的主題和核發機構詳細資料如下：

      分葉/實體證明：

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      

      中繼憑證：

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",
      

4. 驗證在步驟 1 中取得的實際伺服器憑證和憑證 儲存在信任的存放區中。如果兩者不相符 導致問題發生的原因

   以上述範例來說，一次只看一個憑證：

   1. 分葉憑證：

      從後端伺服器：

      s:/CN=mocktarget.apigee.net
      i:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
      

      透過訊息處理者 (用戶端) 信任儲存庫：

      "subject": "CN=mocktarget.apigee.net",
      "issuer": "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      

      儲存在信任存放區中的分葉憑證與後端的相符 伺服器

   2. 中繼憑證：

      從後端伺服器：

      s:/C=US/O=Google Trust Services LLC/CN=GTS CA 1D4
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      

      透過訊息處理者 (用戶端) 信任儲存庫：

      "subject" : "CN=GTS CA 1D4, O=Google Trust Services LLC, C=US",
      "issuer" : "CN=GTS Root R1, O=Google Trust Services LLC, C=US",
      

      儲存在信任存放區的中繼憑證 後端伺服器

   3. 根憑證：

      從後端伺服器：

      s:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      i:/C=US/O=Google Trust Services LLC/CN=GTS Root R1
      

      訊息處理者的 信任儲存庫

   4. 由於信任儲存庫中缺少根憑證，因此 訊息處理器會擲回下列例外狀況：

      sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
      

      且傳回 503 Service Unavailable 及錯誤代碼 messaging.adaptors.http.flow.SslHandshakeFailed至用戶端 應用程式。

正確的 FQDN

使用正確的 FQDN、有效且完整的憑證更新後端伺服器的 KeyStore 鏈結：

1. 如果沒有包含正確 FQDN 的後端伺服器憑證， 然後從適當的憑證授權單位 (憑證授權單位) 取得適當的憑證。

2. 驗證 有效且完整的後端伺服器憑證鏈結。

3. 取得有效且完整的憑證鏈結，並以正確的 FQDN 取得 分葉或實體憑證中與主機名稱完全相同的後端伺服器 將後端的 KeyStore 更新為 完成憑證鏈結。

正確的後端伺服器

使用正確的後端伺服器的主機名稱更新目標端點：

1. 如果主機名稱未在目標端點中指定，請更新 目標端點擁有與後端 FQDN 相符的正確主機名稱 伺服器憑證

2. 儲存 API Proxy 變更。

   在上述範例中，如果後端伺服器主機名稱有誤， 使用後端伺服器憑證中的 FQDN 進行修正 就是 backend.apigee.net，如下所示：

   <TargetEndpoint name="default">
      …
      <HTTPTargetConnection>
         <Properties />
         <SSLInfo>
            <Enabled>true</Enabled>
            <TrustStore>ref://myTrustStoreRef</TrustStore>
         </SSLInfo>
         <URL>https://backend.apigee.net/resource</URL>
      </HTTPTargetConnection>
   </TargetEndpoint>