Azure API Management 인스턴스에 대한 사용자 지정 도메인 이름 구성

  • 아티클

적용 대상: 모든 API Management 계층

Azure 클라우드에 Azure API Management 서비스 인스턴스를 만들면 Azure에서는 azure-api.net 하위 도메인(예: apim-service-name.azure-api.net)에 이 인스턴스를 할당합니다. contoso.com 등의 고유한 사용자 지정 도메인 이름을 사용하여 API Management 엔드포인트를 노출할 수도 있습니다. 이 문서에서는 기존 사용자 지정 DNS 이름을 API Management 인스턴스에 공개된 엔드포인트에 매핑하는 방법을 보여 줍니다.

Important

API Management는 호스트 헤더 값이 다음과 일치하는 요청만 허용합니다.

  • 게이트웨이의 기본 도메인 이름
  • 게이트웨이의 구성된 모든 사용자 지정 도메인 이름

필수 조건

  • API Management 인스턴스. 자세한 내용은 Azure API Management 인스턴스 만들기를 참조하세요.

  • 사용자 또는 사용자의 조직이 소유하고 있는 사용자 지정 도메인 이름입니다. 이 문서는 사용자 지정 도메인 이름을 확보하는 방법에 대한 지침은 제공하지 않습니다.

  • 선택적으로 퍼블릭 및 프라이빗 키(.PFX)가 있는 유효한 인증서입니다. 주체 또는 SAN(주체 대체 이름)이 도메인 이름과 일치해야 합니다(이렇게 하면 API Management 인스턴스에서 TLS를 통해 URL을 안전하게 공개할 수 있음).

    도메인 인증서 옵션을 참조하세요.

  • 사용자 지정 도메인 이름을 API Management 인스턴스의 기본 도메인 이름에 매핑하기 위해 DNS 서버에서 호스트되는 DNS 레코드입니다. 이 항목은 DNS 레코드를 호스트하는 방법에 대해서는 설명하지 않습니다.

    필수 레코드에 대한 자세한 내용은 이 문서 뒷부분의 DNS 구성을 참조하세요.

사용자 지정 도메인에 대한 엔드포인트

사용자 지정 도메인 이름을 할당할 수 있는 여러 API Management 엔드포인트가 있습니다. 현재는 다음 엔드포인트를 사용할 수 있습니다.

엔드포인트 기본값
게이트웨이 기본값은 <apim-service-name>.azure-api.net입니다. 게이트웨이는 소비 계층의 구성에 사용할 수 있는 유일한 엔드포인트입니다.

기본 게이트웨이 엔드포인트 구성은 사용자 지정 게이트웨이 도메인이 추가된 후에도 계속 사용할 수 있습니다.
개발자 포털 기본값은 <apim-service-name>.developer.azure-api.net입니다.
관리 기본값은 <apim-service-name>.management.azure-api.net입니다.
구성 API(v2) 기본값은 <apim-service-name>.configuration.azure-api.net입니다.
SCM 기본값은 <apim-service-name>.scm.azure-api.net입니다.

고려 사항

  • 서비스 계층에서 지원되는 엔드포인트를 업데이트할 수 있습니다. 일반적으로 고객은 게이트웨이(이 URL은 API Management를 통해 노출된 API를 호출하는 데 사용됨) 및 개발자 포털(개발자 포털 URL)을 업데이트합니다.
  • 기본 게이트웨이 엔드포인트는 사용자 지정 게이트웨이 도메인 이름을 구성한 후에도 사용할 수 있으며 삭제할 수 없습니다. 사용자 지정 도메인 이름으로 구성하는 다른 API Management 엔드포인트(예: 개발자 포털)의 경우 기본 엔드포인트를 더 이상 사용할 수 없습니다.
  • API Management 인스턴스 소유자만 내부적으로 관리 및 SCM 엔드포인트를 사용할 수 있습니다. 해당 엔드포인트에는 사용자 지정 도메인 이름이 자주 할당되지 않습니다.
  • 프리미엄 및 개발자 계층은 게이트웨이 엔드포인트에 대한 여러 호스트 이름 설정을 지원합니다.
  • *.contoso.com과 같은 와일드카드 도메인 이름은 소비 계층을 제외한 모든 계층에서 지원됩니다. 특정 하위 도메인 인증서(예: api.contoso.com)가 api.contoso.com 요청에 대해 와일드카드 인증서(*.contoso.com)보다 우선합니다.

도메인 인증서 옵션

API Management는 Azure Key Vault에서 가져온 사용자 지정 TLS 인증서 또는 인증서를 지원합니다. 무료 관리형 인증서를 사용하도록 설정할 수도 있습니다.

Warning

인증서 고정이 필요한 경우 기본 인증서나 무료 관리형 인증서가 아닌 사용자 지정 도메인 이름과 사용자 지정 또는 Key Vault 인증서를 사용하세요. 관리하지 않는 인증서에 대한 하드 종속성을 사용하지 않는 것이 좋습니다.

타사 공급자의 프라이빗 인증서가 이미 있는 경우 해당 인증서를 API Management 인스턴스에 업로드할 수 있습니다. 이는 다음 요구 사항을 충족해야 합니다. (API Management의 관리형 무료 인증서를 사용하도록 설정하면 이미 이러한 요구 사항을 충족합니다.)

  • PFX 파일로 내보내고 삼중 DES를 사용하여 암호화하고 선택적으로 암호로 보호합니다.
  • 최소 2048비트 개인 키 포함
  • 인증서 체인의 모든 중간 인증서와 루트 인증서를 포함합니다.

사용자 지정 도메인 이름 설정 - 포털

사용하려는 도메인 인증서에 따라 단계를 선택합니다.

  1. Azure Portal에서 API Management 인스턴스로 이동합니다.
  2. 왼쪽 탐색 영역에서 사용자 지정 도메인을 선택합니다.
  3. +추가를 선택하거나 업데이트하려는 기존 엔드포인트를 선택합니다.
  4. 오른쪽 창에서 사용자 지정 도메인의 엔드포인트 유형을 선택합니다.
  5. 호스트 이름 필드에서 사용할 이름을 지정합니다. 예: api.contoso.com.
  6. 인증서에서 사용자 지정 선택
  7. 인증서 파일을 선택하여 인증서를 선택하고 업로드합니다.
  8. 유효한 .PFX 파일을 업로드하고 인증서가 암호로 보호되는 경우 해당 암호를 제공합니다.
  9. 게이트웨이 엔드포인트를 구성할 때 클라이언트 인증서 협상 또는 기본 SSL 바인딩을 포함하여 필요에 따라 다른 옵션을 선택하거나 선택 취소합니다. 사용자 지정 인증서로 게이트웨이 도메인 구성
  10. 추가를 선택하거나 기존 엔드포인트에 대한 업데이트를 선택합니다.
  11. 저장을 선택합니다.

DNS 구성

  • 사용자 지정 도메인에 대한 CNAME 레코드를 구성합니다.
  • API Management의 무료 관리형 인증서를 사용하는 경우 도메인 소유권을 설정하도록 TXT 레코드도 구성합니다.

참고 항목

무료 인증서는 DigiCert에서 발급됩니다. 일부 도메인의 경우 0 issue digicert.com 값으로 CAA 도메인 레코드를 만들어 DigiCert를 인증서 발급자로 명시적으로 허용해야 합니다.

CNAME 레코드

사용자 지정 도메인 이름(예: api.contoso.com)에서 API Management 서비스 호스트 이름(예: <apim-service-name>.azure-api.net)으로 가리키는 CNAME 레코드를 구성합니다. IP 주소가 변경되는 경우 CNAME 레코드는 A 레코드보다 더 안정적입니다. 자세한 내용은 Azure API Management의 IP 주소 및 API Management FAQ를 참조하세요.

참고 항목

일부 도메인 등록자는 www.contoso.com과 같은 CNAME 레코드를 사용할 때만 하위 도메인 매핑을 허용하고 contoso.com과 같은 루트 이름은 허용하지 않습니다. CNAME 레코드에 관한 자세한 내용은 등록자가 제공하는 설명서 또는 IETF 도메인 이름 - 구현 및 사양을 참조하세요.

주의

무료 관리형 인증서를 사용하고 DNS 공급자를 사용하여 CNAME 레코드를 구성하는 경우 기본 API Management 서비스 호스트 이름(<apim-service-name>.azure-api.net)으로 확인해야 합니다. 현재 API Management는 CNAME 레코드가 기본 API Management 호스트 이름으로 확인하지 않으면 인증서를 자동으로 갱신하지 않습니다. 예를 들어 관리형 무료 인증서를 사용하고 Cloudflare를 DNS 공급자로 사용하는 경우 CNAME 레코드에서 DNS 프록시가 사용하도록 설정되지 않았는지 확인합니다.

TXT 레코드

API Management에 대한 무료 관리형 인증서를 사용하도록 설정하는 경우 DNS 영역에서 TXT 레코드를 구성하여 도메인 이름의 소유권을 설정합니다.

  • 레코드의 이름은 apimuid 접두사가 붙은 사용자 지정 도메인 이름입니다. 예: apimuid.api.contoso.com
  • 값은 API Management 인스턴스에서 제공하는 도메인 소유권 식별자입니다.

포털을 사용하여 사용자 지정 도메인에 대해 무료 관리형 인증서를 구성하면 필요한 TXT 레코드의 이름과 값이 자동으로 표시됩니다.

도메인 소유권 식별자 가져오기 REST API를 호출하여 도메인 소유권 식별자를 가져올 수도 있습니다.

API Management 프록시 서버가 TLS 핸드셰이크에서 SSL 인증서로 응답하는 방법

게이트웨이 엔드포인트에 대한 사용자 지정 도메인을 구성할 때 클라이언트 요청에 따라 API Management가 서버 인증서로 응답하는 방법을 결정하는 추가 속성을 설정할 수 있습니다.

SNI(서버 이름 표시) 헤더를 포함하여 호출하는 클라이언트

게이트웨이 엔드포인트에 대해 구성된 사용자 지정 도메인이 하나 또는 여러 개 경우 API Management는 다음 중 하나에서 HTTPS 요청에 응답할 수 있습니다.

  • 사용자 지정 도메인(예: contoso.com)
  • 기본 도메인(예: apim-service-name.azure-api.net).

SNI 헤더의 정보에 따라 API Management는 적절한 서버 인증서로 응답합니다.

SNI 헤더 없이 호출하는 클라이언트

SNI 헤더를 보내지 않는 클라이언트를 사용하는 경우 API Management는 다음 논리에 따라 응답을 만듭니다.

  • 서비스에 게이트웨이에 대해 구성된 사용자 지정 도메인이 하나만 있는 경우 기본 인증서는 게이트웨이의 사용자 지정 도메인에 발급된 인증서입니다.

  • 서비스에 게이트웨이에 대해 구성된 사용자 지정 도메인이 여러 개 있는 경우(개발자 및 프리미엄 계층에서 지원됨)defaultSslBinding 속성을 true로 설정("defaultSslBinding":"true")하여 기본 인증서를 지정할 수 있습니다. 포털에서 기본 SSL 바인딩 확인란을 선택합니다.

    속성을 설정하지 않으면 기본 인증서는 *.azure-api.net에서 호스트되는 기본 게이트웨이 도메인에 발급된 인증서입니다.

대용량 페이로드를 사용하여 PUT/POST 요청에 대한 지원

API Management 프록시 서버는 HTTPS에서 클라이언트 쪽 인증서를 사용하는 경우 대용량 페이로드(> 40KB)로 요청을 지원합니다. 서버의 요청이 중단되지 않도록 하려면 게이트웨이 호스트 이름에서 negotiateClientCertificate 속성을 true로 설정("negotiateClientCertificate": "true")할 수 있습니다. 포털에서 클라이언트 인증서 협상 확인란을 선택합니다.

속성이 true로 설정된 경우 모든 HTTP 요청 교환 전에 클라이언트 인증서가 SSL/TLS 연결 시 요청됩니다. 설정은 게이트웨이 호스트 이름 수준에서 적용되므로 모든 연결 요청은 클라이언트 인증서를 요청합니다. 이 제한을 해결하고 게이트웨이에 대해 최대 20개의 사용자 지정 도메인을 구성할 수 있습니다(프리미엄 계층에서만 지원됨).

다음 단계

서비스 업그레이드 및 크기 조정