Azure Maps 인증

아티클
03/11/2024

Azure Maps는 요청을 인증하는 세 가지 방법, 즉 공유 키 인증, Microsoft Entra ID 인증 및 SAS(공유 액세스 서명) 토큰 인증을 지원합니다. 이 문서에서는 Azure Maps 서비스의 구현을 안내하는 데 도움이 되는 인증 방법을 설명합니다. 또한 이 문서에서는 Azure Policy 및 CORS(원본 간 리소스 공유)에 대한 로컬 인증을 사용하지 않도록 설정하는 것과 같은 기타 계정 컨트롤에 대해서도 설명합니다.

참고 항목

Azure Maps와의 보안 통신을 개선하기 위해 이제 TLS(전송 계층 보안) 1.2를 지원하고 TLS 1.0 및 1.1에 대한 지원을 중단하고 있습니다. 현재 TLS 1.x를 사용하는 경우 TLS 1.2 준비 상태를 평가하고 TLS 1.0 문제 해결에 설명된 테스트를 사용하여 마이그레이션 계획을 수립하세요.

공유 키 인증

Azure Portal에서 키를 보는 방법에 대한 자세한 내용은 인증 세부 정보 보기를 참조하세요.

Azure Maps 계정이 만들어진 후 기본 및 보조 키가 생성됩니다. 공유 키 인증을 사용한 Azure Maps를 호출할 때 기본 키를 구독 키로 사용하는 것이 좋습니다. 공유 키 인증은 Azure Maps 계정에서 생성한 키를 Azure Maps 서비스로 전달합니다. Azure Maps 서비스에 요청할 때마다 ‘구독 키’를 URL에 매개 변수로 추가해야 합니다. 키 롤링 변경 등의 시나리오에서 보조 키를 사용할 수 있습니다.

URL에서 구독 키를 매개 변수로 사용하는 예제:

https://atlas.microsoft.com/map/tile?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2024-04-01&tilesetId=microsoft.base.road&zoom=15&x=5236&y=12665&tileSize=256

Important

기본 키와 보조 키는 중요한 데이터로 취급되어야 합니다. 공유 키는 모든 Azure Maps REST API를 인증하는 데 사용됩니다. 공유 키를 사용하는 사용자는 API 키를 중앙에서 관리될 수 있는 환경 변수 또는 보안 비밀 저장소를 통해 추상화해야 합니다.

Microsoft Entra 인증

Azure 구독은 세분화된 액세스 제어를 사용할 수 있도록 Microsoft Entra 테넌트와 함께 제공됩니다. Azure Maps는 Microsoft Entra ID를 사용하여 Azure Maps 서비스에 대한 인증을 제공합니다. Microsoft Entra ID는 Microsoft Entra 테넌트에 등록된 사용자 및 애플리케이션에 대한 ID 기반 인증을 제공합니다.

Azure Maps는 Azure Maps 계정을 포함하고 있는 Azure 구독과 연결된 Microsoft Entra 테넌트에 대한 OAuth 2.0 액세스 토큰을 허용합니다. Azure Maps는 다음에 대한 토큰을 허용합니다.

Microsoft Entra 사용자
사용자가 위임한 권한을 사용하는 파트너 애플리케이션
Azure 리소스에 대한 관리 ID

Azure Maps는 각 Azure Maps 계정에 대해 고유 식별자(클라이언트 ID)를 생성합니다. 이 클라이언트 ID를 다른 매개 변수와 결합하면 Microsoft Entra ID에서 토큰을 요청할 수 있습니다.

Microsoft Entra ID를 구성하고 Azure Maps에 대한 토큰을 요청하는 방법에 대한 자세한 내용은 Azure Maps의 인증 관리를 참조하세요.

Microsoft Entra ID를 사용하여 인증하는 방법에 대한 일반 정보는 인증 및 권한 부여를 참조하세요.

Azure 리소스 및 Azure Maps에 대한 관리형 ID

Azure 리소스에 대한 관리 ID는 Microsoft Entra ID를 사용하여 인증할 수 있는 자동 관리형 애플리케이션을 기반으로 하는 보안 주체를 Azure 서비스에 제공합니다. Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하면 관리 ID 보안 주체에 Azure Maps 서비스에 액세스할 수 있는 권한을 부여할 수 있습니다. 관리 ID의 몇 가지 예는 Azure App Service, Azure Functions 및 Azure Virtual Machines입니다. 관리 ID 목록은 관리 ID를 사용하여 다른 서비스에 액세스할 수 있는 Azure 서비스를 참조하세요. 관리 ID에 대한 자세한 내용은 Azure Maps의 인증 관리를 참조하세요.

애플리케이션 Microsoft Entra 인증 구성

애플리케이션은 Microsoft Entra ID에서 제공하는 하나 이상의 시나리오를 사용하는 Microsoft Entra 테넌트로 인증합니다. 각 Microsoft Entra 애플리케이션 시나리오는 비즈니스에서 요구하는 바에 따라 다양한 요구 사항을 나타냅니다. 일부 애플리케이션에는 사용자 로그인 경험이 필요할 수 있으며, 다른 애플리케이션에는 애플리케이션 로그인 경험이 필요할 수 있습니다. 자세한 내용은 인증 흐름 및 애플리케이션 시나리오를 참조하세요.

애플리케이션이 액세스 토큰을 받은 후 SDK 및/또는 애플리케이션은 다른 REST API HTTP 헤더 외에도 다음과 같은 필수 HTTP 헤더 집합을 사용하여 HTTPS 요청을 보냅니다.

헤더 이름	값
x-ms-client-id	30d7cc…9f55
Authorization	Bearer eyJ0e…HNIVN

참고 항목

x-ms-client-id는 Azure Maps 인증 페이지에 표시되는 Azure Maps 계정 기반 GUID입니다.

Microsoft Entra ID OAuth 전달자 토큰을 사용하는 Azure Maps 경로 요청의 예는 다음과 같습니다.

GET /route/directions/json?api-version=1.0&query=52.50931,13.42936:52.50274,13.43872
Host: atlas.microsoft.com
x-ms-client-id: 30d7cc….9f55
Authorization: Bearer eyJ0e…HNIVN

클라이언트 ID를 보는 방법에 대한 내용은 인증 세부 정보 보기를 참조하세요.

팁

프로그래밍 방식으로 클라이언트 ID 가져오기

PowerShell을 사용하는 경우 클라이언트 ID는 IMapsAccount 개체의 UniqueId 속성으로 저장됩니다. Get-AzMapsAccount를 사용하여 이 속성을 검색합니다. 예를 들면 다음과 같습니다.

$maps = Get-AzMapsAccount -Name {Azure-Maps_Account-Name} -ResourceGroupName {Resource-Group-Name} -SubscriptionId {SubscriptionId}
$ClientId = $maps.UniqueId

Azure CLI를 사용하는 경우 --query 매개 변수와 함께 az maps account show 명령을 사용합니다. 예를 들면 다음과 같습니다.

$ClientId = az maps account show --name {Azure-Maps_Account-Name} --resource-group {Resource-Group-Name} --subscription {SubscriptionId} --query properties.uniqueId

역할 기반 액세스 제어를 사용하는 권한 부여

필수 조건

Azure RBAC에 익숙하지 않은 경우 Azure RBAC(역할 기반 액세스 제어) 개요를 참조하세요. 보안 주체 유형에는 역할 정의라고도 하는 사용 권한 세트가 부여됩니다. 역할 정의는 REST API 작업에 대한 권한을 제공합니다. Azure Maps는 개별 Microsoft Entra 사용자, 그룹, 애플리케이션, Azure 리소스 및 Azure 관리 ID를 포함하여 Azure RBAC(Azure 역할 기반 액세스 제어)의 모든 보안 주체 유형에 대한 액세스를 지원합니다. 하나 이상의 Azure Maps 계정에 대한 액세스를 적용하는 것을 범위라고 합니다. 보안 주체, 역할 정의 및 범위를 적용하는 경우 역할 할당이 만들어집니다.

개요

다음 섹션에서는 Azure RBAC와 Azure Maps 통합의 개념 및 구성 요소에 대해 설명합니다. Azure Maps 계정을 설정하는 프로세스의 일부로, Microsoft Entra 디렉터리는 Azure Maps 계정이 있는 Azure 구독에 연결됩니다.

Azure RBAC를 구성하는 경우 보안 주체를 선택하여 역할 할당에 적용합니다. Azure Portal에서 역할 할당을 추가하는 방법을 알아보려면 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

역할 정의 선택

애플리케이션 시나리오를 지원하기 위해 다음과 같은 역할 정의 형식이 있습니다.

Azure 역할 정의	설명
Azure Maps 검색 및 렌더링 데이터 읽기 권한자	기본 웹 브라우저 사용 사례에 대한 액세스를 제한하기 위해 Azure Maps REST API만 검색하고 렌더링할 수 있는 액세스를 제공합니다.
Azure Maps 데이터 읽기 권한자	변경할 수 없는 Azure Maps REST API에 대한 액세스를 제공합니다.
Azure Maps Data Contributor	변경 가능한 Azure Maps REST API에 대한 액세스를 제공합니다. 쓰기 및 삭제 작업으로 정의되는 가변성.
Azure Maps 데이터 읽기 및 Batch 역할	이 역할은 Azure Maps에서 읽기 및 일괄 처리 작업을 할당하는 데 사용할 수 있습니다.
사용자 지정 역할 정의	Azure Maps REST API에 제한된 액세스를 유연성 있게 사용할 수 있도록 하는 특수 역할을 만듭니다.

일부 Azure Maps 서비스에는 Azure Maps REST API에 대한 쓰기 또는 삭제 작업을 수행하기 위해 상승된 권한이 필요할 수 있습니다. 쓰기 또는 삭제 작업을 제공하는 서비스에는 Azure Maps 데이터 기여자 역할이 필요합니다. 다음 표에서는 쓰기 또는 삭제 작업을 사용하는 경우에 적용할 수 있는 Azure Maps Data Contributor 서비스에 대해 설명합니다. 읽기 작업만 필요한 경우 Azure Maps 데이터 기여자 역할 대신 Azure Maps 데이터 읽기 권한자 역할을 사용할 수 있습니다.

Azure Maps 서비스	Azure Maps 역할 정의
Creator(사용되지 않음¹)	Azure Maps Data Contributor
공간(사용되지 않음¹)	Azure Maps Data Contributor
Batch 검색 및 경로	Azure Maps Data Contributor

¹ Azure Maps Creator 및 데이터 레지스트리 및 공간 서비스는 이제 더 이상 사용되지 않으며 2025년 9월 30일에 사용 중지됩니다.

Azure RBAC 설정을 보는 방법에 대한 내용은 Azure Maps에 대한 Azure RBAC 구성 방법을 참조하세요.

사용자 지정 역할 정의

애플리케이션 보안의 한 측면은 최소 권한의 원칙, 즉 현재 작업에 필요한 권한으로 액세스 권한을 제한하는 사례입니다. 액세스 권한을 제한하려면 액세스 제어를 더욱 세분화해야 하는 사용 사례를 지원하는 사용자 지정 역할 정의를 만들면 됩니다. 사용자 지정 역할 정의를 만들려면 정의에 포함하거나 제외할 특정 데이터 작업을 선택합니다.

그런 다음 사용자 지정 역할 정의를 모든 보안 주체에 대한 역할 할당에 사용할 수 있습니다. Azure 사용자 지정 역할 정의에 대한 자세한 정보는 Azure 사용자 지정 역할을 참조하세요.

사용자 지정 역할이 애플리케이션 보안을 향상시킬 수 있는 몇 가지 예제 시나리오는 다음과 같습니다.

시나리오	사용자 지정 역할 데이터 작업
기본 지도 타일과 다른 REST API가 없는 퍼블릭 연결 또는 대화형 로그인 웹 페이지입니다.	`Microsoft.Maps/accounts/services/render/read`
역방향 지오코딩만 필요하고 다른 REST API는 필요하지 않은 애플리케이션입니다.	`Microsoft.Maps/accounts/services/search/read`
Azure Maps Creator 기반 지도 데이터 및 기본 지도 타일 REST API의 읽기를 요청하는 보안 주체에 대한 역할입니다.	`Microsoft.Maps/accounts/services/data/read`: `Microsoft.Maps/accounts/services/render/read`
Creator 기반 지도 데이터를 읽고, 쓰고, 삭제해야 하는 보안 주체에 대한 역할입니다. 기본 지도 타일과 같은 다른 REST API에 대한 액세스를 허용하지 않는 맵 데이터 편집자 역할로 정의됩니다.

범위 이해

역할 할당을 만들 때 Azure 리소스 계층 구조 내에서 정의됩니다. 계층의 맨 위는 관리 그룹이고, 가장 낮은 계층은 Azure Maps 계정과 같은 Azure 리소스입니다. 리소스 그룹에 역할 할당을 할당하면 그룹의 여러 Azure Maps 계정 또는 리소스에 대한 액세스를 설정할 수 있습니다.

팁

Microsoft의 일반적인 권장 사항은 Azure Maps 계정 범위에 대한 액세스 권한을 할당하는 것입니다. 동일한 Azure 구독에 존재하는 다른 Azure Maps 계정에 대해 의도하지 않은 액세스를 차단하기 때문입니다.

로컬 인증 사용 안 함

Azure Maps 계정은 disableLocalAuth라는 Microsoft.Maps/accounts에 대한 Management API의 표준 Azure 속성을 지원합니다. true인 경우 Microsoft Entra 인증을 제외한 Azure Maps 데이터 평면 REST API에 대한 모든 인증이 비활성됩니다. Azure Policy를 사용하여 공유 키 및 SAS 토큰의 배포와 관리를 제어하도록 구성됩니다. 자세한 내용은 Azure Policy란?을 참조하세요.

로컬 인증을 사용하지 않도록 설정해도 즉시 적용되지는 않습니다. 서비스에서 향후 인증 요청을 차단하는 데 몇 분 정도 걸립니다. 로컬 인증을 다시 사용하도록 설정하려면 속성을 false로 설정하세요. 그러면 로컬 인증이 몇 분 후 다시 시작됩니다.

{
  // omitted other properties for brevity.
  "properties": {
    "disableLocalAuth": true
  }
}

공유 액세스 서명 토큰 인증

SAS(공유 액세스 서명) 토큰은 JWT(JSON 웹 토큰) 형식을 사용하여 만든 인증 토큰이며 Azure Maps REST API에 애플리케이션에 대한 인증을 증명하기 위해 암호화 서명됩니다. Azure 구독의 Azure Maps 계정과 사용자 할당 관리 ID를 통합하여 만들어진 SAS 토큰입니다. 사용자가 할당한 관리 ID에는 기본 제공 또는 사용자 지정 역할 정의 중 하나를 사용하여 Azure RBAC를 통해 Azure Maps 계정에 대한 권한이 부여됩니다.

Microsoft Entra 액세스 토큰과 SAS 토큰의 주요 기능 차이:

최대 만료 기간은 1일(24시간)인 토큰의 수명입니다.
토큰당 Azure 위치 및 지리 액세스 제어
초당 약 1~500개 요청의 토큰당 속도 제한
토큰의 프라이빗 키는 Azure Maps 계정 리소스의 기본 및 보조 키입니다.
권한 부여를 위한 서비스 주체 개체는 사용자가 할당한 관리 ID에 의해 제공됩니다.

SAS 토큰은 변경할 수 없습니다. 즉, 토큰이 만들어지면 만료일까지 SAS 토큰이 유효하며 허용된 지역, 속도 제한 및 사용자가 할당한 관리 ID의 구성을 변경할 수 없습니다. SAS 토큰 해지 및 액세스 제어 변경 내용에 대한 자세한 정보는 액세스 제어 이해를 참조하세요.

SAS 토큰 속도 제한 이해

SAS 토큰 최대 속도 제한은 Azure Maps 리소스에 대한 청구를 제어할 수 있습니다.

토큰에 최대 속도 제한(maxRatePerSecond)을 지정하면 계정에 초과 요금이 청구되지 않아 토큰을 사용할 때 계정에 대한 청구 가능 트랜잭션의 상한을 설정할 수 있습니다. 그러나 애플리케이션은 해당 제한에 도달하면 모든 트랜잭션에 대해 429 (TooManyRequests)가 포함된 클라이언트 오류 응답을 받습니다. SAS 토큰의 다시 시도와 배포를 관리하는 것은 애플리케이션에서 처리합니다. 계정에 대해 만들 수 있는 SAS 토큰 수에는 제한이 없습니다. 기존 토큰 한도의 증가 또는 감소를 허용하기 위해 새 SAS 토큰을 생성해야 합니다. 이전 SAS 토큰은 만료될 때까지 계속 유효합니다.

예상 사례:

초당 대략 최대 속도	초당 실제 속도	속도 지속 기간(초)	총 청구 가능 트랜잭션
10	20	600	6,000

실제 속도 제한은 일정 기간 내에 일관성을 적용하는 Azure Maps 기능에 따라 다릅니다. 그러나 이를 통해 청구 비용을 예방적으로 컨트롤할 수 있습니다.

속도 제한은 전역적 또는 지리적으로 적용되지 않고 Azure 위치별로 적용됩니다.

예를 들어 maxRatePerSecond가 10인 단일 SAS 토큰을 사용하여 East US 위치의 처리량을 제한할 수 있습니다. West US 2에서 동일한 토큰을 사용하는 경우 East US 위치와 독립적으로 해당 위치에서 처리량을 10으로 제한하는 새 카운터가 만들어집니다. 비용을 제어하고 예측 가능성을 향상하려면 다음을 수행하는 것이 좋습니다.

대상 지리에 대해 허용된 Azure 위치가 지정된 SAS 토큰을 만듭니다. 계속 읽으면서 SAS 토큰을 만드는 방법을 이해합니다.
지리적 데이터 평면 REST API 엔드포인트인 https://us.atlas.microsoft.com 또는 https://eu.atlas.microsoft.com을 사용합니다.

엔드포인트 https://us.atlas.microsoft.com가 Azure Maps 서비스가 호스트되는 동일한 미국 위치로 라우팅되는 애플리케이션 토폴로지(예: East US, West Central US 또는 West US 2)를 생각해 보세요. 동일한 아이디어가 West Europe과 North Europe 사이의 https://eu.atlas.microsoft.com와 같은 다른 지리적 엔드포인트에 적용됩니다. 예기치 않은 권한 부여 거부를 방지하려면 애플리케이션에서 사용하는 것과 동일한 Azure 위치를 사용하는 SAS 토큰을 사용합니다. 엔드포인트 위치는 Azure Maps 관리 REST API를 사용하여 정의됩니다.

기본 속도 제한은 SAS 토큰 속도 제한보다 우선합니다.

Azure Maps 속도 제한에 설명된 대로 개별 서비스 제품에는 계정의 집계로 적용되는 다양한 속도 제한이 있습니다.

다음 테이블에 대한 QPS(초당 쿼리 수)가 250개로 제한되는 Search Service - 비 Batch 역방향의 경우를 고려해 보세요. 각 테이블은 예제 사용량에서 성공한 총 예상 트랜잭션을 나타냅니다.

첫 번째 표에는 초당 최대 요청이 500개인 1개의 토큰이 표시되고, 애플리케이션의 실제 사용량은 60초 동안 초당 500개의 요청이었습니다. Search Service - 비 Batch 역방향의 속도 제한은 250입니다. 60초 동안 총 30,000개 요청이 수행된다는 것을 의미하며 이러한 요청 중 15,000개는 청구 가능한 트랜잭션입니다. 나머지 요청의 결과는 상태 코드 429 (TooManyRequests)입니다.

이름	초당 대략 최대 속도	초당 실제 속도	속도 지속 기간(초)	성공한 대략적인 총 트랜잭션
token	500	500	60	~15,000

예를 들어 두 개의 SAS 토큰이 만들어지고 Azure Maps 계정과 동일한 위치를 사용하는 경우 각 토큰은 이제 기본 속도 제한인 250 QPS를 공유합니다. 각 토큰이 동일한 처리량으로 동시에 사용되는 경우 토큰 1과 토큰 2는 각각 7,500개의 성공적인 트랜잭션을 부여합니다.

이름	초당 대략 최대 속도	초당 실제 속도	속도 지속 기간(초)	성공한 대략적인 총 트랜잭션
토큰 1	250	250	60	~7500
토큰 2	250	250	60	~7500

SAS 토큰 액세스 제어 이해

SAS 토큰은 RBAC를 사용하여 REST API에 대한 액세스를 제어합니다. SAS 토큰을 만들 때 Map 계정의 필수 구성 요소인 관리 ID에는 특정 REST API 작업에 대한 액세스 권한을 부여하는 Azure RBAC 역할이 할당됩니다. 애플리케이션이 허용하는 API를 결정하려면 역할 정의 선택을 참조하세요.

SAS 토큰이 만료되기 전에 임시 액세스 권한을 할당하고 액세스 권한을 제거하려면 토큰을 철회합니다. 액세스를 철회하는 다른 이유로는 토큰이 의도치 않게 Azure Maps Data Contributor 역할 할당을 사용하여 배포되고 SAS 토큰을 가진 모든 사용자가 Azure Maps REST API에 데이터를 읽고 쓸 수 있어 중요한 데이터 노출 또는 사용량으로 인한 예상치 못한 재정적 비용이 발생하는 경우일 수 있습니다.

SAS 토큰에 대한 액세스를 철회하는 두 가지 옵션이 있습니다.

맵 계정의 SAS 토큰 또는 secondaryKey에서 사용한 키를 다시 생성합니다.
연결된 맵 계정에서 관리 ID에 대한 역할 할당을 제거합니다.

Warning

SAS 토큰에서 사용하는 관리 ID를 삭제하거나 관리 ID의 액세스 제어를 취소하면 SAS 토큰 및 관리 ID를 사용하는 애플리케이션 인스턴스가 Azure Maps REST API에서 의도적으로 401 Unauthorized 또는 403 Forbidden을 반환하여 애플리케이션 중단이 발생합니다.

중단을 방지하려면 다음을 수행합니다.

Map 계정에 두 번째 관리 ID를 추가하고 새 관리 ID에 올바른 역할 할당을 부여합니다.
secondaryKey 또는 이전 관리 ID와 다른 관리 ID를 signingKey로 사용하여 SAS 토큰을 만들고 새 SAS 토큰을 애플리케이션에 배포합니다.
기본 키를 다시 생성하고, 계정에서 관리 ID를 제거하고, 관리 ID에 대한 역할 할당을 제거합니다.

SAS 토큰 만들기

SAS 토큰을 만들려면 Azure 구독에서 Azure Maps 계정 및 사용자가 할당한 ID를 모두 관리하는 Contributor 역할 액세스 권한이 있어야 합니다.

Important

global Azure 위치에서 만든 기존 Azure Maps 계정은 관리 ID를 지원하지 않습니다.

먼저 Azure Maps 계정과 동일한 위치에 사용자가 할당한 관리 ID를 만들어야 합니다.

팁

관리 ID와 Azure Maps 계정 모두에 대해 동일한 위치를 사용해야 합니다.

관리 ID가 만들어지면 Azure Maps 계정을 만들거나 업데이트하고 연결할 수 있습니다. 자세한 내용은 Azure Maps 계정 관리를 참조하세요.

계정이 성공적으로 만들어지거나 관리 ID로 업데이트된 후 계정 범위의 Azure Maps 데이터 역할에 관리 ID에 대한 역할 기반 액세스 제어를 할당합니다. 이렇게 하면 관리 ID에 맵 계정에 Azure Maps REST API에 대한 액세스 권한을 부여할 수 있습니다.

다음으로 Azure 관리 SDK 도구, 계정 관리 API에서 SAS 작업 나열 또는 Map 계정 리소스의 Azure Portal 공유 액세스 서명 페이지를 사용하여 SAS 토큰을 만듭니다.

SAS 토큰 매개 변수:

매개 변수 이름	예제 값	설명
signingKey	`primaryKey`	필수 요소로, signingKey에 대한 문자열 열거형 값 `primaryKey`, `secondaryKey` 또는 관리 ID가 SAS의 서명을 만드는 데 사용됩니다.
principalId	`<GUID>`	필수 요소이며 principalId는 맵 계정에 연결된 사용자가 할당한 관리 ID의 개체(보안 주체) ID입니다.
지역	`[ "eastus", "westus2", "westcentralus" ]`	선택 사항이며 기본값은 `null`입니다. 지역은 Azure Maps REST 데이터 평면 API에서 SAS 토큰을 사용할 수 있는 지역을 제어합니다. 지역 매개 변수를 생략하면 SAS 토큰을 아무런 제약 조건 없이 사용할 수 있습니다. `us.atlas.microsoft.com` 및 `eu.atlas.microsoft.com`과 같은 Azure Maps 데이터 평면 지리적 엔드포인트와 함께 사용할 경우 애플리케이션이 지정된 지리적 위치 내에서 사용량을 제어할 수 있습니다. 이렇게 하면 다른 지역에서의 사용을 방지할 수 있습니다.
maxRatePerSecond	500	필수 요소로 SAS 토큰이 부여되는 초당 지정된 대략적 최대 요청입니다. 한도에 도달하면 HTTP 상태 코드 `429 (TooManyRequests)`를 사용하여 추가 처리량의 속도가 제한됩니다.
start	`2021-05-24T10:42:03.1567373Z`	필수 요소로 토큰이 활성화되는 날짜 및 시간을 지정하는 UTC 날짜입니다.
만료	`2021-05-24T11:42:03.1567373Z`	필수 요소로 토큰이 만료되는 날짜 및 시간을 지정하는 UTC 날짜입니다. 시작과 만료 사이의 기간은 24시간을 초과할 수 없습니다.

SAS 토큰을 사용하여 애플리케이션 구성

애플리케이션이 SAS 토큰을 받은 후 Azure Maps SDK 및/또는 애플리케이션은 다른 REST API HTTP 헤더 외에도 다음과 같은 필수 HTTP 헤더를 사용하여 HTTPS 요청을 보냅니다.

헤더 이름	값
Authorization	jwt-sas eyJ0e….HNIVN

참고 항목

jwt-sas는 SAS 토큰을 사용하여 나타내는 인증 체계입니다. x-ms-client-id나 다른 권한 부여 헤더 또는 subscription-key 쿼리 문자열 매개 변수를 포함하지 마세요.

CORS는 특정 도메인에서 실행되는 웹 애플리케이션이 다른 도메인의 자원에 액세스할 수 있도록 하는 HTTP 프로토콜입니다. 웹 브라우저는 웹 페이지가 다른 도메인의 API를 호출할 수 없도록 하는 동일 원본 정책이라는 보안 제한을 구현합니다. CORS는 특정 도메인(원본 도메인)에서 다른 도메인의 API를 호출할 수 있는 안전한 방법을 제공합니다. Azure Maps 계정 리소스를 사용하여 애플리케이션에서 Azure Maps REST API에 액세스할 수 있는 원본을 구성할 수 있습니다.

Important

CORS는 권한 부여 메커니즘이 아닙니다. CORS를 사용하는 경우 REST API를 사용하여 Map 계정에 만드는 모든 요청에는 공유 키, Microsoft Entra ID 또는 SAS 토큰과 같은 유효한 맵 계정 인증 체계도 필요합니다.

CORS는 모든 맵 계정 가격 책정 계층, 데이터 평면 엔드포인트 및 위치에 대해 지원됩니다.

필수 조건

클라이언트에서 악의적인 코드가 실행되는 것을 방지하기 위해 최신 브라우저는 웹 애플리케이션의 요청을 별도의 도메인에서 실행되는 리소스로 차단합니다.

CORS에 익숙하지 않은 경우 CORS(원본 간 리소스 공유)를 참조하세요. CORS를 사용하면 Azure Maps 계정의 엔드포인트를 호출할 수 있는 원본을 Access-Control-Allow-Origin 헤더에서 선언할 수 있습니다. CORS 프로토콜은 Azure Maps에 국한되지 않습니다.

CORS 요청

원본 도메인의 CORS 요청은 두 가지 개별 요청으로 구성될 수 있습니다.

서비스에서 적용하는 CORS 제한을 쿼리하는 실행 전 요청. 요청이 표준 메서드 GET, HEAD, POST 또는 Authorization 요청 헤더를 포함하는 요청이 아니면 실행 전 요청이 필요합니다.
원하는 자원에 대해 수행될 실제 요청

실행 전 요청

실행 전 요청은 서버가 실제 요청에서 전송될 메서드와 헤더를 이해하고 서버가 요청의 원본을 알고 신뢰하도록 하는 보안 조치일 뿐만 아니라 맵 계정에 대해 설정된 CORS 제한 사항도 쿼리합니다. 웹 브라우저 또는 기타 사용자 에이전트는 요청 헤더, 메서드 및 원본 도메인이 포함된 OPTIONS 요청을 보냅니다. 맵 계정 서비스는 CORS 실행 전 프로토콜을 통해 계정 인증이 가능한 경우 CORS 규칙을 가져오려고 시도합니다.

인증이 불가능한 경우 Maps 서비스는 Maps 서비스에 대한 실제 요청에 대해 지정할 수 있는 원본 도메인, 요청 메서드 및 요청 헤더를 지정하는 미리 구성된 CORS 규칙 집합을 평가합니다. 기본적으로 Maps 계정은 모든 원본이 웹 브라우저에 원활하게 통합할 수 있도록 구성됩니다.

다음 기준이 충족되면 서비스는 필수 Access-Control 헤더를 사용하여 실행 전 요청에 응답합니다.

OPTIONS 요청에는 필수 CORS 헤더(Origin 및 Access-Control-Request-Method 헤더)가 포함됩니다.
인증이 성공했으며 실행 전 요청과 일치하는 계정에 대해 CORS 규칙이 사용하도록 설정되었습니다.
실행 전 요청에서 지정할 수 없는 필수 Authorization 요청 헤더로 인해 인증을 건너뛰었습니다.

실행 전 요청이 성공하면 서비스는 상태 코드 200 (OK)로 응답하고 응답에 필수 Access-Control 헤더를 포함합니다.

다음 조건이 발생하는 경우 서비스는 실행 전 요청을 거부합니다.

OPTIONS 요청에 필수 CORS 헤더(Origin 및 Access-Control-Request-Method 헤더)가 없으면 서비스는 400 (Bad request) 상태 코드로 응답합니다.
실행 전 요청에서 인증이 성공했고 실행 전 요청과 일치하는 CORS 규칙이 없는 경우 서비스는 상태 코드 403 (Forbidden)으로 응답합니다. 이 상태 코드는 CORS 규칙이 현재 브라우저 클라이언트 원본 요청 헤더와 일치하지 않는 원본을 허용하도록 구성된 경우에 발생할 수 있습니다.

참고 항목

요청한 자원이 아닌 서비스에 대해 실행 전 요청을 평가합니다. 계정 소유자가 적절한 계정 속성을 설정하여 CORS를 사용하도록 설정해야 요청이 성공합니다.

실제 요청

실행 전 요청이 수락되고 응답이 반환되면 브라우저는 맵 서비스에 대한 실제 요청을 전달합니다. 실행 전 요청이 거부되면 브라우저는 실제 요청을 즉시 거부합니다.

실제 요청은 맵 서비스에 대한 일반 요청으로 처리됩니다. Origin 헤더가 있다는 것은 요청이 CORS 요청이고 서비스가 CORS 규칙에 대해 유효성을 검사함을 나타냅니다. 일치하는 규칙이 있으면 Access-Control 헤더가 응답에 추가되어 클라이언트로 다시 전송됩니다. 일치하는 항목이 없으면 응답은 CORS 원본 오류를 나타내는 403 (Forbidden)을 반환합니다.

CORS 정책 사용

맵 계정이 만들어지거나 업데이트되면 해당 속성은 구성이 허용되는 원본을 지정합니다. Azure Maps Management SDK, Azure Maps Management REST API 및 포털을 통해 Azure Maps 계정 속성에 CORS 규칙을 설정할 수 있습니다. 서비스에 대해 CORS 규칙을 설정하고 나면 다른 도메인에서 해당 서비스에 대해 수행하는 적절하게 권한이 부여된 요청을 평가하여 지정된 규칙에 따라 해당 요청이 허용되는지 여부를 결정합니다. 예시:

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
    "cors": {
      "corsRules": [
        {
          "allowedOrigins": [
            "https://www.azure.com",
            "https://www.microsoft.com"
          ]
        }
      ]
    }
  }
}

허용되는 원본 목록을 가진 하나의 CORS 규칙만 지정할 수 있습니다. 각 원본을 사용하면 지정된 원본의 웹 브라우저에서 Azure Maps REST API에 대한 HTTP 요청을 만들 수 있습니다.

CORS 정책 제거

CORS를 제거할 수 있습니다.

Azure Portal에서 수동으로
프로그래밍 방식으로 다음을 사용합니다.
- Azure Maps SDK
- Azure Maps 관리 REST API
- ARM 템플릿

팁

Azure Maps 관리 REST API를 사용하는 경우 요청 본문에 빈 corsRule 목록과 함께 PUT 또는 PATCH를 사용합니다.

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
        "cors": {
          "corsRules": []
        }
    }
  }
}

청구 트랜잭션 이해

Azure Maps는 다음 상태 코드에 대해서는 청구 트랜잭션을 계산하지 않습니다.

5xx HTTP 상태 코드
401(권한 없음)
403(사용할 수 없음)
408(시간 초과)
429(TooManyRequests)
CORS 실행 전 요청

청구 트랜잭션 및 기타 Azure Maps 가격 책정 정보에 대한 자세한 내용은 Azure Maps 가격 책정을 참조하세요.

다음 단계

보안 모범 사례에 대한 자세한 내용은 다음을 참조하세요.

인증 및 권한 부여 모범 사례

Microsoft Entra ID와 Azure Maps를 통한 애플리케이션 인증 방법에 대한 자세한 내용은 다음을 참조하세요.

Azure Maps의 인증 관리

Microsoft Entra ID를 사용하여 Azure Maps Control을 인증하는 방법에 대한 자세한 내용은 다음을 참조하세요.

Azure Maps 맵 컨트롤 사용

다음을 통해 공유

Azure Maps 인증

공유 키 인증

Microsoft Entra 인증

Azure 리소스 및 Azure Maps에 대한 관리형 ID

애플리케이션 Microsoft Entra 인증 구성

역할 기반 액세스 제어를 사용하는 권한 부여

필수 조건

개요

역할 정의 선택

사용자 지정 역할 정의

범위 이해

로컬 인증 사용 안 함

공유 액세스 서명 토큰 인증

SAS 토큰 속도 제한 이해

SAS 토큰 최대 속도 제한은 Azure Maps 리소스에 대한 청구를 제어할 수 있습니다.

속도 제한은 전역적 또는 지리적으로 적용되지 않고 Azure 위치별로 적용됩니다.

기본 속도 제한은 SAS 토큰 속도 제한보다 우선합니다.

SAS 토큰 액세스 제어 이해

SAS 토큰 만들기

SAS 토큰을 사용하여 애플리케이션 구성

필수 조건

CORS 요청

실행 전 요청

실제 요청

CORS 정책 사용

CORS 정책 제거

청구 트랜잭션 이해

다음 단계

피드백

추가 리소스

다음을 통해 공유

Azure Maps 인증

공유 키 인증

Microsoft Entra 인증

Azure 리소스 및 Azure Maps에 대한 관리형 ID

애플리케이션 Microsoft Entra 인증 구성

역할 기반 액세스 제어를 사용하는 권한 부여

필수 조건

개요

역할 정의 선택

사용자 지정 역할 정의

범위 이해

로컬 인증 사용 안 함

공유 액세스 서명 토큰 인증

SAS 토큰 속도 제한 이해

SAS 토큰 최대 속도 제한은 Azure Maps 리소스에 대한 청구를 제어할 수 있습니다.

속도 제한은 전역적 또는 지리적으로 적용되지 않고 Azure 위치별로 적용됩니다.

기본 속도 제한은 SAS 토큰 속도 제한보다 우선합니다.

SAS 토큰 액세스 제어 이해

SAS 토큰 만들기

SAS 토큰을 사용하여 애플리케이션 구성

CORS(크로스-원본 자원 공유)

필수 조건

CORS 요청

실행 전 요청

실제 요청

CORS 정책 사용

CORS 정책 제거

청구 트랜잭션 이해

다음 단계

피드백

추가 리소스