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

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

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

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

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

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

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

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

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

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

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

Учетные записи 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 по-прежнему действителен до истечения срока действия.

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

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

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

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

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

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

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

Если вы хотите назначить временный доступ и удалить доступ до истечения срока действия маркера SAS, отмените маркер. Другие причины отзыва доступа могут быть, если маркер распространяется с Azure Maps Data Contributor назначением ролей непреднамеренно, и любой пользователь с маркером SAS может иметь возможность считывать и записывать данные в 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 для учетной записи Maps.

Затем создайте маркер SAS с помощью инструментов пакета SDK для управления Azure, перечисления операции 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, ознакомьтесь с общим доступом 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, если выполнены следующие критерии:

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

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

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

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 (TooManyRequests)
• Предварительные запросы CORS

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

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

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

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

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