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

Azure Maps поддерживает три метода проверки подлинности: общий ключ, идентификатор Microsoft Entra и маркер SAS. В этой статье рассматриваются методы аутентификации, включая сведения об управляющих элементах учётными записями, таких как отключение локальной аутентификации для Azure Policy и Общий доступ к ресурсам между источниками (CORS).

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

Сведения о просмотре ключей в портал 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

Аутентификация 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 ID, комбинируя этот идентификатор клиента с другими параметрами.

Дополнительные сведения о настройке идентификатора 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.

Ниже приведен пример запроса маршрута 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

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

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

$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 Maps требуются повышенные привилегии для выполнения действий записи или удаления в REST API Azure Maps. Роль разработчика данных Azure Maps требуется для служб, которые предоставляют возможность выполнения записи или удаления. В следующей таблице описано, для каких служб применима роль разработчика данных Azure Maps, когда выполняется запись или удаление. Если требуются только операции чтения, можно использовать роль Azure Maps "Читатель данных" вместо роли "Разработчик данных Azure Maps".

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

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

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

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

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

Здесь приведено несколько примеров сценариев, когда использование пользовательских ролей может повысить безопасность приложения.

Понять объем

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

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

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

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

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

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

Аутентификация с помощью подписи общего доступа (SAS)

Маркеры общего доступа (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 помогает контролировать размер оплаты за ресурс Azure Maps

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

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

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

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

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

1. Создайте токены SAS с указанными разрешенными расположениями Azure для целевой географии.
2. Используйте географические конечные точки 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).

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

Понимание управления доступом с использованием токенов SAS

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

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

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

1. Создайте заново ключ, использованный токеном SAS или вторичным ключом учетной записи карты.
2. Удалите назначение роли для управляемой идентификационной системы на связанной учетной записи карты.

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

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

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

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

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

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

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

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

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

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

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

Предварительные условия

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

• Если вы не знакомы с CORS, ознакомьтесь с общим доступом к ресурсам между источниками (CORS); он позволяет заголовку определить, каким источникам разрешено обращаться к конечным точкам учетной записи Azure Maps. Протокол CORS не является специфичным для Azure Maps.

Запросы CORS

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

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

• Запрос, сделанный в отношении нужного ресурса.

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

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

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

Служба отвечает на предварительный запрос с необходимыми заголовками Access-Control, если выполнены следующие критерии:

1. Запрос OPTIONS содержит необходимые заголовки CORS (заголовки Origin и Access-Control-Request-Method).
2. Проверка подлинности прошла успешно, и для учетной записи, которая соответствует предварительному запросу, активировано правило CORS.
3. Процесс аутентификации был пропущен из-за обязательных Authorization заголовков запросов, которые нельзя указать при предварительном запросе (preflight request).

Если предварительный запрос выполнен успешно, служба отвечает с кодом состояния 200 (OK), и включает в ответ необходимые заголовки управления доступом.

Служба отклоняет предварительные запросы при возникновении следующих условий:

1. Если запрос OPTIONS не содержит необходимые заголовки CORS (заголовки Origin и Access-Control-Request-Method), служба отвечает с кодом состояния 400 (Bad request).
2. Если аутентификация была успешно выполнена при предварительном запросе и правило CORS не соответствует предварительному запросу, служба отвечает с кодом состояния 403 (Forbidden). Это может произойти, если правило 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

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

Понимание расчетных операций

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

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

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

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

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

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

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