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. 모든 FlowInfo 표시가 사용 설정되어 있는지 확인합니다.

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

5. 일반적으로 아래와 같이 Target Request Flow Started 단계 후에 오류가 표시됩니다.

   ( 큰 이미지 보기)

   
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. 비공개 클라우드 사용자인 경우 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. X-Apigee-fault-code가 messaging.adaptors.http.flow.SslHandshakeFailed 값과 일치하는 503 오류가 발견되면 X-Apigee-fault-source 값을 확인합니다.

   NGINX 액세스 로그의 503 오류 샘플:

   ( 큰 이미지 보기)

   

   위의 NGINX 액세스 로그 샘플 항목에는 X-Apigee-fault-code 및 X-Apigee-fault-source에 다음 값이 있습니다.

   헤더	값
   X-Apigee-fault-code	messaging.adaptors.http.flow.SslHandshakeFailed
   X-Apigee-fault-source	target

메시지 프로세서 로그

절차 4: 메시지 프로세서 로그 사용

1. 일반적인 진단 단계에 설명된 대로 API 모니터링, 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단계: 백엔드 서버의 인증서와 메시지 프로세서의 트러스트스토어에 저장된 인증서 비교

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

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

      샘플 출력:

      예시 신뢰 저장소 myCompanyTruststore의 인증서는 다음과 같습니다.

      [
        "serverCert"
      ]

   2. 키 저장소 또는 트러스트 저장소에서 특정 인증서의 인증서 세부정보를 가져옵니다. 이 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은 인증서의 이름입니다.
      • $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단계에서 획득한 실제 서버 인증서와 3단계에서 획득한 트러스트스토어에 저장된 인증서가 일치하는지 확인합니다. 일치하지 않으면 문제의 원인이 됩니다.

   위 예시에서 인증서를 하나씩 살펴보겠습니다.

   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. 리프 또는 엔티티 인증서에 백엔드 서버의 올바르고 완전한 인증서 체인이 있고 이 인증서 체인이 대상 엔드포인트에 지정된 호스트 이름과 동일한 경우 완전한 인증서 체인으로 백엔드의 키 저장소를 업데이트합니다.

올바른 백엔드 서버

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

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>