Autenticação com o Azure Maps

O Azure Maps suporta três formas de autenticar pedidos: autenticação de Chave Partilhada, autenticação de ID do Microsoft Entra e autenticação de Token de Assinatura de Acesso Partilhado (SAS). Este artigo explica os métodos de autenticação para ajudar a orientar a implementação dos serviços do Azure Maps. O artigo também descreve outros controles de conta, como desabilitar a autenticação local para a Política do Azure e o Compartilhamento de Recursos entre Origens (CORS).

Autenticação de chave compartilhada

Para obter informações sobre como exibir suas chaves no portal do Azure, consulte Exibir detalhes de autenticação.

As chaves primária e secundária são geradas após a criação da conta do Azure Maps. Você é incentivado a usar a chave primária como a chave de assinatura ao chamar o Azure Maps com autenticação de chave compartilhada. A autenticação de Chave Partilhada passa uma chave gerada por uma conta do Azure Maps para um serviço do Azure Maps. Para cada solicitação aos serviços do Azure Maps, adicione a chave de assinatura como um parâmetro à URL. A chave secundária pode ser usada em cenários como alterações de teclas rolantes.

Exemplo de utilização da chave de subscrição como parâmetro no 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

Autenticação do Microsoft Entra

As Assinaturas do Azure são fornecidas com um locatário do Microsoft Entra para habilitar o controle de acesso refinado. O Azure Maps oferece autenticação para serviços do Azure Maps usando a ID do Microsoft Entra. O Microsoft Entra ID fornece autenticação baseada em identidade para usuários e aplicativos registrados no locatário do Microsoft Entra.

O Azure Maps aceita tokens de acesso OAuth 2.0 para locatários do Microsoft Entra associados a uma assinatura do Azure que contém uma conta do Azure Maps. O Azure Maps também aceita tokens para:

• Usuários do Microsoft Entra
• Aplicativos parceiros que usam permissões delegadas pelos usuários
• Identidades geridas para os recursos do Azure

O Azure Maps gera um identificador exclusivo (ID do cliente) para cada conta do Azure Maps. Você pode solicitar tokens do Microsoft Entra ID ao combinar essa ID de cliente com outros parâmetros.

Para obter mais informações sobre como configurar o Microsoft Entra ID e solicitar tokens para o Azure Maps, consulte Gerenciar autenticação no Azure Maps.

Para obter informações gerais sobre como autenticar com o Microsoft Entra ID, consulte Autenticação versus autorização.

Identidades gerenciadas para recursos do Azure e Azure Maps

As identidades gerenciadas para recursos do Azure fornecem aos serviços do Azure uma entidade de segurança baseada em aplicativo gerenciada automaticamente que pode ser autenticada com a ID do Microsoft Entra. Com o controle de acesso baseado em função do Azure (Azure RBAC), a entidade de segurança de identidade gerenciada pode ser autorizada a acessar os serviços do Azure Maps. Alguns exemplos de identidades gerenciadas incluem: Serviço de Aplicativo do Azure, Azure Functions e Máquinas Virtuais do Azure. Para obter uma lista de identidades gerenciadas, consulte Serviços do Azure que podem usar identidades gerenciadas para acessar outros serviços. Para obter mais informações sobre identidades gerenciadas, consulte Gerenciar autenticação no Azure Maps.

Configurar a autenticação do aplicativo Microsoft Entra

Os aplicativos são autenticados com o locatário do Microsoft Entra usando um ou mais cenários suportados fornecidos pela ID do Microsoft Entra. Cada cenário de aplicativo Microsoft Entra representa requisitos diferentes com base nas necessidades de negócios. Algumas aplicações podem exigir experiências de início de sessão do utilizador e outras aplicações podem exigir uma experiência de início de sessão na aplicação. Para obter mais informações, veja Cenários de fluxos de autenticação e aplicações.

Depois que o aplicativo recebe um token de acesso, o SDK e/ou aplicativo envia uma solicitação HTTPS com o seguinte conjunto de cabeçalhos HTTP necessários, além de outros cabeçalhos REST API HTTP:

Aqui está um exemplo de uma solicitação de rota do Azure Maps que usa um token OAuth Bearer do Microsoft Entra ID:

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

Para obter informações sobre como exibir sua ID de cliente, consulte Exibir detalhes de autenticação.

$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

Autorização com controle de acesso baseado em função

Pré-requisitos

Se você for novo no RBAC do Azure, a visão geral do controle de acesso baseado em função do Azure (Azure RBAC) fornece Os tipos principais recebem um conjunto de permissões, também conhecido como definição de função. Uma definição de função fornece permissões para ações da API REST. O Azure Maps dá suporte ao acesso a todos os tipos principais para o controle de acesso baseado em função do Azure (Azure RBAC), incluindo: usuários individuais do Microsoft Entra, grupos, aplicativos, recursos do Azure e identidades gerenciadas do Azure. A aplicação de acesso a uma ou mais contas do Azure Maps é conhecida como um escopo. Uma atribuição de função é criada quando um principal, uma definição de função e um escopo são aplicados.

Descrição geral

As próximas seções discutem conceitos e componentes da integração do Azure Maps com o Azure RBAC. Como parte do processo para configurar sua conta do Azure Maps, um diretório do Microsoft Entra é associado à assinatura do Azure, na qual a conta do Azure Maps reside.

Ao configurar o RBAC do Azure, você escolhe uma entidade de segurança e a aplica a uma atribuição de função. Para saber como adicionar atribuições de função no portal do Azure, consulte Atribuir funções do Azure usando o portal do Azure.

Escolhendo uma definição de função

Os seguintes tipos de definição de função existem para dar suporte a cenários de aplicativo.

Alguns serviços do Azure Maps podem exigir privilégios elevados para executar ações de gravação ou exclusão nas APIs REST do Azure Maps. A função de Colaborador de Dados do Azure Maps é necessária para serviços que fornecem ações de gravação ou exclusão. A tabela a seguir descreve quais serviços o Azure Maps Data Contributor é aplicável ao usar ações de gravação ou exclusão. Quando apenas ações de leitura são necessárias, a função Leitor de Dados do Azure Maps pode ser usada no lugar da função de Colaborador de Dados do Azure Maps.

1 O Azure Maps Creator e o Registo de dados e os serviços espaciais foram agora preteridos e serão descontinuados em 30/09/25.

Para obter informações sobre como exibir suas configurações do RBAC do Azure, consulte Como configurar o RBAC do Azure para o Azure Maps.

Definições de função personalizadas

Um aspeto da segurança do aplicativo é o princípio do menor privilégio, a prática de limitar os direitos de acesso aos direitos exigidos para o trabalho atual. A limitação dos direitos de acesso é realizada através da criação de definições de função personalizadas que suportam casos de uso que exigem maior granularidade para o controle de acesso. Para criar uma definição de função personalizada, selecione ações de dados específicas a serem incluídas ou excluídas para a definição.

A definição de função personalizada pode ser usada em uma atribuição de função para qualquer entidade de segurança. Para saber mais sobre as definições de função personalizadas do Azure, consulte Funções personalizadas do Azure.

Aqui estão alguns exemplos de cenários em que funções personalizadas podem melhorar a segurança do aplicativo.

Compreender o âmbito

Ao criar uma atribuição de função, ela é definida dentro da hierarquia de recursos do Azure. A parte superior da hierarquia é um grupo de gerenciamento e a mais baixa é um recurso do Azure, como uma conta do Azure Maps. Atribuir uma atribuição de função a um grupo de recursos pode permitir o acesso a várias contas ou recursos do Azure Maps no grupo.

Desativar autenticação local

As contas do Azure Maps dão suporte à propriedade padrão do Azure na API de Gerenciamento para Microsoft.Maps/accounts chamadas disableLocalAuth. Quando true, toda a autenticação para a API REST do plano de dados do Azure Maps está desabilitada, exceto a autenticação do Microsoft Entra. Isso é configurado usando a Política do Azure para controlar a distribuição e o gerenciamento de chaves compartilhadas e tokens SAS. Para obter mais informações, veja What is Azure Policy? (O que é o Azure Policy?).

A desativação da autenticação local não entra em vigor imediatamente. Aguarde alguns minutos para que o serviço bloqueie futuras solicitações de autenticação. Para reativar a autenticação local, defina a propriedade como false e após alguns minutos a autenticação local é retomada.

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

Autenticação de token de assinatura de acesso compartilhado

Os tokens de assinatura de acesso compartilhado (SAS) são tokens de autenticação criados usando o formato de token Web JSON (JWT) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Maps. Um token SAS, criado integrando uma identidade gerenciada atribuída pelo usuário a uma conta do Azure Maps em sua assinatura do Azure. A identidade gerenciada atribuída pelo usuário recebe autorização para a conta do Azure Maps por meio do RBAC do Azure usando definições de função internas ou personalizadas.

Principais diferenças funcionais do token SAS dos tokens de acesso do Microsoft Entra:

• Vida útil de um token para uma expiração máxima de um dia (24 horas).
• Controle de acesso de localização e geografia do Azure por token.
• Limites de taxa por token para aproximadamente 1 a 500 solicitações por segundo.
• As chaves privadas do token são as chaves primária e secundária de um recurso de conta do Azure Maps.
• O objeto Service Principal para autorização é fornecido por uma identidade gerenciada atribuída pelo usuário.

Os tokens SAS são imutáveis. Isso significa que, uma vez que um token é criado, o token SAS é válido até que a expiração tenha sido cumprida e a configuração das regiões permitidas, limites de taxa e identidade gerenciada atribuída pelo usuário não possa ser alterada. Leia mais abaixo sobre como entender o controle de acesso para revogação de token SAS e alterações no controle de acesso.

Entenda os limites de taxa de token SAS

O limite máximo de taxa do token SAS pode controlar a cobrança de um recurso do Azure Maps

Ao especificar um limite máximo de taxa no token (maxRatePerSecond), as taxas excedentes não são cobradas na conta, permitindo que você defina um limite superior de transações faturáveis para a conta, ao usar o token. No entanto, o aplicativo recebe respostas de erro do cliente com 429 (TooManyRequests) para todas as transações uma vez que o limite que atingiu. É responsabilidade do aplicativo gerenciar a repetição e distribuição de tokens SAS. Não há limite de quantos tokens SAS podem ser criados para uma conta. Para permitir um aumento ou diminuição no limite de um token existente; um novo token SAS deve ser criado. O token SAS antigo ainda é válido até sua expiração.

Exemplo estimado:

Os limites de taxa reais variam com base na capacidade do Azure Maps de impor consistência dentro de um período de tempo. No entanto, isso permite o controle preventivo do custo de faturamento.

Os limites de taxa são impostos por local do Azure, não globalmente ou geograficamente

Por exemplo, um único token SAS com um maxRatePerSecond de 10 pode ser usado para limitar a taxa de transferência no East US local. Se esse mesmo token for usado no West US 2, um novo contador será criado para limitar a taxa de transferência a 10 nesse local, independentemente do East US local. Para controlar os custos e melhorar a previsibilidade, recomendamos:

1. Crie tokens SAS com locais do Azure permitidos designados para a geografia de destino. Continue lendo para entender a criação de tokens SAS.
2. Use pontos https://us.atlas.microsoft.com de extremidade da API REST do plano de dados geográfico ou https://eu.atlas.microsoft.com.

Considere a topologia do aplicativo em que o ponto de extremidade https://us.atlas.microsoft.com roteia para os mesmos locais dos EUA em que os serviços do Azure Maps estão hospedados, como East US, West Central USou West US 2. A mesma ideia aplica-se a outros parâmetros geográficos, tais como https://eu.atlas.microsoft.com entre West Europe e North Europe. Para evitar recusas de autorização inesperadas, use um token SAS que use os mesmos locais do Azure que o aplicativo consome. O local do ponto de extremidade é definido usando a API REST do Azure Maps Management.

Os limites de taxa padrão têm precedente sobre os limites de taxa de token SAS

Conforme descrito nos limites de taxa do Azure Maps, as ofertas de serviço individuais têm limites de taxa variáveis que são impostos como uma agregação da conta.

Considere o caso do serviço de Pesquisa - Non-Batch Reverse, com seu limite de 250 consultas por segundo (QPS) para as tabelas a seguir. Cada tabela representa o total estimado de transações bem-sucedidas a partir do uso do exemplo.

A primeira tabela mostra um token que tem uma solicitação máxima por segundo de 500, e o uso real do aplicativo é de 500 solicitações por segundo por uma duração de 60 segundos. Serviço de pesquisa - Non-Batch Reverse tem um limite de taxa de 250, ou seja, do total de 30.000 solicitações feitas nos 60 segundos, 15.000 dessas solicitações são transações faturáveis. As solicitações restantes resultam em código de 429 (TooManyRequests)status .

Por exemplo, se dois tokens SAS forem criados e usarem o mesmo local que uma conta do Azure Maps, cada token agora compartilha o limite de taxa padrão de 250 QPS. Se cada token for usado ao mesmo tempo com a mesma taxa de transferência, o token 1 e o token 2 concederiam com sucesso 7500 transações bem-sucedidas cada.

Compreender o controle de acesso ao token SAS

Os tokens SAS usam RBAC para controlar o acesso à API REST. Quando você cria um token SAS, a identidade gerenciada de pré-requisito na Conta de Mapa recebe uma função RBAC do Azure que concede acesso a ações específicas da API REST. Consulte Escolhendo uma definição de função para determinar quais APIs o aplicativo permite.

Se você quiser atribuir acesso temporário e remover o acesso antes que o token SAS expire, revogue o token. Outros motivos para revogar o acesso podem ser se o token for distribuído com Azure Maps Data Contributor atribuição de função involuntariamente e qualquer pessoa com o token SAS poderá ler e gravar dados nas APIs REST do Azure Maps que podem expor dados confidenciais ou custos financeiros inesperados do uso.

há duas opções para revogar o acesso ao(s) token(s) SAS:

1. Regenere a chave que foi usada pelo token SAS ou secondaryKey da conta de mapa.
2. Remova a atribuição de função para a identidade gerenciada na conta de mapa associada.

Criar tokens SAS

Para criar tokens SAS, você deve ter Contributor acesso à função para gerenciar contas do Azure Maps e identidades atribuídas pelo usuário na assinatura do Azure.

Primeiro, você deve Criar uma identidade gerenciada atribuída pelo usuário no mesmo local da conta do Azure Maps.

Depois que uma identidade gerenciada é criada, você pode criar ou atualizar a conta do Azure Maps e anexá-la. Para obter mais informações, consulte Gerenciar sua conta do Azure Maps.

Uma vez que a conta é criada com sucesso ou atualizada com a identidade gerenciada; atribuir controle de acesso baseado em função para a identidade gerenciada a uma função de dados do Azure Maps no escopo da conta. Isso permite que a identidade gerenciada tenha acesso à API REST do Azure Maps para sua conta de mapa.

Em seguida, crie um token SAS usando as ferramentas do SDK de Gerenciamento do Azure, a operação Listar SAS na API de Gerenciamento de Contas ou a página Assinatura de Acesso Compartilhado do portal do Azure do recurso Conta de mapa.

Parâmetros do token SAS:

Configurando o aplicativo com token SAS

Depois que o aplicativo recebe um token SAS, o SDK do Azure Maps e/ou os aplicativos enviam uma solicitação HTTPS com o seguinte cabeçalho HTTP necessário, além de outros cabeçalhos HTTP da API REST:

Compartilhamento de recursos entre origens (CORS)

CORS é um protocolo HTTP que permite que um aplicativo Web executado em um domínio acesse recursos em outro domínio. Os navegadores da Web implementam uma restrição de segurança conhecida como política de mesma origem que impede que uma página da Web chame APIs em um domínio diferente; O CORS fornece uma maneira segura de permitir que um domínio (o domínio de origem) chame APIs em outro domínio. Usando o recurso de conta do Azure Maps, você pode configurar quais origens têm permissão para acessar a API REST do Azure Maps a partir de seus aplicativos.

Pré-requisitos

Para evitar a execução de códigos mal-intencionados no cliente, os navegadores modernos bloqueiam solicitações de aplicativos da Web para recursos executados em um domínio separado.

• Se você não estiver familiarizado com o CORS, consulte Compartilhamento de recursos entre origens (CORS), ele permite que um Access-Control-Allow-Origin cabeçalho declare quais origens têm permissão para chamar pontos de extremidade de uma conta do Azure Maps. O protocolo CORS não é específico do Azure Maps.

Pedidos CORS

Uma solicitação CORS de um domínio de origem pode consistir em duas solicitações separadas:

• Um pedido de comprovação, que consulta as restrições CORS impostas pelo serviço. A solicitação de comprovação é necessária, a menos que a solicitação seja o método padrão GET, HEAD, POST ou solicitações que contenham Authorization cabeçalho de solicitação.

• O pedido real, feito contra o recurso desejado.

Pedido de comprovação

A solicitação de comprovação é feita não apenas como uma medida de segurança para garantir que o servidor entenda o método e os cabeçalhos que são enviados na solicitação real e que o servidor conheça e confie na origem da solicitação, mas também consulta as restrições CORS que foram estabelecidas para a conta do mapa. O navegador da Web (ou outro agente de usuário) envia uma solicitação OPTIONS que inclui os cabeçalhos da solicitação, o método e o domínio de origem. O serviço de conta de mapa tenta obter quaisquer regras CORS se a autenticação da conta for possível através do protocolo de comprovação CORS.

Se a autenticação não for possível, o serviço de mapas avaliará um conjunto pré-configurado de regras CORS que especificam quais domínios de origem, métodos de solicitação e cabeçalhos de solicitação podem ser especificados em uma solicitação real em relação ao serviço de mapas. Por padrão, uma conta de mapas é configurada para permitir que todas as origens permitam uma integração perfeita em navegadores da Web.

O serviço responde à solicitação de comprovação com os cabeçalhos de controle de acesso necessários se os seguintes critérios forem atendidos:

1. A solicitação OPTIONS contém os cabeçalhos CORS necessários (os cabeçalhos Origin e Access-Control-Request-Method)
2. A autenticação foi bem-sucedida e uma regra CORS está habilitada para a conta que corresponde à solicitação de comprovação.
3. A autenticação foi ignorada devido aos cabeçalhos de solicitação necessários Authorization que não podem ser especificados na solicitação de comprovação.

Quando a solicitação de comprovação é bem-sucedida, o serviço responde com o código 200 (OK)de status e inclui os cabeçalhos de Controle de Acesso necessários na resposta.

O serviço rejeita pedidos de comprovação se ocorrerem as seguintes condições:

1. Se a solicitação OPTIONS não contiver os cabeçalhos CORS necessários (os cabeçalhos Origin e Access-Control-Request-Method), o serviço responderá com o código 400 (Bad request)de status.
2. Se a autenticação foi bem-sucedida na solicitação de comprovação e nenhuma regra CORS corresponde à solicitação de comprovação, o serviço responde com o código 403 (Forbidden)de status . Isso pode ocorrer se a regra CORS estiver configurada para aceitar uma origem que não corresponda ao cabeçalho atual da solicitação de origem do cliente do navegador.

Pedido real

Uma vez que a solicitação de comprovação é aceita e a resposta é retornada, o navegador envia a solicitação real para o serviço de mapas. O navegador nega o pedido real imediatamente se o pedido de comprovação for rejeitado.

A solicitação real é tratada como uma solicitação normal contra o serviço de mapa. A presença do Origin cabeçalho indica que a solicitação é uma solicitação CORS e, em seguida, o serviço valida em relação às regras CORS. Se uma correspondência for encontrada, os cabeçalhos de Controle de Acesso serão adicionados à resposta e enviados de volta ao cliente. Se uma correspondência não for encontrada, a resposta retornará indicando 403 (Forbidden) um erro de origem CORS.

Ativar a política CORS

Quando uma conta Map é criada ou atualizada, suas propriedades especificam as origens permitidas a serem configuradas. Você pode definir uma regra CORS nas propriedades da conta do Azure Maps por meio do SDK de Gerenciamento do Azure Maps, da API REST do Azure Maps Management e do portal. Depois de definir a regra CORS para o serviço, uma solicitação devidamente autorizada feita ao serviço a partir de um domínio diferente é avaliada para determinar se é permitida de acordo com a regra especificada. Por exemplo:

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

Apenas uma regra CORS com sua lista de origens permitidas pode ser especificada. Cada origem permite que a solicitação HTTP seja feita à API REST do Azure Maps no navegador da Web da origem especificada.

Remover política CORS

Você pode remover CORS:

• Manualmente no portal do Azure
• Utilizando programaticamente:
  • O SDK do Azure Maps
  • API REST de gerenciamento do Azure Maps
  • Um modelo ARM

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

Compreender as transações de faturação

O Azure Maps não conta as transações de faturação para:

• 5xx Códigos de status HTTP
• 401 (Não Autorizado)
• 403 (Proibido)
• 408 (Tempo limite)
• 429 (MuitosPedidos)
• Pedidos de comprovação CORS

Para obter mais informações sobre transações de cobrança e outras informações de preços do Azure Maps, consulte Preços do Azure Maps.

Próximos passos

Para saber mais sobre as práticas recomendadas de segurança, consulte:

Para saber mais sobre como autenticar um aplicativo com o Microsoft Entra ID e o Azure Maps, consulte:

Para saber mais sobre como autenticar o Controle do Azure Maps com a ID do Microsoft Entra, consulte: