API 프록시에서 TLS 연결 정보에 액세스

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

Edge를 사용하면 단방향 TLS와 양방향 TLS를 지원하는 가상 호스트를 만들 수 있습니다. 단방향 TLS를 사용하면 클라이언트가 Edge Router에 배포된 가상 호스트에 세션 요청을 실행하고 라우터는 가상 호스트의 공개 키가 포함된 인증서로 응답합니다. 서명된 인증서의 경우 클라이언트는 인증 기관 (CA)에 인증서를 인증하도록 요청할 수 있습니다.

양방향 TLS에서는 클라이언트와 Edge 모두 요청의 일부로 검증되는 인증서를 통과합니다.

  • 에지 라우터는 TLS 클라이언트에 인증서를 제공하여 자체 인증을 진행합니다. 그러면 클라이언트는 인증서를 서버로 전송하기 전에 서버의 ID를 확인합니다.
  • TLS 클라이언트는 자체적으로 인증을 위해 에지에 인증서를 제공합니다.

자세한 내용은 가상 호스트 정보를 참고하세요.

TLS 연결 정보 캡처

TLS를 지원하는 가상 호스트를 통해 API 프록시를 요청하는 동안 Edge는 TLS 연결에 대한 정보를 캡처할 수 있습니다. 그러면 API 프록시가 흐름 변수를 통해 해당 정보에 액세스하여 추가 분석 및 검증을 수행할 수 있습니다.

Edge에서 캡처한 TLS 정보의 유형은 가상 호스트가 단방향 TLS를 지원하는지 또는 양방향 TLS를 지원하는지에 따라 다릅니다. 예를 들어 단방향 TLS의 경우 Edge는 TLS 연결에 사용되는 TLS 암호화 또는 TLS 프로토콜에 대한 정보를 캡처할 수 있습니다.

양방향 TLS의 경우 Edge는 단방향 TLS에서 캡처한 것과 동일한 모든 정보를 캡처하고 클라이언트의 인증서에 대한 정보도 캡처할 수 있습니다. 예를 들어 Edge는 클라이언트 인증서의 SHA1 디지털 지문과 클라이언트 인증서를 PEM 형식으로 캡처할 수 있습니다.

단방향 TLS와 양방향 TLS의 정보 캡처

다음 표에는 Edge에서 캡처하고 API 프록시에서 액세스할 수 있는 TLS 연결 정보가 포함된 흐름 변수가 나와 있습니다. 이 정보는 가상 호스트 정의에서 <ConnectionProperties>를 true로 설정하여 단방향 및 양방향 TLS에 대해 모두 캡처됩니다.

흐름 변수 설명
tls.cipher TLS 연결에 사용되는 암호화입니다.
tls.protocol TLS 연결에 사용되는 프로토콜입니다.
tls.server.name 요청된 SNI 서버 이름입니다.
tls.session.id

세션 식별자입니다.

이 흐름 변수는 <ConnectionProperties> 또는 <ClientProperties>를 또는 true로 설정한 경우에 사용할 수 있습니다.

양방향 TLS 중에 추가 TLS 정보 캡처

다음 표에는 Edge에서 양방향 TLS로 캡처한 클라이언트 인증서 세부정보가 포함된 흐름 변수가 나와 있습니다. 이 정보는 가상 호스트 정의에서 <ClientProperties>를 true로 설정하여 양방향 TLS를 위해 캡처됩니다.

흐름 변수 설명
tls.client.s.dn 클라이언트 인증서의 주제 고유 이름(DN)입니다.
tls.client.i.dn 클라이언트 인증서의 발급기관 고유 이름(DN)입니다.
tls.client.raw.cert PEM 형식의 클라이언트 인증서입니다.
tls.client.cert.serial 클라이언트 인증서의 일련번호입니다.
tls.client.cert.fingerprint 클라이언트 인증서의 SHA1 지문입니다.
tls.session.id

세션 식별자입니다.

이 흐름 변수는 <ConnectionProperties> 또는 <ClientProperties>를 true로 설정한 경우에 사용할 수 있습니다.

TLS 정보를 캡처하도록 가상 호스트 구성

TLS 정보를 캡처하도록 가상 호스트를 구성하려면 <PropagateTLSInformation>에서 다음 속성을 true로 설정합니다.

  • <ConnectionProperties>: 단방향 TLS와 양방향 TLS 모두에 TLS 연결 정보 캡처를 사용 설정합니다. 기본값은 false입니다.
  • <ClientProperties>: 양방향 TLS의 추가 정보 캡처를 사용 설정합니다. 기본값은 false입니다.

예를 들어 다음 가상 호스트 정의는 양방향 TLS를 사용하고 두 가지 유형의 TLS 정보를 모두 캡처할 수 있도록 합니다.

<VirtualHost name="secure">
    ....
    <SSLInfo>
        <Enabled>true</Enabled>
        # Enable two-way TLS.
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <KeyAlias>ks-alias</KeyAlias>
        <KeyStore>ref://ks-ref</KeyStore>
        <TrustStore>ref://ts-ref</TrustStore>
    </SSLInfo>
    <PropagateTLSInformation>
        <ConnectionProperties>true</ConnectionProperties>
        <ClientProperties>true</ClientProperties>
    </PropagateTLSInformation>
</VirtualHost>

JSON 본문을 전달하는 경우 속성을 다음과 같이 설정합니다.

  "propagateTLSInformation" : {
    "connectionProperties" : true,
    "clientProperties" : true
  }

헤더 크기 한도 설정

가상 호스트에서 TLS 정보 캡처를 사용 설정하면 Edge는 HTTP 헤더를 사용하여 해당 정보를 전달합니다. 따라서 클라우드용 Edge 또는 프라이빗 클라우드용 Edge 중 어느 것을 사용하는지에 따라 헤더 크기 한도가 적절하게 설정되어 있는지 확인해야 합니다.

  • 클라우드용 에지: Apigee가 헤더 크기를 적절하게 설정합니다.
  • 프라이빗 클라우드용 Edge: 기능을 사용할 수 없습니다.

API 프록시에서 흐름 변수에 액세스

API 프록시 내에서 TLS 흐름 변수에 액세스하여 검사할 수 있습니다. 예를 들어 AssignMessage 정책을 사용하여 액세스하고, JavaScript 정책을 사용하여 JavaScript에서 액세스할 수 있습니다.

프록시 또는 대상 흐름의 <Condition> 요소나 <Step> 또는 <RouteRule>에서 흐름 변수를 참조할 수도 있습니다. 예를 들어 클라이언트의 SN에 따라 요청을 다른 대상에 라우팅할 수 있습니다.

자세한 내용은 다음을 참고하세요.