Azure API Management의 구독
적용 대상: 모든 API Management 계층
Azure API Management에서 구독은 API 소비자가 API Management 인스턴스를 통해 게시된 API에 액세스하는 가장 일반적인 방법입니다. 이 문서는 개념에 대한 개요를 제공합니다.
참고 항목
API Management 구독은 특히 구독 키를 사용하여 API Management 통해 API를 호출하는 데 사용됩니다. Azure 구독과 같지 않습니다.
구독이란?
API Management를 통해 API를 게시하면 구독 키를 사용하여 API 액세스를 쉽게 보호할 수 있습니다. 게시된 API를 사용해야 하는 개발자는 해당 API를 호출할 때 HTTP 요청에 유효한 구독 키를 포함해야 합니다. 유효한 구독 키가 없으면 호출은 다음을 수행합니다.
- API Management 게이트웨이에서 즉시 거부됩니다.
- 백 엔드 서비스로 전달되지 않습니다.
API에 액세스하려면 개발자는 구독과 구독 키가 필요합니다. 구독은 구독 키 쌍의 이름을 지정한 컨테이너입니다.
또한,
- 개발자는 API 게시자의 승인 없이 구독을 받을 수 있습니다.
- API 게시자는 API 소비자를 위해 직접 구독을 만들 수도 있습니다.
구독 키 관리
정기적으로 키를 재생성하는 것은 일반적인 보안 예방 조치입니다. 구독 키가 필요한 대부분의 Azure 서비스와 마찬가지로 API Management는 키를 쌍으로 생성합니다. 서비스를 사용하는 각 애플리케이션은 키 A에서 키 B로 전환하고 최소한의 중단으로 키 A를 재생성할 수 있으며 그 반대의 경우도 마찬가지입니다.
Azure API Management 구독 - Azure REST API 만들기 또는 업데이트를 호출함으로써 특정 키를 다시 생성할 필요 없이 설정할 수 있습니다. 특히 properties.primaryKey 및/또는 properties.secondaryKey은(는) HTTP 요청 본문에서 설정해야 합니다.
참고 항목
- API Management는 만료 날짜 설정 또는 키 자동 순환과 같은 구독 키의 수명 주기를 관리하는 기본 제공 기능을 제공하지 않습니다. Azure PowerShell 또는 Azure SDK와 같은 도구를 사용하여 이러한 프로세스를 자동화하는 워크플로를 개발할 수 있습니다.
- API에 대해 시간이 제한되는 액세스를 적용하기 위해 API 게시자는 구독 키와 함께 정책을 사용하거나 토큰 기반 인증과 같은 기본 제공 만료를 제공하는 메커니즘을 사용할 수 있습니다.
구독 범위
구독은 다양한 범위, 즉 제품, 모든 API 또는 개별 API와 연결할 수 있습니다.
제품에 대한 범위
일반적으로 API Management의 구독은 단일 제품 범위와 연결되어 있습니다. 개발자:
- 개발자 포털에서 제품 목록을 찾았다고 가정해 보겠습니다.
- 사용할 제품에 대한 구독 요청을 제출했습니다.
- 해당 구독의 키(자동 또는 API 게시자 승인)를 사용하여 제품의 모든 API에 액세스합니다.
현재 개발자 포털에는 사용자 프로필 섹션에서 제품 범위 구독만 표시됩니다.
모든 API 또는 개별 API에 대한 구독
다음 중 하나에 대한 액세스 권한을 부여하는 키를 만들 수도 있습니다.
- 단일 API 또는
- API Management 인스턴스 내의 모든 API.
이러한 경우 먼저 제품을 만들고 API를 추가할 필요가 없습니다.
모든 액세스 구독
각 API Management 인스턴스는 모든 API에 대한 액세스 권한을 부여하는 기본 제공 전체 액세스 구독과 함께 제공됩니다. 서비스 범위 구독을 사용하면 서비스 소유자가 테스트 콘솔 내에서 쉽게 API를 테스트하고 디버그할 수 있습니다.
Warning
모든 액세스 구독을 사용하면 API Management 인스턴스의 모든 API에 액세스할 수 있으며 권한 있는 사용자만 사용해야 합니다. 일상적인 API 액세스에 이 구독을 사용하거나 클라이언트 앱에 모든 액세스 구독 키를 포함하면 안 됩니다.
참고 항목
API 범위 구독, 모든 API 구독 또는 기본 제공 전체 액세스 구독을 사용하는 경우 제품 범위에서 구성된 정책은 해당 구독의 요청에 적용되지 않습니다.
독립 실행형 구독
또한 API Management는 개발자 계정과 연결되지 않은 독립형 구독을 허용합니다. 이 기능은 구독을 공유하는 여러 개발자 또는 팀과 유사한 시나리오에서 유용합니다.
소유자를 지정하지 않고 구독을 만들면 독립 실행형 구독이 됩니다. 개발자와 나머지 팀에 독립 실행형 구독 키에 대한 액세스 권한을 부여하려면 다음 중 하나를 수행합니다.
- 구독 키를 수동으로 공유합니다.
- 사용자 지정 시스템을 사용하여 팀에서 구독 키를 사용할 수 있도록 합니다.
Azure Portal에서 구독 만들기 및 관리
API 게시자는 Azure Portal에서 직접 구독을 만들 수 있습니다.
포털에서 만든 구독은 활성 상태이므로 구독자는 유효한 구독 키를 사용하여 연결된 API를 호출할 수 있습니다. 필요에 따라 구독의 상태를 변경할 수 있습니다. 예를 들어 API 액세스를 방지하기 위해 모든 구독(기본 제공 전체 액세스 구독 포함)을 일시 중단, 취소 또는 삭제할 수 있습니다.
구독 키 사용
구독자는 다음 두 가지 방법 중 하나로 API Management 구독 키를 사용할 수 있습니다.
요청에 Ocp-Apim-Subscription-Key HTTP 헤더를 추가하여 유효한 구독 키의 값을 전달합니다.
구독 키 쿼리 매개 변수와 유효한 값을 URL에 포함합니다. 쿼리 매개 변수는 헤더가 없는 경우에만 확인됩니다.
팁
Ocp-Apim-Subscription-Key는 구독 키 헤더의 기본 이름이며 subscription-key는 쿼리 매개 변수의 기본 이름입니다. 원하는 경우 각 API에 대한 설정에서 이러한 이름을 수정할 수 있습니다. 예를 들어 포털에서 API의 설정 탭에서 이러한 이름을 업데이트합니다.
참고 항목
구독 키가 요청 헤더 또는 쿼리 매개 변수에 포함된 경우 구독 키는 기본적으로 백 엔드에 전달되며 백 엔드 모니터링 로그 또는 기타 시스템에 노출될 수 있습니다. 중요한 데이터로 간주되는 경우 inbound 섹션의 끝에 정책을 구성하여 구독 키 헤더(set-header) 또는 쿼리 매개 변수(set-query-parameter)를 제거할 수 있습니다.
API 또는 제품 액세스에 대한 구독 요구 사항 사용 또는 사용 안 함
기본적으로 API를 만들 때 API 액세스에는 구독 키가 필요합니다. 마찬가지로 제품을 만들 때 제품에 추가된 API에 액세스하려면 기본적으로 구독 키가 필요합니다. 특정 시나리오에서 API 게시자는 구독 요구 사항 없이 제품 또는 특정 API를 대중에게 게시하기를 원할 수 있습니다. 게시자가 특정 API에 대한 보호되지 않은(익명) 액세스를 사용하도록 설정하도록 선택할 수 있지만 클라이언트 액세스를 보호하기 위해 다른 메커니즘을 구성하는 것이 좋습니다.
주의
구독이 필요하지 않은 제품 또는 API를 구성할 때는 주의합니다. 이 구성은 지나치게 관대할 수 있으며 API를 특정 API 보안 위협에 더 취약하게 만들 수 있습니다.
참고 항목
열려 있는 제품은 구독 필요 설정이 사용하지 않도록 설정되어 있으므로 사용자가 구독할 필요가 없습니다. 따라서 열려 있는 제품은 개발자 포털의 제품 페이지에 표시되지 않습니다.
API 또는 제품을 만들 때 또는 나중에 구독 요구 사항을 사용하지 않도록 설정할 수 있습니다.
포털을 사용하여 구독 요구 사항을 사용하지 않도록 설정하려면:
- 제품 요구 사항 사용 안 함 - 제품의 설정 페이지에서 구독 필요를 사용하지 않도록 설정합니다.
- API 요구 사항 사용 안 함 - API의 설정 페이지에서 구독 필요를 사용하지 않도록 설정합니다.
구독 요구 사항이 사용하지 않도록 설정되면 구독 키 없이 선택한 API에 액세스할 수 있습니다.
API Management에서 구독 키가 있거나 없는 요청을 처리하는 방법
구독 키가 있는 API 요청
API Management는 구독 키가 있는 클라이언트의 API 요청을 받으면 다음 규칙에 따라 요청을 처리합니다.
활성 구독과 연결된 유효한 키인지 먼저 확인합니다.
- API로 범위가 지정된 구독
- API에 할당된 제품으로 범위가 지정된 구독
- 모든 API로 범위가 지정된 구독
- 서비스 범위 구독(기본 제공 모든 액세스 구독)
해당하는 범위의 활성 구독에 대한 유효한 키가 제공되면 액세스가 허용됩니다. 정책은 해당 범위의 정책 정의 구성에 따라 적용됩니다.
키가 유효하지 않지만 API를 포함하지만 구독( 개방형 제품)이 필요하지 않은 제품이 있는 경우 키를 무시하고 구독 키 없이 API 요청으로 처리합니다(아래 참조).
그렇지 않으면 액세스가 거부됩니다(401 액세스 거부 오류).
구독 키가 없는 API 요청
API Management는 구독 키가 없는 클라이언트로부터 API 요청을 받으면 다음 규칙에 따라 요청을 처리합니다.
- API를 포함하지만 구독이 필요하지 않은 제품(공개 제품)이 있는지 먼저 확인합니다. 열려 있는 제품이 있는 경우 열린 제품에 대해 구성된 API, 정책 및 액세스 규칙의 컨텍스트에서 요청을 처리합니다. API는 최대 하나의 공개 제품과 연결할 수 있습니다.
- API가 포함된 공개 제품이 없으면 API에 구독이 필요한지 확인합니다. 구독이 필요하지 않은 경우 해당 API 및 작업의 컨텍스트에서 요청을 처리합니다.
- 구성된 제품 또는 API가 없으면 액세스가 거부됩니다(401 액세스 거부 오류).
요약표
다음 표에서는 게이트웨이가 다양한 시나리오에서 구독 키가 있거나 없는 API 요청을 처리하는 방법을 요약합니다. 의도하지 않은 익명 API 액세스를 가능하게 할 수 있는 구성이 명시되어 있습니다.
| API에 할당된 모든 제품에 구독 필요 | API에 구독 필요 | 구독 키가 있는 API 호출 | 구독 키가 없는 API 호출 | 일반적인 시나리오 |
|---|---|---|---|---|
| ✔️ | ✔️ | 액세스 허용: • 제품 범위 키 • API 범위 키 • 모든 API 범위 키 • 서비스 범위 키 액세스 거부됨: • 적용 가능한 제품 또는 API로 범위가 지정되지 않은 기타 키 |
액세스 거부됨 | 제품 범위 또는 API 범위 구독을 사용하여 보호된 API 액세스 |
| ✔️ | ❌ | 액세스 허용: • 제품 범위 키 • API 범위 키 • 모든 API 범위 키 • 서비스 범위 키 • 적용 가능한 제품 또는 API로 범위가 지정되지 않은 기타 키 |
액세스 허용(API 컨텍스트) | • 제품 범위 구독을 사용하여 보호된 API 액세스 • API에 대한 익명 액세스. 익명 액세스가 의도되지 않은 경우 인증 및 권한 부여를 적용하도록 API 수준 정책을 구성합니다. |
| ❌1 | ✔️ | 액세스 허용: • 제품 범위 키 • API 범위 키 • 모든 API 범위 키 • 서비스 범위 키 액세스 거부됨: • 적용 가능한 제품 또는 API로 범위가 지정되지 않은 기타 키 |
액세스 허용(공개 제품 컨텍스트) | • API 범위 구독을 사용하여 보호된 API 액세스 • API에 대한 익명 액세스. 익명 액세스가 의도되지 않은 경우 인증 및 권한 부여를 적용하도록 제품 정책으로 구성합니다. |
| ❌1 | ❌ | 액세스 허용: • 제품 범위 키 • API 범위 키 • 모든 API 범위 키 • 서비스 범위 키 • 적용 가능한 제품 또는 API로 범위가 지정되지 않은 기타 키 |
액세스 허용(공개 제품 컨텍스트) | API에 대한 익명 액세스. 익명 액세스가 의도되지 않은 경우 인증 및 권한 부여를 적용하도록 제품 정책으로 구성합니다. |
1 API와 연결된 공개 제품이 있습니다.
고려 사항
- 제품 컨텍스트의 API 액세스는 제품이 게시되었는지 여부에 관계없이 동일합니다. 제품 게시를 취소하면 개발자 포털에서 숨겨지지만 새 구독 또는 기존 구독 키는 무효화되지 않습니다.
- API에 구독 인증이 필요하지 않은 경우 구독 키를 포함하는 모든 API 요청은 구독 키가 없는 요청과 동일하게 처리됩니다. 구독 키가 무시됩니다.
- API 액세스 “컨텍스트”는 특정 범위(예: API 또는 제품)에 적용되는 정책 및 액세스 제어를 의미합니다.
다음 단계
API Management에 대한 자세한 내용 확인: