Аутентификация в Azure Maps

Статья
10/18/2023

Azure Maps поддерживает три способа проверки подлинности запросов: проверка подлинности с общим ключом, проверка подлинности идентификатора Microsoft Entra ID и проверка подлинности маркера ПОДПИСАННОГО URL-адреса (SAS). В этой статье описываются способы проверки подлинности, которые помогут пользователю выполнить реализацию служб Azure Maps. В статье также описаны другие элементы управления учетными записями, такие как отключение локальной проверки подлинности для Политика Azure и общего доступа к ресурсам между источниками (CORS).

Примечание.

Для улучшения безопасного взаимодействия с Azure Maps теперь поддерживается протокол Transport Layer Security (TLS) 1.2 и прекращается поддержка протокола TLS 1.0 и 1.1. Если в настоящее время используется TLS 1.x, оцените свою готовность к внедрению протокола TLS 1.2 и разработайте план миграции, выполнив тестирование, описание которого можно найти в статье Решение проблемы TLS 1.0.

Аутентификация на основе общего ключа

Сведения о просмотре ключей в портал Azure см. в разделе "Просмотр сведений о проверке подлинности".

Первичные и вторичные ключи генерируются после создания учетной записи 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

Внимание

Первичные и вторичные ключи следует обрабатывать как конфиденциальные данные. Общий ключ используется для проверки подлинности всех REST API Azure Maps. Пользователи, использующие общий ключ, должны извлекать ключ API либо с помощью переменных среды, либо с помощью защищенного хранилища секретов, где им можно управлять централизованно.

Проверка подлинности Microsoft Entra

Подписки Azure предоставляются клиенту Microsoft Entra для обеспечения точного контроля доступа. Azure Maps предлагает проверку подлинности для служб Azure Maps с помощью идентификатора Microsoft Entra. Идентификатор Microsoft Entra предоставляет проверку подлинности на основе удостоверений для пользователей и приложений, зарегистрированных в клиенте Microsoft Entra.

Azure Maps принимает маркеры доступа OAuth 2.0 для клиентов Microsoft Entra, связанных с подпиской Azure, содержащей учетную запись Azure Maps. Azure Maps также принимает токены для следующих субъектов.

Пользователи Microsoft Entra
Партнерские приложения, использующие разрешения, предоставляемые пользователями
Управляемые удостоверения для ресурсов Azure

Azure Maps создает уникальный идентификатор (идентификатор клиента) для каждой учетной записи Azure Maps. Маркеры можно запросить из идентификатора Microsoft Entra при объединении этого идентификатора клиента с другими параметрами.

Дополнительные сведения о настройке идентификатора Microsoft Entra и маркеров запроса для Azure Maps см. в статье "Управление проверкой подлинности в Azure Maps".

Общие сведения о проверке подлинности с помощью идентификатора Microsoft Entra см. в разделе "Проверка подлинности и авторизация".

Управляемые удостоверения для ресурсов Azure и Azure Maps

Управляемые удостоверения для ресурсов Azure предоставляют службам Azure автоматически управляемый субъект безопасности на основе приложений, который может проходить проверку подлинности с помощью идентификатора Microsoft Entra. С помощью управления доступом на основе ролей Azure (Azure RBAC) субъект безопасности с управляемым удостоверением может пройти проверку подлинности для получения доступа к службам Azure Maps. Некоторые примеры управляемых удостоверений: служба приложений Azure, функции Azure и виртуальные машины Azure. Список управляемых удостоверений см . в службах Azure, которые могут использовать управляемые удостоверения для доступа к другим службам. Дополнительные сведения об управляемых удостоверениях см. в статье "Управление проверкой подлинности в Azure Maps".

Настройка проверки подлинности Microsoft Entra приложения

Приложения проходят проверку подлинности с помощью клиента Microsoft Entra с помощью одного или нескольких поддерживаемых сценариев, предоставляемых идентификатором Microsoft Entra. Каждый сценарий приложения Microsoft Entra представляет различные требования в зависимости от бизнес-потребностей. Для некоторых приложений может потребоваться вход пользователя в систему, а для других приложений может потребоваться вход в приложение. Дополнительные сведения см. в статье Потоки проверки подлинности и сценарии для приложений.

После того, как приложение получает токен доступа, пакет SDK и/или приложение отправляет HTTPS-запрос со следующим набором необходимых HTTP-заголовков в дополнение к другим HTTP-заголовкам REST API.

Имя заголовка	Значение
x-ms-client-id	30d7cc... 9f55
Авторизация	Носителя eyJ0e... HNIVN

Примечание.

x-ms-client-id — это GUID Azure Maps на основе учетных записей, который отображается на странице проверки подлинности службы Azure Maps.

Ниже приведен пример запроса маршрута Azure Maps, использующего токен носителя OAuth идентификатора Microsoft Entra:

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

Сведения о просмотре идентификатора клиента см. в разделе Просмотр сведений об аутентификации.

Совет

Программное получение идентификатора клиента

При использовании PowerShell идентификатор клиента сохраняется как свойство UniqueId в объекте IMapsAccount. Это свойство извлекается с помощью команды Get-AzMapsAccount, например:

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

При использовании Azure CLI используйте команду az maps account show с параметром --query, например:

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

Проверка подлинности с управлением доступом на основе ролей

Необходимые компоненты

Если вы не знакомы с Azure RBAC, обзор управления доступом на основе ролей Azure (Azure RBAC) предоставляет набор разрешений, также известный как определение роли. Определение роли предоставляет разрешения на выполнение действий REST API. Azure Maps поддерживает доступ ко всем типам субъектов для управления доступом на основе ролей Azure (Azure RBAC), включая отдельных пользователей Microsoft Entra, групп, приложений, ресурсов Azure и управляемых удостоверений Azure. Предоставление доступа к одной или нескольким учетным записям Azure Maps определяет область. Назначение роли создается при применении субъекта, определения роли и области.

Обзор

В следующих разделах обсуждаются основные понятия и компоненты интеграции Azure Maps с Azure RBAC. В рамках процесса настройки учетной записи Azure Maps каталог Microsoft Entra связан с подпиской Azure, которой находится учетная запись Azure Maps.

При настройке Azure RBAC выбирается субъект безопасности и для него назначается роль. Сведения о добавлении назначений ролей в портал Azure см. в статье "Назначение ролей Azure с помощью портал Azure".

Выбор определения роли

Для поддержки сценариев приложений доступны следующие типы определений ролей.

Определение роли Azure	Description
Читатель данных поиска и преобразования для просмотра в Azure Maps	Предоставляет доступ только для поиска и преобразования для просмотра в интерфейсах REST API Azure Maps, чтобы ограничить доступ базовыми возможностями использования веб-браузера.
Читатель данных Azure Maps	Предоставляет доступ к неизменяемым интерфейсам REST API для Azure Maps.
Разработчик данных Azure Maps	Предоставляет доступ к изменяемым интерфейсам REST API для Azure Maps. Мутируемость, определяемая действиями: запись и удаление.
Роль чтения и пакетной службы Azure Maps	Эту роль можно использовать для назначения действий чтения и пакетной обработки в Azure Maps.
Определения пользовательской роли	Создайте пользовательскую роль, чтобы обеспечить гибкий ограниченный доступ к интерфейсам REST API для Azure Maps.

Некоторым службам Azure Maps может потребоваться более высокий уровень привилегий для выполнения записи или удаления при использовании интерфейсом REST API для Azure Maps. Роль разработчика данных Azure Maps требуется для служб, которые предоставляют возможность выполнения записи или удаления. В следующей таблице описано, для каких служб применима роль разработчика данных Azure Maps, когда выполняется запись или удаление. Если требуются только операции чтения, можно использовать роль Azure Maps "Читатель данных" вместо роли "Разработчик данных Azure Maps".

Служба Azure Maps	Определение роли Azure Maps
Создатель (не рекомендуется¹)	Разработчик данных Azure Maps
Пространственный (не рекомендуется¹)	Разработчик данных Azure Maps
Пакетные поиск и прокладка маршрута	Разработчик данных Azure Maps

¹ Azure Maps Creator, а реестр данных и пространственные службы теперь устарели и будут прекращены 9.30.25.

Сведения о просмотре параметров Azure RBAC см. в статье Конфигурация Azure RBAC для Azure Maps.

Определения пользовательских ролей

Одним из аспектов безопасности приложений является принцип наименьшей привилегии, практика ограничения прав доступа к правам, необходимым для текущего задания. Ограничение прав доступа осуществляется путем создания определений пользовательских ролей, поддерживающих варианты использования, требующие дополнительной детализации для управления доступом. Чтобы создать определение пользовательской роли, выберите определенные действия с данными, которые требуется включить или исключить из определения.

Затем пользовательское определение роли можно использовать в назначении ролей для любого субъекта безопасности. Дополнительные сведения об определениях пользовательских ролей 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`
Роль для субъекта безопасности, который запрашивает чтение, запись и удаление данных карты Azure Maps Creator. Определяется как роль редактора данных карты, которая не разрешает доступ к другим REST API, таким как плитки базовой карты.	`Microsoft.Maps/accounts/services/data/read`, , `Microsoft.Maps/accounts/services/data/writeMicrosoft.Maps/accounts/services/data/delete`

Общие сведения об области

При создании назначения ролей он определяется в иерархии ресурсов Azure. Верхняя часть иерархии — это группа управления, а самый низкий — ресурс Azure, например учетная запись Azure Maps. Назначение роли для группы ресурсов может обеспечить доступ к нескольким учетным записям Azure Maps или ресурсам в группе.

Совет

Общая рекомендация Майкрософт заключается в том, что нужно назначить доступ к области учетной записи Azure Maps, поскольку это предотвращает непреднамеренный доступ к другим учетным записям Azure Maps, существующим в той же подписке Azure.

Отключение локальной проверки подлинности

Учетные записи Azure Maps поддерживают стандартное свойство Azure в API управления для Microsoft.Maps/accounts вызова disableLocalAuth. Когда trueвсе проверки подлинности в REST API уровня данных Azure Maps отключены, за исключением проверки подлинности Microsoft Entra. Это настраивается с помощью Политики Azure для распространения общих ключей и маркеров SAS и управления ими. Дополнительные сведения см. в статье Что такое служба "Политика Azure".

Отключение локальной проверки подлинности не вступает в силу немедленно. Подождите несколько минут, пока служба не начнет блокировать будущие запросы проверки подлинности. Чтобы повторно включить локальную проверку подлинности, задайте для свойства false и после нескольких минут возобновление локальной проверки подлинности.

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

Аутентификация с помощью маркера SAS

Маркеры подписанного URL-адреса (SAS) — это маркеры проверки подлинности, созданные с помощью формата JSON Web token (JWT) и криптографически подписанные для подтверждения подлинности приложения для REST API Azure Maps. Маркер SAS, созданный путем интеграции управляемого удостоверения, назначаемого пользователем, с учетной записью Azure Maps в подписке Azure. Управляемое удостоверение, назначаемое пользователем, получает авторизацию учетной записи Azure Maps через Azure RBAC с помощью встроенных или настраиваемых определений ролей.

Функциональные отличия маркера SAS от маркеров доступа Microsoft Entra:

Время существования маркера для максимального истечения срока действия в один день (24 часа).
Управление доступом к расположению и географии Azure на уровне маркеров.
Ограничение скорости на маркер приблизительно от 1 до 500 запросов в секунду.
Закрытые ключи маркера являются первичными и вторичными ключами ресурса учетной записи Azure Maps.
Объект субъекта-службы для авторизации предоставляется управляемым удостоверением, назначаемым пользователем.

Маркеры SAS являются неизменяемыми. Это означает, что после создания маркера маркер SAS действителен до истечения срока действия, а конфигурация разрешенных регионов, ограничений скорости и управляемого удостоверения, назначаемого пользователем, нельзя изменить. Дополнительные сведения об отзыве маркера SAS и изменениях в управлении доступом см. ниже в разделе об управлении доступом.

Общие сведения об ограничениях скорости для маркеров SAS

Ограничение максимальной скорости маркера SAS помогает контролировать размер оплаты за ресурс Azure Maps

При указании максимального ограничения скорости для токена (maxRatePerSecond) избыточные тарифы не выставляются учетной записи, что позволяет задать верхний предел выставленных счетов транзакций для учетной записи при использовании маркера. Однако приложение получает ответы об ошибках клиента со 429 (TooManyRequests) всеми транзакциями после достижения этого ограничения. Это ответственность за приложение для управления повторными попытками и распределением маркеров SAS. Нет ограничений на количество маркеров SAS для учетной записи. Разрешение увеличения или уменьшения ограничения существующего маркера; Необходимо создать новый маркер SAS. Старый маркер SAS по-прежнему действителен до истечения срока действия.

Пример расчета:

Приблизительная максимальная скорость в секунду	Фактическая скорость в секунду	Продолжительность устойчивой скорости в секундах	Всего оплачиваемых транзакций
10	20	600	6000

Фактические ограничения скорости зависят от способности Azure Maps обеспечить согласованность в течение определенного времени. Однако это позволяет осуществлять превентивное управление размером счетов.

Ограничения скорости применяются для каждого расположения Azure, а не глобально или географически

Например, для ограничения пропускной способности в расположении East US можно использовать один маркер SAS с параметром maxRatePerSecond равным 10. Если этот же маркер используется в West US 2, в этом расположении создается новый счетчик для ограничения пропускной способности в 10, независимо от расположения East US. Для управления затратами и повышения предсказуемости рекомендуется выполнить следующее.

Создайте маркеры SAS с назначенными разрешенными расположениями Azure для целевого географического региона. Продолжите чтение стать, чтобы узнать, как создавать маркеры 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. Та же идея применяется к другим географическим конечным точкам, таким как https://eu.atlas.microsoft.com между West Europe и North Europe. Чтобы предотвратить непредвиденные отказы в авторизации, используйте маркер SAS, использующий те же расположения Azure, что и приложение. Расположение конечной точки определяется с помощью REST API управления Azure Maps.

Ограничения скорости по умолчанию имеют приоритет над ограничениями скорости маркеров SAS

Как описано в ограничениях скорости Azure Maps, отдельные предложения служб имеют различные ограничения скорости, которые применяются в качестве агрегата учетной записи.

Рассмотрим случай служба — обратный запрос, отличный от пакетной службы, с ограничением в 250 запросов в секунду (QPS) для следующих таблиц. Каждая таблица представляет оценочное общее количество успешных транзакций, полученное из примера использования.

В первой таблице показан один маркер, имеющий максимальный запрос в секунду 500, а фактическое использование приложения составляет 500 запросов в секунду в течение 60 секунд. служба — обратный запрос, отличный от пакетной службы, имеет ограничение скорости 250, то есть всего 30 000 запросов, сделанных в течение 60 секунд; 15 000 из этих запросов являются оплачиваемыми транзакциями. Остальные запросы приводят к коду 429 (TooManyRequests)состояния.

Имя.	Приблизительная максимальная скорость в секунду	Фактическая скорость в секунду	Продолжительность устойчивой скорости в секундах	Приблизительное общее число успешных транзакций
token	500	500	60	~15 000

Например, если два маркера SAS создаются и используют то же расположение, что и учетная запись Azure Maps, тогда каждый маркер использует ограничение скорости по умолчанию — 250 QPS. Если каждый маркер используется одновременно с одной и той же пропускной способностью, маркерам 1 и 2 будет успешно предоставляться 7500 транзакций.

Имя.	Приблизительная максимальная скорость в секунду	Фактическая скорость в секунду	Продолжительность устойчивой скорости в секундах	Приблизительное общее число успешных транзакций
маркер 1	250	250	60	~7500
маркер 2	250	250	60	~7500

Общие сведения об управлении доступом с помощью маркеров SAS

Маркеры SAS используют RBAC для управления доступом к REST API. При создании маркера SAS необходимое управляемое удостоверение в учетной записи карты назначается роль Azure RBAC, которая предоставляет доступ к определенным действиям REST API. См . раздел "Выбор определения роли", чтобы определить, какие API разрешено приложению.

Если вы хотите назначить временный доступ и удалить доступ до истечения срока действия маркера SAS, отмените маркер. Другие причины отзыва доступа могут быть, если маркер распространяется с Azure Maps Data Contributor назначением ролей непреднамеренно, и любой пользователь с маркером SAS может иметь возможность считывать и записывать данные в REST API Azure Maps, которые могут предоставлять конфиденциальные данные или непредвиденные финансовые затраты от использования.

Существует два варианта отзыва доступа к маркерам SAS:

Повторно создайте ключ, который использовался маркером SAS или дополнительным ключом учетной записи карты.
Удалите назначение роли для управляемого удостоверения в связанной учетной записи карты.

Предупреждение

Удаление управляемого удостоверения, используемого маркером SAS, или отмена контроля доступа управляемого удостоверения приведет к тому, что экземпляры приложения, использующие маркер SAS и управляемое удостоверение? будут намеренно возвращать 401 Unauthorized или 403 Forbidden из REST API Azure Maps, что приведет к нарушению работы приложения.

Чтобы избежать сбоев, сделайте следующее.

Добавьте второе управляемое удостоверение в учетную запись Maps и предоставьте новому управляемому удостоверению правильное назначение ролей.
Создайте маркер SAS с помощью secondaryKeyуправляемого удостоверения или другого управляемого удостоверения, отличного от предыдущего, в качестве signingKey нового маркера SAS в приложение.
Повторно создайте первичный ключ, удалите управляемое удостоверение из учетной записи и удалите назначение роли для управляемого удостоверения.

Создание маркеров SAS

Чтобы создать маркеры SAS, необходимо иметь Contributor доступ к роли как к учетным записям Azure Maps, так и к удостоверениям, назначенным пользователем, в подписке Azure.

Внимание

Существующие учетные записи Azure Maps, созданные в расположении global Azure, не поддерживают управляемые удостоверения.

Сначала следует создать назначаемое пользователем управляемое удостоверение в том же расположении, что и учетная запись Azure Maps.

Совет

Необходимо использовать одно и то же расположение как для управляемого удостоверения, так и для учетной записи Azure Maps.

После создания управляемого удостоверения можно создать или обновить учетную запись Azure Maps и присоединить ее. Дополнительные сведения см. в статье "Управление учетной записью Azure Maps".

После успешного создания или обновления учетной записи с помощью управляемого удостоверения; назначьте управление доступом на основе ролей для управляемого удостоверения роли данных Azure Maps в области учетной записи. Это позволит управляемому удостоверению предоставлять доступ к REST API Azure Maps для учетной записи Maps.

Затем создайте маркер SAS с помощью инструментов пакета SDK для управления Azure, перечисления операции SAS в API управления учетными записями или страницы портал Azure сигнатуры общего доступа ресурса учетной записи карты.

Параметры маркера SAS.

имени параметра	Пример значения	Description
подписьKey	`primaryKey`	Обязательный параметр перечисления строки для ключа подписи `primaryKeysecondaryKey` или управляемого удостоверения используется для создания подписи SAS.
principalId	`<GUID>`	Обязательный идентификатор субъекта — это идентификатор объекта (субъекта) управляемого удостоверения, назначаемого пользователем, подключенного к учетной записи карты.
регионы	`[ "eastus", "westus2", "westcentralus" ]`	Необязательно. По умолчанию используется значение `null`. Регионы определяют, какие регионы маркер SAS можно использовать в API плоскости данных REST в Azure Maps. Параметр "Опустить регионы" позволяет использовать маркер SAS без каких-либо ограничений. При использовании в сочетании с географической конечной точкой уровня данных Azure Maps, например `us.atlas.microsoft.com` и `eu.atlas.microsoft.com` позволяет приложению управлять использованием в пределах указанного географического региона. Это позволяет предотвратить использование в других регионах.
maxRatePerSecond	500	Обязательно. Задает приблизительную максимальную скорость запросов в секунду, которая предоставляется маркеру SAS. После достижения предельного значения пропускная способность ограничена кодом `429 (TooManyRequests)`состояния HTTP.
start	`2021-05-24T10:42:03.1567373Z`	Обязательно. Дата и время в формате UTC, когда маркер станет активным.
точки восстановления	`2021-05-24T11:42:03.1567373Z`	Обязательно. Дата и время истечения срока действия маркера в формате UTC. Длительность между началом и истечением срока действия не может превышать 24 часа.

Настройка приложения с помощью маркера SAS

После того, как приложение получает маркер SAS, пакет SDK Azure Maps и/или приложения отправляют HTTPS-запрос со следующим необходимым HTTP-заголовком в дополнение к другим HTTP-заголовкам REST API.

Имя заголовка	Значение
Авторизация	jwt-sas eyJ0e….HNIVN

Примечание.

jwt-sas — это схема проверки подлинности для обозначения использования маркера SAS. Не включайте x-ms-client-id и не указывайте другие заголовки авторизации или параметр строки запроса subscription-key.

CORS является протоколом HTTP, которая позволяет веб-приложению, работающему в одном домене, обращаться к ресурсам из другого домена. Веб-браузеры реализуют ограничение безопасности под названием политика одного источника, которое не позволяет веб-странице вызывать интерфейсы API из другого домена; CORS обеспечивает безопасный способ, который разрешает одному домену (исходному домену) вызывать интерфейсы API в другом домене. С помощью ресурса учетной записи Azure Maps можно настроить, какие источники разрешены для доступа к REST API Azure Maps из приложений.

Внимание

CORS не является механизмом авторизации. Любой запрос, сделанный в учетную запись карты с помощью REST API, если CORS включен, также требуется допустимая схема проверки подлинности учетной записи карты, например общий ключ, идентификатор Microsoft Entra или маркер SAS.

CORS поддерживается для всех ценовых категорий учетных записей Maps, конечных точек плоскости данных и расположений.

Необходимые компоненты

Чтобы предотвратить выполнение вредоносного кода на клиенте, современные браузеры блокируют запросы от веб-приложений к ресурсам, выполняемым в отдельном домене.

Если вы не знакомы с CORS, ознакомьтесь с общим доступом Access-Control-Allow-Origin к ресурсам между источниками (CORS), он позволяет заголовок объявить, какие источники разрешены для вызова конечных точек учетной записи Azure Maps. Протокол CORS не зависит от Azure Maps.

Запросы CORS

Запрос CORS из исходного домена может состоять из двух отдельных запросов:

Предварительный запрос, который запрашивает ограничения CORS, наложенные службой. Предварительный запрос требуется, если запрос не является стандартным методом GET, HEAD, POST или запросами, содержащими Authorization заголовок запроса.
Фактический запрос нужного ресурса.

Предварительный запрос

Предварительный запрос выполняется не только в качестве меры безопасности, чтобы убедиться, что сервер понимает метод и заголовки, отправленные в фактическом запросе, и что сервер знает и доверяет источнику запроса, но также запрашивает ограничения CORS, установленные для учетной записи карты. Браузер (или другой агент пользователя) отправляет запрос OPTIONS, содержащий заголовки запроса, метод и исходный домен. Служба учетных записей Maps пытается получить правила CORS, если проверка подлинности учетной записи возможна через протокол предварительной проверки CORS.

Если проверка подлинности невозможна, служба карт оценивает предварительно настроенный набор правил 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, задав соответствующие параметры учетной записи.

Фактический запрос

После принятия предварительного запроса и возврата ответа браузер отправляет фактический запрос в службу карт. Браузер запрещает фактический запрос немедленно, если предварительный запрос отклоняется.

Фактический запрос считается обычным запросом к службе Maps. Наличие заголовка Origin указывает, что запрос является запросом CORS, а затем служба проверяет правила CORS. Если запрос соответствует правилам, в ответ будут добавлены заголовки Access-Control, после чего запрос будет отправлен обратно клиенту. Если совпадение не найдено, ответ возвращает 403 (Forbidden) ошибку источника CORS.

Включение политики CORS

При создании или обновлении учетной записи карты его свойства указывают разрешенные источники для настройки. Правило CORS можно задать в свойствах учетной записи Azure Maps с помощью пакета SDK для управления Azure Maps, REST API управления Azure Maps и на портале. После установки правила CORS для службы проверяется правильно авторизованный запрос, сделанный в службу из другого домена, чтобы определить, разрешено ли оно в соответствии с указанным правилом. Например:

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

Можно указать только одно правило CORS со списком разрешенных источников. Каждый источник позволяет выполнить HTTP-запрос к REST API Azure Maps в веб-браузере указанного источника.

Удаление политики CORS

Вы можете удалить CORS:

Вручную на портале Azure
Программное использование:
- Пакет SDK для Azure Maps
- REST API управления Azure Maps
- Шаблон ARM

Совет

Если вы используете REST API управления Azure Maps, используйте PUT или PATCH с пустым списком corsRule в тексте запроса.

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

Общие сведения о взимании платы за транзакции

Azure Maps не учитывает транзакции выставления счетов для:

Коды состояния HTTP 5xx
401 (Не авторизовано)
403 (Forbidden (Запрещено))
408 (время ожидания)
429 (TooManyRequests)
Предварительные запросы CORS

Дополнительные сведения о транзакциях выставления счетов и других ценах на Azure Maps см. в разделе о ценах на Azure Maps.

Следующие шаги

Дополнительные сведения о рекомендациях по обеспечению безопасности см. в следующем разделе:

Дополнительные сведения о проверке подлинности приложения с помощью идентификатора Microsoft Entra и Azure Maps см. в следующих статье:

Управление проверкой подлинности в Azure Maps

Дополнительные сведения о проверке подлинности элемента управления Azure Maps с помощью идентификатора Microsoft Entra см. в следующих статье:

Использование библиотеки Map Control в службе Azure Maps

Поделиться через

Аутентификация в Azure Maps

Аутентификация на основе общего ключа

Проверка подлинности Microsoft Entra

Управляемые удостоверения для ресурсов Azure и Azure Maps

Настройка проверки подлинности Microsoft Entra приложения

Проверка подлинности с управлением доступом на основе ролей

Необходимые компоненты

Обзор

Выбор определения роли

Определения пользовательских ролей

Общие сведения об области

Отключение локальной проверки подлинности

Аутентификация с помощью маркера SAS

Общие сведения об ограничениях скорости для маркеров SAS

Ограничение максимальной скорости маркера SAS помогает контролировать размер оплаты за ресурс Azure Maps

Ограничения скорости применяются для каждого расположения Azure, а не глобально или географически

Ограничения скорости по умолчанию имеют приоритет над ограничениями скорости маркеров SAS

Общие сведения об управлении доступом с помощью маркеров SAS

Создание маркеров SAS

Настройка приложения с помощью маркера SAS

Необходимые компоненты

Запросы CORS

Предварительный запрос

Фактический запрос

Включение политики CORS

Удаление политики CORS

Общие сведения о взимании платы за транзакции

Следующие шаги

Обратная связь

Дополнительные ресурсы

Поделиться через

Аутентификация в Azure Maps

Аутентификация на основе общего ключа

Проверка подлинности Microsoft Entra

Управляемые удостоверения для ресурсов Azure и Azure Maps

Настройка проверки подлинности Microsoft Entra приложения

Проверка подлинности с управлением доступом на основе ролей

Необходимые компоненты

Обзор

Выбор определения роли

Определения пользовательских ролей

Общие сведения об области

Отключение локальной проверки подлинности

Аутентификация с помощью маркера SAS

Общие сведения об ограничениях скорости для маркеров SAS

Ограничение максимальной скорости маркера SAS помогает контролировать размер оплаты за ресурс Azure Maps

Ограничения скорости применяются для каждого расположения Azure, а не глобально или географически

Ограничения скорости по умолчанию имеют приоритет над ограничениями скорости маркеров SAS

Общие сведения об управлении доступом с помощью маркеров SAS

Создание маркеров SAS

Настройка приложения с помощью маркера SAS

Общий доступ к ресурсам независимо от источника (CORS)

Необходимые компоненты

Запросы CORS

Предварительный запрос

Фактический запрос

Включение политики CORS

Удаление политики CORS

Общие сведения о взимании платы за транзакции

Следующие шаги

Обратная связь

Дополнительные ресурсы