503 Dịch vụ Không khả dụng - Lỗi Bắt tay SSL

Giám sát API

Quy trình số 1: Sử dụng tính năng giám sát API

Cách chẩn đoán lỗi bằng tính năng Giám sát API:

1. Đăng nhập vào giao diện người dùng Apigee Edge với tư cách là một người dùng có vai trò thích hợp.

2. Chuyển sang tổ chức mà bạn muốn điều tra vấn đề.

   
3. Chuyển đến trang Phân tích > Giám sát API > Điều tra.
4. Chọn khung thời gian cụ thể mà bạn quan sát thấy lỗi.

5. Vẽ Mã lỗi dựa trên Thời gian.

6. Chọn một ô có mã lỗi messaging.adaptors.http.flow.SslHandshakeFailed như minh hoạ dưới đây:

   ( xem hình ảnh lớn hơn)

   

7. Thông tin về mã lỗi messaging.adaptors.http.flow.SslHandshakeFailed hiển thị như sau:

   ( xem hình ảnh lớn hơn)

   

8. Nhấp vào Xem nhật ký rồi mở rộng hàng cho yêu cầu không thành công.

   ( xem hình ảnh lớn hơn)

   
9. Trong cửa sổ Logs (Nhật ký), hãy lưu ý những thông tin sau:
   • Yêu cầu mã nhận dạng thông báo
   • Mã trạng thái: 503
   • Nguồn lỗi: target
   • Mã lỗi: messaging.adaptors.http.flow.SslHandshakeFailed

Trace

Quy trình số 2: Sử dụng công cụ Theo dõi

Cách chẩn đoán lỗi bằng công cụ Theo dõi:

1. Bật tính năng phiên theo dõi và
   • Chờ lỗi 503 Service Unavailable với mã lỗi messaging.adaptors.http.flow.SslHandshakeFailed xảy ra, hoặc
   • Nếu bạn có thể tái hiện vấn đề, hãy thực hiện lệnh gọi API để tái hiện vấn đề đó 503 Service Unavailable

2. Đảm bảo bạn đã bật tuỳ chọn Show all FlowInfos (Hiện tất cả thông tin luồng):

   
3. Chọn một trong các yêu cầu không thành công rồi kiểm tra dấu vết.
4. Di chuyển qua các giai đoạn trong quá trình theo dõi và xác định vị trí xảy ra lỗi.

5. Bạn thường sẽ thấy lỗi này sau giai đoạn Target Request Flow Started (Đã bắt đầu quy trình yêu cầu mục tiêu) như minh hoạ dưới đây:

   ( xem hình ảnh lớn hơn)

   
6. Lưu ý các giá trị của các nội dung sau trong dấu vết:
   • lỗi: 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
   • Giá trị của lỗi 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 cho biết không giao tiếp SSL vì Bộ xử lý tin nhắn của Apigee Edge không thể xác thực chứng chỉ của máy chủ phụ trợ.
7. Chuyển đến Giai đoạn AX (Dữ liệu phân tích đã ghi lại) trong dấu vết rồi nhấp vào đó.

8. Di chuyển xuống mục Tiêu đề lỗi chi tiết giai đoạn rồi xác định giá trị của X-Apigee-fault-code và X-Apigee-fault-source và X-Apigee-Message-ID như minh hoạ dưới đây:

   ( xem hình ảnh lớn hơn)

   
9. Hãy lưu ý giá trị của X-Apigee-fault-code, X-Apigee-fault-source và X-Apigee-Message-ID:

Tiêu đề lỗi	Giá trị
X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
X-Apigee-fault-source	target
X-Apigee-Message-ID	MESSAGE_ID

NGINX

Quy trình 3: Sử dụng nhật ký truy cập NGINX

Cách chẩn đoán lỗi bằng nhật ký truy cập NGINX:

1. Nếu là người dùng Đám mây riêng tư, bạn có thể dùng nhật ký truy cập NGINX để xác định thông tin chính về HTTP 503 Service Unavailable.

2. Kiểm tra nhật ký truy cập NGINX:

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

3. Tìm kiếm xem có lỗi 503 nào với mã lỗi messaging.adaptors.http.flow.SslHandshakeFailed trong một khoảng thời gian cụ thể hay không (nếu vấn đề này xảy ra trong quá khứ) hoặc có yêu cầu nào vẫn không thành công với 503 hay không.

4. Nếu bạn tìm thấy bất kỳ lỗi 503 nào có X-Apigee-fault-code khớp với giá trị của messaging.adaptors.http.flow.SslHandshakeFailed, thì hãy xác định giá trị của X-Apigee-fault-source.

   Ví dụ về lỗi 503 trong nhật ký truy cập NGINX:

   ( xem hình ảnh lớn hơn)

   

   Mục mẫu ở trên từ nhật ký truy cập NGINX có các giá trị sau cho X-Apigee-fault-code và X-Apigee-fault-code

   Tiêu đề	Giá trị
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

Nhật ký Trình xử lý thư

Quy trình số 4: Sử dụng nhật ký trình xử lý thông báo

1. Xác định mã thông báo của một trong các yêu cầu không thành công bằng tính năng Giám sát API, Công cụ theo dõi hoặc Nhật ký truy cập NGINX như giải thích trong phần Các bước chẩn đoán thường gặp.

2. Tìm mã nhận dạng thông báo yêu cầu cụ thể trong nhật ký Trình xử lý thông báo (/opt/apigee/var/log/edge-message-processor/logs/system.log). Bạn có thể gặp phải lỗi sau:

   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
   

   Lỗi trên cho biết rằng giao thức bắt tay SSL không thành công giữa Bộ xử lý thông báo và máy chủ phụ trợ.

   Theo sau là một ngoại lệ với dấu vết ngăn xếp chi tiết như sau:

   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>
     

   Xin lưu ý rằng lỗi bắt tay là do:

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

   Việc này cho thấy quá trình giao tiếp SSL không thành công vì Bộ xử lý tin nhắn của Apigee Edge không thể xác thực chứng chỉ của máy chủ phụ trợ.

Giai đoạn 1

Giai đoạn 1: Xác định chuỗi chứng chỉ của máy chủ phụ trợ

Sử dụng một trong các phương thức sau để xác định chuỗi chứng chỉ của máy chủ phụ trợ:

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

Giai đoạn 2

Giai đoạn 2: So sánh chứng chỉ và chứng chỉ của máy chủ phụ trợ được lưu trữ trong kho tin cậy của Trình xử lý thông báo

1. Xác định chuỗi chứng chỉ của máy chủ phụ trợ.
2. Xác định chứng chỉ được lưu trữ trong kho lưu trữ tin cậy của Trình xử lý thông báo theo các bước sau:

   1. Lấy tên tham chiếu Truststore từ phần tử TrustStore ở phần SSLInfo trong TargetEndpoint.

      Hãy xem phần SSLInfo mẫu trong cấu hình TargetEndpoint:

      <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. Trong ví dụ trên, tên tham chiếu TrustStore là myCompanyTruststoreRef.

   3. Trong giao diện người dùng Edge, hãy chọn Environments > References (Môi trường > Tham chiếu). Hãy lưu ý tên trong cột Reference (Tham chiếu) cho thông tin tham chiếu cụ thể trong Truststore. Đây sẽ là tên kho lưu trữ tin cậy của bạn.

      ( xem hình ảnh lớn hơn)

      

   4. Trong ví dụ trên, tên Truststore là:

      myCompanyTruststoreRef: myCompanyTruststore

3. Lấy các chứng chỉ được lưu trữ trong Truststore (xác định ở bước trước) bằng các API sau:

   1. Nhận tất cả các chứng chỉ cho kho khoá hoặc kho lưu trữ tin cậy. API này liệt kê tất cả chứng chỉ trong kho tin cậy cụ thể.

      Người dùng Public Cloud:

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

      Người dùng Đám mây riêng tư:

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

      Địa điểm:

      • ORGANIZATION_NAME là tên của tổ chức
      • ENVIRONMENT_NAME là tên của môi trường
      • KEYSTORE_NAME là tên của kho khoá
      • $TOKEN được đặt thành mã truy cập OAuth 2.0 của bạn như mô tả trong Lấy mã truy cập OAuth 2.0
      • Các tuỳ chọn curl dùng trong ví dụ này được mô tả trong phần Dùng curl

      Ví dụ về mã được tạo:

      Các chứng chỉ từ kho lưu trữ tin cậy mẫu myCompanyTruststore là:

      [
        "serverCert"
      ]
      

   2. Lấy thông tin chi tiết về chứng chỉ cho chứng chỉ cụ thể từ Kho khoá hoặc Truststore. API này trả về thông tin về một chứng chỉ cụ thể trong kho lưu trữ tin cậy cụ thể.

      Người dùng Public Cloud:

      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"
      

      Người dùng Đám mây riêng tư

      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"
      

      Địa điểm:

      • ORGANIZATION_NAME là tên của tổ chức
      • ENVIRONMENT_NAME là tên của môi trường
      • KEYSTORE_NAME là tên của kho khoá
      • CERT_NAME là tên của chứng chỉ
      • $TOKEN được đặt thành mã truy cập OAuth 2.0 của bạn như mô tả trong Lấy mã truy cập OAuth 2.0
      • Các tuỳ chọn curl dùng trong ví dụ này được mô tả trong phần Dùng curl

      Kết quả mẫu

      Thông tin chi tiết về serverCert cho biết chủ thể và người phát hành như sau:

      Giấy chứng nhận Lá xanh/Pháp nhân:

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

      Chứng chỉ trung cấp:

      "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. Xác minh rằng chứng chỉ máy chủ thực tế thu được ở bước 1 và chứng chỉ được lưu trữ trong Truststore thu được ở bước 3 trùng khớp với nhau. Nếu chúng không khớp nhau thì đó chính là nguyên nhân của vấn đề.

   Từ ví dụ hiển thị trên, hãy xem một chứng chỉ tại một thời điểm:

   1. Giấy chứng nhận lá bài:

      Từ máy chủ phụ trợ:

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

      Từ kho lưu trữ tin cậy của Trình xử lý thư (ứng dụng khách):

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

      Chứng chỉ lá được lưu trữ trong Truststore khớp với chứng chỉ của máy chủ phụ trợ.

   2. Chứng chỉ trung gian:

      Từ máy chủ phụ trợ:

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

      Từ kho lưu trữ tin cậy của Trình xử lý thư (ứng dụng khách):

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

      Chứng chỉ trung gian được lưu trữ trong Truststore khớp với chứng chỉ của máy chủ phụ trợ.

   3. Chứng chỉ gốc:

      Từ máy chủ phụ trợ:

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

      Thiếu chứng chỉ gốc hoàn toàn trong kho lưu trữ tin cậy của Trình xử lý thông báo.

   4. Vì thiếu chứng chỉ gốc trong kho lưu trữ tin cậy nên Trình xử lý thông báo sẽ gửi ra trường hợp ngoại lệ sau:

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

      và trả về 503 Service Unavailable kèm theo mã lỗi messaging.adaptors.http.flow.SslHandshakeFailed cho các ứng dụng.

FQDN chính xác

Cập nhật kho khoá của máy chủ phụ trợ với FQDN chính xác, chuỗi chứng chỉ hợp lệ và đầy đủ:

1. Nếu bạn không có chứng chỉ của máy chủ phụ trợ có FQDN chính xác, hãy mua chứng chỉ phù hợp từ một CA (Tổ chức phát hành chứng chỉ) thích hợp.

2. Xác thực rằng bạn có một chuỗi chứng chỉ hợp lệ và hoàn chỉnh của máy chủ phụ trợ.

3. Sau khi bạn có chuỗi chứng chỉ hợp lệ và hoàn chỉnh với FQDN chính xác của máy chủ phụ trợ trong chứng chỉ thực thể hoặc chứng chỉ lá giống với tên máy chủ được chỉ định trong điểm cuối đích, hãy cập nhật kho khoá của phần phụ trợ bằng chuỗi chứng chỉ hoàn chỉnh.

Máy chủ phụ trợ chính xác

Cập nhật điểm cuối đích bằng tên máy chủ lưu trữ chính xác của máy chủ phụ trợ:

1. Nếu tên máy chủ được chỉ định không chính xác trong điểm cuối đích, hãy cập nhật điểm cuối đích để có tên máy chủ chính xác, khớp với FQDN trong chứng chỉ của máy chủ phụ trợ.

2. Lưu các thay đổi đối với proxy API.

   Trong ví dụ thảo luận ở trên, nếu tên máy chủ lưu trữ phụ trợ được chỉ định không chính xác, bạn có thể khắc phục bằng cách sử dụng FQDN từ chứng chỉ của máy chủ phụ trợ, đó là backend.apigee.net như sau:

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