503 서비스 사용 불가 - SSL 핸드셰이크 실패

API 모니터링

절차 #1: API 모니터링 사용

API 모니터링을 사용하여 오류를 진단하려면 다음 안내를 따르세요.

1. 적절한 역할이 있는 사용자로 Apigee Edge UI에 로그인합니다.

2. 문제를 조사하려는 조직으로 전환합니다.

   
3. 분석 > API 모니터링 > 조사 페이지로 이동합니다.
4. 오류를 관찰한 특정 기간을 선택합니다.

5. 시간을 기준으로 결함 코드를 표시합니다.

6. 아래와 같이 오류 코드가 messaging.adaptors.http.flow.SslHandshakeFailed인 셀을 선택합니다.

   ( 더 큰 이미지 보기)

   

7. 오류 코드 messaging.adaptors.http.flow.SslHandshakeFailed에 관한 정보가 아래와 같이 표시됩니다.

   ( 더 큰 이미지 보기)

   

8. 로그 보기 를 클릭하고 실패한 요청이 있는 행을 펼칩니다.

   ( 더 큰 이미지 보기)

   
9. 로그 창에서 다음 세부정보를 확인합니다.
   • 요청 메시지 ID
   • 상태 코드: 503
   • 결함 소스: target
   • 오류 코드: messaging.adaptors.http.flow.SslHandshakeFailed

Trace

절차 #2: Trace 도구 사용

Trace 도구를 사용하여 오류를 진단하려면 다음 단계를 따르세요.

1. 트레이스 세션을 사용 설정하고 다음 중 하나를 사용 설정합니다.
   • 오류 코드 messaging.adaptors.http.flow.SslHandshakeFailed와 함께 503 Service Unavailable 오류가 발생할 때까지 기다립니다.
   • 문제를 재현할 수 있는 경우 API를 호출하여 문제를 재현합니다. 503 Service Unavailable

2. Show all FlowInfos(모든 FlowInfos 표시)가 사용 설정되어 있는지 확인합니다.

   
3. 실패한 요청 중 하나를 선택하고 트레이스를 검사합니다.
4. trace의 여러 단계를 살펴보고 실패가 발생한 위치를 찾습니다.

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 오류 값은 Apigee Edge의 메시지 프로세서가 백엔드 서버의 인증서를 검증할 수 없어 SSL 핸드셰이크가 실패했음을 나타냅니다.
7. 추적에서 AX (애널리틱스 데이터 기록됨) 단계로 이동하여 클릭합니다.

8. 단계 세부정보 오류 헤더 섹션까지 아래로 스크롤하고 아래와 같이 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. 특정 기간(과거에 문제가 발생한 경우) 동안 오류 코드가 messaging.adaptors.http.flow.SslHandshakeFailed인 503 오류가 있는지 아니면 여전히 503와 함께 실패하는 요청이 있는지 검색합니다.

4. messaging.adaptors.http.flow.SslHandshakeFailed 값과 일치하는 X-Apigee-fault-code가 포함된 503 오류가 발견되면 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 도구 또는 NGINX 액세스 로그를 사용하여 실패한 요청 중 하나의 메시지 ID를 확인합니다.

2. 메시지 프로세서 로그(/opt/apigee/var/log/edge-message-processor/logs/system.log)에서 특정 요청 메시지 ID를 검색합니다. 다음과 같은 오류가 발생할 수 있습니다.

   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

   Apigee Edge의 메시지 프로세서가 백엔드 서버의 인증서를 검증할 수 없어 SSL 핸드셰이크가 실패했음을 나타냅니다.

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단계: 백엔드 서버의 인증서와 메시지 프로세서의 truststore에 저장된 인증서 비교

1. 백엔드 서버의 인증서 체인을 확인합니다.
2. 다음 단계에 따라 메시지 프로세서의 트러스트 저장소에 저장된 인증서를 확인합니다.

   1. TargetEndpoint의 SSLInfo 섹션에 있는 TrustStore 요소에서 truststore 참조 이름을 가져옵니다.

      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에서 환경 > 참조를 선택합니다. 특정 트러스트 저장소 참조의 참조 열에 있는 이름을 확인합니다. 이 이름이 트러스트 저장소 이름이 됩니다.

      ( 더 큰 이미지 보기)

      

   4. 위의 예에서 트러스트 저장소 이름은 다음과 같습니다.

      myCompanyTruststoreRef: myCompanyTruststore

3. 다음 API를 사용하여 트러스트 저장소에 저장된 인증서 (이전 단계에서 결정됨)를 가져옵니다.

   1. 키 저장소 또는 트러스트 저장소의 모든 인증서를 가져옵니다. 이 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은 키 저장소의 이름입니다.
      • OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 $TOKEN을 OAuth 2.0 액세스 토큰으로 설정합니다.
      • 이 예에서 사용되는 curl 옵션은 curl 사용에 설명되어 있습니다.

      샘플 출력:

      트러스트 저장소 myCompanyTruststore 예시의 인증서는 다음과 같습니다.

      [
        "serverCert"
      ]
      

   2. 키 저장소 또는 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은 키 저장소의 이름입니다.
      • CERT_NAME은 인증서 이름입니다.
      • OAuth 2.0 액세스 토큰 가져오기에 설명된 대로 $TOKEN을 OAuth 2.0 액세스 토큰으로 설정합니다.
      • 이 예에서 사용되는 curl 옵션은 curl 사용에 설명되어 있습니다.

      샘플 출력

      serverCert의 세부정보에는 다음과 같이 제목과 발급기관이 표시됩니다.

      Leaf/엔티티 인증서:

      "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단계에서 가져온 실제 서버 인증서와 3단계에서 받은 truststore에 저장된 인증서가 일치하는지 확인합니다. 일치하지 않으면 이것이 문제의 원인입니다.

   위에 표시된 예에서 한 번에 하나의 인증서를 살펴보겠습니다.

   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
      

      클라이언트 애플리케이션에 오류 코드 messaging.adaptors.http.flow.SslHandshakeFailed와 함께 503 Service Unavailable를 반환합니다.

올바른 FQDN

올바른 FQDN, 유효하고 완전한 인증서 체인으로 백엔드 서버의 키 저장소를 업데이트합니다.

1. 올바른 FQDN이 있는 백엔드 서버의 인증서가 없는 경우 적절한 CA (인증 기관)에서 적절한 인증서를 조달합니다.

2. 백엔드 서버의 인증서 체인이 유효하고 완전한지 확인합니다.

3. 리프 또는 항목 인증서에 있는 백엔드 서버의 올바른 FQDN이 대상 엔드포인트에 지정된 호스트 이름과 동일한 유효하고 완전한 인증서 체인이 있으면 백엔드의 키 저장소를 전체 인증서 체인으로 업데이트합니다.

올바른 백엔드 서버

대상 엔드포인트를 올바른 백엔드 서버의 호스트 이름으로 업데이트합니다.

1. 호스트 이름이 대상 엔드포인트에 잘못 지정된 경우 백엔드 서버 인증서의 FQDN과 일치하는 올바른 호스트 이름이 포함되도록 대상 엔드포인트를 업데이트합니다.

2. API 프록시에 변경사항을 저장합니다.

   위에 설명된 예시에서 백엔드 서버 호스트 이름이 잘못 지정된 경우 다음과 같이 백엔드 서버 인증서의 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>