프라이빗 클라우드용 API에 대한 TLS 액세스 구성

Apigee Edge 문서입니다.
Go to the Apigee X 문서로 이동합니다. info

Edge의 가상 호스트는 API 프록시가 노출되는 도메인 및 포트를 정의하고 더 나아가 앱에서 API 프록시에 액세스하기 위해 사용하는 URL을 확인합니다.

또한 가상 호스트는 API 프록시에 액세스하는 데 HTTP 프로토콜을 사용할 것인지 또는 TLS를 사용하는 암호화된 HTTPS 프로토콜을 사용할 것인지 정의합니다. HTTPS 및 TLS를 사용하도록 가상 호스트를 구성할 때는 Edge에서 가상 호스트를 만들고 키 저장소 및 트러스트 저장소를 사용하도록 가상 호스트를 구성합니다.

자세히 알아보기:

가상 호스트를 만드는 데 필요한 사항

가상 호스트를 만들기 전에 다음 정보가 있어야 합니다.

  • 가상 호스트의 공개적으로 표시되는 도메인 이름입니다. 예를 들어 공개적으로 표시되는 이름이 api.myCompany.com, myapi.myCompany.com 등인지 알아야 합니다. 이 정보는 가상 호스트를 만들 때와 가상 호스트의 DNS 레코드를 만들 때 사용됩니다.
  • **단방향 TLS**의 경우 키 저장소를 만들어야 합니다. 키 저장소에는 다음이 포함됩니다.
    • TLS 인증서 - 인증 기관 (CA)에서 서명한 인증서 또는 마지막 인증서가 CA에서 서명한 인증서 체인입니다.
    • 비공개 키 - Edge는 최대 2048비트의 키 크기를 지원합니다. 암호는 선택사항입니다.
  • 양방향 TLS의 경우 키 저장소가 필요하며 클라이언트의 인증서와 선택적으로 인증서의 CA 체인을 보관할 트러스트 저장소가 필요합니다. 인증서가 CA에서 서명한 경우에도 트러스트 저장소가 필요합니다.

키 저장소 및 트러스트 저장소 만들기에 대한 자세한 내용은 키 저장소 및 트러스트 저장소를 참조하세요.

TLS용 가상 호스트 구성

가상 호스트를 만들려면 가상 호스트를 정의하는 XML 객체를 만듭니다. 다음 XML 객체는 <SSLInfo> 요소를 사용하여 HTTPS를 통한 단방향 TLS 구성의 가상 호스트를 정의합니다.

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

이 예시에서 <Enabled> 요소는 단방향 TLS를 사용 설정하기 위해 true로 설정되고 <KeyStore> 및 <KeyAlias> 요소는 TLS 연결에서 사용하는 키 저장소와 키를 지정합니다.

양방향 TLS를 사용 설정하려면 <ClientAuthEnabled> 요소를 true로 설정하고 트러스트 저장소를 <TrustStore> 요소를 사용하여 지정합니다. 트러스트 저장소에는 클라이언트의 인증서와 선택적으로 인증서의 CA 체인이 포함됩니다.

가상 호스트에서 키 저장소 및 트러스트 저장소 이름을 지정하는 방법 결정

위의 가상 호스트 예시에서는 참조 를 사용하여 키 저장소를 지정했습니다. 참조는 키 저장소 이름을 직접 지정하는 대신 키 저장소의 이름이 포함되는 변수입니다.

참조를 사용하면 현재 키 저장소의 인증서가 곧 만료될 때 참조 값을 변경하여 가상 호스트에서 사용되는 키 저장소를 변경할 수 있다는 장점이 있습니다. 참조의 값을 변경할 때는 Edge 라우터를 다시 시작할 필요가 없습니다

또는 가상 호스트에서 리터럴 키 저장소 이름을 사용할 수 있습니다. 그러나 키 저장소 이름을 변경하도록 가상 호스트를 수정하는 경우 Edge 라우터를 다시 시작해야 합니다.

키 저장소 및 트러스트 저장소 사용에 대한 제한

키 저장소 및 트러스트 저장소에 대한 참조를 사용할 때는 다음 제한사항을 고려해야 합니다.

  • SNI를 지원하고 Apigee 라우터에서 SSL을 종료하는 경우에만 가상 호스트에서 키 저장소 및 트러스트 저장소 참조를 사용할 수 있습니다.
  • Apigee 라우터 앞에 부하 분산기가 있고 부하 분산기에서 TLS를 종료한 경우 가상 호스트에서 키 저장소 및 트러스트 저장소 참조를 사용할 수 없습니다.

키 저장소 및 트러스트 저장소에 대한 참조를 사용하도록 기존 가상 호스트 수정

Apigee에서는 가상 호스트가 키 저장소 및 트러스트 저장소에 대한 참조를 사용하도록 적극 권장합니다. 참조를 사용하면 Edge 라우터를 다시 시작하지 않고도 가상 호스트에서 사용하는 키 저장소와 트러스트 저장소를 변경할 수 있습니다.

가상 호스트가 현재 키 저장소 또는 트러스트 저장소의 리터럴 이름을 사용하도록 구성된 경우 참조를 사용하도록 변환할 수 있습니다. 이렇게 하려면 참조를 사용하도록 가상 호스트를 업데이트한 후 Edge 라우터를 다시 시작합니다.

Edge 4.15.07 이하 버전의 TLS 암호화 및 프로토콜 설정

Edge 버전 4.15.07 이하를 사용하는 경우 <SSLInfo> 태그의 <Ciphers> 및 <Protocols> 하위 태그를 사용하여 가상 호스트에서 사용하는 TLS 프로토콜 및 암호화를 설정합니다. 이러한 태그 는 아래 표에 설명되어 있습니다.

예를 들면 다음과 같습니다.

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

<Cipher> 태그는 암호화의 Java 및 JSSE 이름을 사용합니다. 예를 들어 Java 8의 경우 http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites를 참조하세요.

Edge 4.16.01~4.16.09의 TLS 암호화 및 프로토콜 지정

Edge 4.16.01~4.16.09에서는 라우터에서 가상 호스트의 기본 암호화 및 프로토콜을 전역적으로 설정합니다. 그러면 이러한 기본값이 모든 가상 호스트에 적용됩니다.

토큰을 사용하여 기본 프로토콜 및 암호화를 지정합니다.

  • 기본 프로토콜을 지정하려면 conf_load_balancing_load.balancing.driver.server.ssl.protocols 토큰을 사용합니다.
  • 라우터의 기본 암호화를 지정하려면 conf_load_balancing_load.balancing.driver.server.ssl.ciphers 토큰을 사용합니다.

conf_load_balancing_load.balancing.driver.server.ssl.protocols 토큰 의 기본값은 다음과 같습니다.

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

이 설정은 라우터가 TLS 버전 1.0, 1.1, 1.2를 지원하도록 지정합니다. 토큰에 공백으로 구분된 값 목록을 지정합니다.

conf_load_balancing_load.balancing.driver.server.ssl.ciphers 토큰 의 기본값은 다음과 같습니다.

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

이 설정은 다음을 지정합니다.

  • 키 길이가 128비트 이상이어야 합니다 (HIGH).
  • 인증이 없는 암호화 제외 (!aNULL)
  • MD5를 사용하는 암호화 스위트 제외 (!MD5)
  • DH (익명 DH, 임시 DH, 고정 DH 포함) 및 3DES를 사용하는 암호화 스위트 제외 (!DH+3DES)
  • RSA 키 교환 및 3DES를 사용하는 암호화 스위트 제외 (!RSA+3DES)

이 토큰에서 허용하는 구문 및 값에 대한 자세한 내용은 OpenSSL 암호화를 참조하세요. 이 토큰은 TLS_RSA_WITH_AES_128_CBC_SHA256과 같은 Java/JSSE 암호화 이름이 아닌 AES128-SHA256과 같은 OpenSSL 암호화 이름을 사용합니다.

라우터의 토큰을 설정하려면 다음 단계를 따르세요.

  1. /opt/apigee/customer/application/router.properties 파일을 수정합니다. 파일이 없으면 만듭니다.
  2. conf_load_balancing_load.balancing.driver.server.ssl.ciphers 토큰을 설정합니다. 예를 들어 TLSv1.2만 지정하고 사전 공유 키를 사용하는 암호화 스위트를 제외하려면 다음을 추가합니다!PSK: 
    conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK
  3. router.properties 파일의 소유자가 apigee인지 확인합니다. 
    chown apigee:apigee /opt/apigee/customer/application/router.properties
  4. Edge 라우터를 다시 시작합니다. 
    /opt/apigee/apigee-service/bin/apigee-service edge-router restart
  5. 토큰의 값을 확인합니다. 
    /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Edge 버전 4.17.01 이상 버전의 TLS 가상 호스트 매개변수 설정

Edge 버전 4.17.01 이상을 사용하는 경우 개별 가상 호스트의 일부 TLS 속성(예: TLS 프로토콜 및 암호화)을 <Properties> 하위 태그를 사용하여 설정할 수 있습니다. <VirtualHost> 태그. 이러한 태그는 가상 호스트 속성 참조에 설명되어 있습니다.

예를 들면 다음과 같습니다.

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

ssl_ciphers 토큰에서 허용하는 구문 및 값에 대한 자세한 내용은 OpenSSL 암호화를 참조하세요. 이 토큰은 TLS_RSA_WITH_AES_128_CBC_SHA256과 같은 Java/JSSE 암호화 이름이 아닌 AES128-SHA256과 같은 OpenSSL 암호화 이름을 사용합니다.

HTTPS를 사용하는 가상 호스트 만들기

이 예시에서는 참조를 사용하여 가상 호스트의 키 저장소를 지정합니다. 참조를 사용하면 라우터를 다시 시작하지 않고도 키 저장소를 변경할 수 있습니다.

다음 절차에 따라 가상 호스트를 만듭니다.

  1. 키 저장소 및 트러스트 저장소에 설명된 절차에 따라 myTestKeystore 라는 키 저장소를 만들고 구성합니다. 키 저장소에서 인증서 및 비공개 키에 myKeyAlias라는 별칭 이름을 사용하는지 확인합니다.

  2. 다음 POST API 호출을 사용하여 위에서 만든 키 저장소에 keystoreref 라는 참조를 만듭니다.

    curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

    참조는 키 저장소의 이름과 참조 유형을 KeyStore로 지정합니다.

    참조를 보려면 다음 GET API 호출을 사용하세요.

    curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

  3. 가상 호스트 만들기 API를 사용하여 가상 호스트를 만듭니다. 여기서 <ms-IP>는 관리 서버 노드의 IP 주소 또는 도메인 이름입니다.

    올바른 키 저장소 참조 및 키 별칭을 지정해야 합니다.

    curl -X POST -H "Content-Type:application/xml" \
  http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
  -d '<VirtualHost  name="newTLSTrustStore2">
    <HostAliases>
      <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>false</ClientAuthEnabled>
      <KeyStore>ref://keystoreref</KeyStore>
      <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
  </VirtualHost>' \
  -u email:password
  4. 호스트 별칭과 일치하는 가상 호스트의 DNS 레코드를 만듭니다.

  5. 기존 API 프록시가 있는 경우 ProxyEndpoint의 <HTTPConnection> 요소에 가상 호스트를 추가합니다. 가상 호스트는 모든 새 API 프록시에 자동으로 추가됩니다.

    가상 호스트 정보에서 가상 호스트를 만든 후 API 프록시 업데이트를 참조하세요.

가상 호스트를 사용하도록 API 프록시를 업데이트하고 호스트 별칭의 DNS 레코드를 만든 후에는 아래와 같이 API 프록시에 액세스할 수 있습니다.

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

예를 들면 다음과 같습니다.

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

키 저장소 또는 트러스트 저장소에 대한 참조 만들기 및 수정

원하는 경우 키 저장소 또는 트러스트 저장소에 대한 참조 를 사용하도록 가상 호스트를 구성할 수 있습니다. 참조를 사용하면 라우터를 다시 시작하지 않고도 다른 키 저장소 또는 트러스트 저장소를 가리키는 참조를 업데이트하여 TLS 인증서를 업데이트할 수 있다는 이점이 있습니다.

예를 들어 아래 가상 호스트는 키 저장소에 대한 참조를 사용합니다.

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

다음 POST API 호출을 사용하여 keystoreref라는 참조를 만드세요.

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

참조는 키 저장소의 이름과 유형을 지정합니다.

참조를 보려면 다음 GET API 호출을 사용하세요.

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

다른 키 저장소를 가리키도록 나중에 참조를 변경하여 별칭의 이름이 동일하게 하려면 다음 PUT 호출을 사용합니다.

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password