Microsoft Azure Data Manager for Energy API를 보안 API 게이트웨이에 게시
Azure API Management는 클라이언트 애플리케이션과 백 엔드 API 간의 중요한 매개자 역할을 합니다. 기술적 세부 사항을 숨기고 조직에 API 보안에 대한 제어권을 부여함으로써 클라이언트가 서비스에 더 쉽게 액세스할 수 있도록 해줍니다.
Azure API Management를 통해 Azure Data Manager for Energy API를 게시하면 프라이빗 트래픽에 대한 Azure Data Manager for Energy Private Link 기능을 사용하고 인스턴스에 대한 직접적인 공용 액세스를 완전히 제거할 수 있습니다.
이 문서에서는 Azure Data Manager for Energy API를 보호하기 위해 Azure API Management를 설정하는 방법을 설명합니다.
필수 조건
이 연습을 완료하려면 다음 구성 요소, 도구 및 정보가 필요합니다.
두 개의 서브넷을 사용할 수 있는 가상 네트워크. 하나는 Azure Data Manager for Energy 프라이빗 엔드포인트용이고 다른 하나는 Azure API Management 가상 네트워크 주입용입니다.
서브넷에 배포된 프라이빗 링크로 구성된 Azure Data Manager for Energy.
Azure API Management는 가상 네트워크 주입을 사용하여 가상 네트워크에 프로비전 및 배포됩니다. 외부 모드를 선택하거나 내부 모드에 대한 기타 옵션 섹션을 참조하세요.
코드 편집기(예: Visual Studio Code). 게시되는 각 API에 대한 Azure Data Manager for Energy OpenAPI 사양을 수정합니다.
adme-samples GitHub 리포지토리에서 Azure Data Manager for Energy OpenAPI 사양을 다운로드합니다. rest-apis 디렉터리로 이동하여 애플리케이션에 적절한 버전을 선택합니다.
프로비전 시 사용된 Azure Data Manager for Energy 앱의 앱 등록에서 테넌트 ID 및 클라이언트 ID를 기록해 둡니다.
API Management 인스턴스 준비
Azure API Management 인스턴스의 구성을 변경하려면 다음 단계를 따릅니다.
모든 리소스 창에서 이 연습에 사용되는 Azure API Management 인스턴스를 선택합니다.
API 설정 그룹에서 선택하여 제품 설정 페이지로 이동합니다.
제품 페이지에서 추가 단추을 선택하여 새 제품을 만듭니다. Azure API Management 제품을 사용하면 함께 관리할 수 있는 느슨하게 결합된 API 그룹을 만들 수 있습니다. Azure Data Manager for Energy API에 대한 제품을 만듭니다.
제품 추가 페이지에서 다음 표에 설명된 값을 입력하여 제품을 만듭니다.
설정 값 표시 이름 "Azure Data Manager for Energy 제품" ID "adme-product" 설명 어떤 API를 그룹화하는지 개발자에게 알려 주는 설명 입력 게시된 날짜 이 상자를 선택하여 만든 제품 게시 구독 필요 이 확인란을 선택하여 API에 대한 기본 권한 부여 제공 승인 필요 경우에 따라 관리자가 이 제품에 대한 구독 시도를 검토하고 허용하거나 거부하도록 하려면 선택합니다. 선택하지 않으면 구독 시도가 자동으로 승인됩니다. 구독 수 제한 필요하다면 여러 동시 구독의 수를 제한합니다. 약관 선택적으로 구독자가 제품을 사용하기 위해 동의해야 하는 제품 사용 약관을 정의합니다. API 이 기능은 무시할 수 있습니다. 이 문서의 뒷부분에서 API를 연결합니다. 만들기를 선택하여 새 제품을 만듭니다.
제품 만들기가 완료되면 포털에서 제품 페이지로 돌아갑니다. 새로 만들어진 제품인 Azure Data Manager for Energy Product를 선택하여 제품 리소스 페이지로 이동합니다. 설정 메뉴에서 정책 설정 메뉴 항목을 선택합니다.
인바운드 처리 창에서 제품 정책을 수정할 수 있는 </> 아이콘을 선택합니다. 솔루션의 보안을 강화하기 위해 세 가지 정책 집합을 추가합니다.
- API 게이트웨이에서 인증되지 않은 요청이 catch되도록 Entra ID 토큰 유효성 검사
- 요청 속도와 총 요청/전송된 데이터를 제어하기 위한 할당량 및 속도 제한
- 백 엔드 API에서 반환한 헤더를 제거하려면 헤더 설정(이로 인해 잠재적인 악의적인 작업자에게 중요한 세부 정보가 노출될 수 있음)
inbound 태그 내 및 base 태그 아래 구성에 다음 validate-azure-ad-token 정책을 추가합니다. 필수 구성 요소에 명시된 Microsoft Entra ID 앱 세부 정보로 템플릿을 업데이트합니다.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>validate-azure-ad-token 정책 아래에 다음 할당량 및 비율 제한 정책을 추가합니다. 소비자에 맞게 정책 구성 값을 업데이트합니다.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />정책 편집기의 outbound 섹션과 base 태그 아래에 다음 set-header 정책을 추가합니다.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />저장을 선택하여 변경 내용을 커밋합니다.
Azure Portal에서 API Management 리소스로 다시 이동합니다. 백 엔드 메뉴 항목을 선택하고 + 추가 단추를 선택합니다.
백 엔드 모달에서 다음 표에 설명된 값을 입력하여 백 엔드를 만듭니다.
설정 값 속성 "adme-backend" 설명 이 백 엔드가 Azure Data Manager for Energy API와 관련되어 있음을 개발자에게 나타내는 설명을 입력합니다. Type 사용자 지정 URL 런타임 URL Azure Data Manager for Energy URI _ex를 입력합니다. https://INSERT_ADME_NAME.energy.azure.com/인증서 체인 유효성 검사 선택 인증서 이름 유효성 검사 선택 
백 엔드를 만들려면 만들기를 선택합니다. 새로 만들어진 이 백 엔드는 API를 게시할 때 다음 섹션에서 사용됩니다.
Azure Data Manager for Energy 가져오기
다음 단계에서 Azure Data Manager for Energy API를 Azure API Management 게이트웨이로 가져오고 구성하고 게시합니다.
마지막 섹션에서 사용한 Azure API Management 인스턴스로 다시 이동합니다.
메뉴에서 API 메뉴 항목을 선택한 다음 + API 추가 단추를 선택합니다.
정의에서 만들기 제목 아래에서 OpenAPI를 선택합니다.
OpenAPI 사양에서 만들기 모달 창에서 전체 토글을 선택합니다.
필수 구성 요소의 일부로 다운로드한 OpenAPI 사양을 찾고 원하는 코드 편집기를 사용하여 스키마 사양을 엽니다. "서버"라는 단어를 검색하고 파일에 서버 URL을 적어둡니다. 예: /api/schema-service/v1/
파일 선택을 선택하고 스키마 API 사양을 선택합니다. 업로드가 완료되면 모달 창은 사양의 일부 값을 로드합니다.
다른 필드에는 다음 표에 설명된 값을 입력합니다.
설정 값 작업 템플릿에 필수 쿼리 매개 변수 포함 선택 표시 이름 앱 개발자에게 적합한 표시 이름을 입력합니다. 예: Azure Data Manager for Energy 스키마 서비스 속성 API Management는 공백을 대시로 바꾸는 방식(kebab-cased)의 이름을 제안합니다. 선택적으로 이름을 변경할 수 있지만 인스턴스에 대해 고유해야 합니다. 설명 OpenAPI 사양은 설명을 정의할 수 있으며, 정의된 경우 설명이 자동으로 채워집니다. 선택적으로 사용 사례에 따라 설명을 업데이트합니다. URL 구성표 "둘 다" 선택 API URL 접미사 모든 Azure Data Manager for Energy API에 대한 접미사를 입력합니다(예: adme). 그런 다음 5단계의 서버 URL을 입력합니다. 최종 값은 /adme/api/schema-service/v1/과 같아야 합니다. 접미사를 사용하면 일반적으로 Azure Data Manager for Energy API에 직접 연결되는 기존 클라이언트 및 소프트웨어 개발 키트를 준수할 수 있습니다. 태그 선택적으로 태그를 입력합니다. 제품 이전 섹션에서 만든 "Azure Data Manager for Energy" 제품을 선택합니다. Important
API URL 접미사의 유효성을 검사합니다. 이는 Azure Data Manager for Energy API를 게시할 때 오류가 발생하는 일반적인 원인입니다.
API 외관을 만들려면 만들기를 선택합니다.
API 목록에서 새로 만들어진 스키마 API 외관을 선택하고 작업 목록에서 모든 작업을 선택합니다. 인바운드 처리 창에서 </> 아이콘을 선택하여 정책 문서를 편집합니다.
API를 구성하려면 두 가지 정책 집합을 추가합니다.
- 요청을 Azure Data Manager for Energy 인스턴스로 라우팅하도록 백 엔드 서비스 설정
- URI를 다시 빌드하여 adme 접두사를 제거하고 백 엔드 API에 대한 요청을 빌드합니다. 이 정책 문은 정책 식을 사용하여 현재 작업의 URL 템플릿 값을 서버 URL에 동적으로 추가합니다.
5단계의 서버 URL을 적어둡니다. base 태그 아래의 inbound 섹션에 다음 두 정책 문을 삽입합니다.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />저장을 선택하여 변경 내용을 커밋합니다.
작업 목록에서 버전 정보 가져오기 작업을 선택하여 API를 테스트합니다. 그런 다음 테스트 탭을 선택하여 Azure API Management 테스트 콘솔로 이동합니다.
다음 표에 설명된 값을 입력합니다. Azure Data Manager for Energy에 대한 인증 토큰을 생성합니다. API를 테스트하려면 보내기를 선택합니다.
설정 값 data-partition-id Azure Data Manager for Energy 인스턴스의 데이터 파티션 ID Product 이전에 만든 Azure Data Manager for Energy 제품 선택 권한 부여 "Bearer" 및 생성한 인증 토큰 
API가 올바르게 구성되면 스크린샷과 유사한 HTTP 200 - OK 응답이 표시됩니다. 그렇지 않은 경우 문제 해결 섹션을 확인합니다.
각 Azure Data Manager for Energy API 및 관련 사양에 대해 위 단계를 반복합니다.
문제 해결
Azure API Management를 통해 API를 테스트하는 동안 오류가 발생하면 일반적으로 구성 문제를 나타냅니다. 오류에 따라 잠재적인 해결 단계를 검토합니다.
| 코드 | 오류 메시지 | 세부 정보 |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Azure Data Manager for Energy 인스턴스에 대한 Microsoft Entra ID 테넌트 및 클라이언트 앱에 대한 유효한 인증 헤더가 있는지 확인합니다. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
테스트 요청에 인증 헤더가 추가되었는지 확인합니다. |
HTTP 404 Not Found |
이 오류는 일반적으로 백 엔드 API에 대한 요청이 잘못된 URL로 이루어졌음을 의미합니다. API Management에서 API 요청을 추적하여 백 엔드 요청에 대해 생성된 URL을 파악하고 유효한지 확인합니다. 그렇지 않은 경우 url-rewrite 정책이나 백 엔드를 다시 확인합니다. | |
HTTP 500 Internal Server Error |
Internal server error |
이 오류는 일반적으로 백 엔드 API에 요청하는 문제를 반영합니다. 일반적으로 이 시나리오에서 문제는 DNS(도메인 이름 서비스)와 관련됩니다. 가상 네트워킹에 프라이빗 DNS 영역이 구성되어 있는지 또는 사용자 지정 DNS 확인에 적절한 전달자가 있는지 확인합니다. API Management에서 API 요청을 추적하여 어떤 백 엔드 요청이 이루어졌고 요청을 시도할 때 API Management가 보고하는 오류를 파악합니다. |
기타 고려 사항
API Management 내부 가상 네트워킹 모드
내부 모드는 공용 IP 주소를 통해 엔드포인트를 노출하는 대신 Azure API Management를 완전히 격리합니다. 이 구성에서 조직은 모든 Azure Data Manager for Energy가 내부인지 확인할 수 있습니다. Azure Data Manager for Energy는 파트너 및 고객과 협력하기 위한 협업 솔루션이므로 이 시나리오는 현재로서는 유용하지 않을 수 있습니다.
웹 애플리케이션 방화벽을 갖춘 App Gateway
많은 조직에서는 내부 가상 네트워크 모드만 사용하는 대신 보안 역방향 프록시 메커니즘을 적용하여 내부 모드 Azure API Management 인스턴스를 외부 파트너 및 고객에게 노출하는 방법을 선택합니다. 내부 모드 인스턴스는 프록시를 통과해야 하는 엄격하게 제어된 수신으로 완전히 격리된 상태를 유지합니다.
Azure App Gateway는 역방향 프록시로 사용되는 일반적인 서비스입니다. Azure App Gateway에는 애플리케이션 및 API의 취약성에 대한 잠재적인 공격을 적극적으로 검색하는 WAF(웹 애플리케이션 방화벽) 기능도 있습니다.
사용자 지정 도메인으로 Azure API Management 구성
이 아키텍처의 또 다른 일반적인 기능은 API에 사용자 지정 도메인을 적용하는 것입니다. Azure Data Manager for Energy는 이 기능을 지원하지 않지만 대신 Azure API Management에서 사용자 지정 도메인을 구성할 수 있습니다.
도메인에 대한 인증서가 필수 조건입니다. 그러나 Azure API Management는 사용자 지정 도메인에 대한 무료 관리 인증서 만들기를 지원합니다.