Autenticação com Azure Mapas

O Azure Mapas dá suporte a três métodos de autenticação: chave compartilhada, Microsoft Entra ID e token SAS (assinatura de acesso compartilhado). Este artigo explica esses métodos de autenticação, incluindo detalhes sobre controles de conta, como desabilitar a autenticação local para o Azure Policy e o CORS (compartilhamento de recursos entre origens).

Autenticação de Chave Compartilhada

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

Chaves primárias e secundárias são geradas automaticamente ao criar uma conta do Azure Mapas. Você é incentivado a usar a chave primária como a chave de assinatura ao chamar os Azure Mapas com a autenticação de chave compartilhada. A autenticação de chave compartilhada passa as chaves geradas por uma conta dos Azure Mapas para um serviço dos Azure Mapas. Para cada solicitação aos serviços Azure Mapas, adicione a chave de assinatura como um parâmetro para a URL. É possível usar a chave secundária em cenários como alterações de chave sem interrupção.

Exemplo de uso da chave de assinatura como um parâmetro em sua 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 Mapas oferece autenticação para os serviços do Azure Mapas usando o Microsoft Entra ID. O Microsoft Entra ID fornece autenticação baseada em identidade para usuários e aplicativos registrados no locatário do Microsoft Entra.

O Azure Mapas aceita tokens de acesso OAuth 2.0 para locatários do Azure Entra associados a uma assinatura do Azure que contêm uma conta do Azure Mapas. Os Azure Mapas aceitam tokens para:

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

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

Para obter mais informações sobre como configurar o Microsoft Entra ID e solicitar tokens para o Azure Mapas, confira Como gerenciar a autenticação no Azure Mapas.

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

Identidades gerenciadas para recursos do Azure e os Azure Mapas

As Identidades gerenciadas para recursos do Azure fornecem serviços do Azure com uma entidade de segurança baseada em aplicativos gerenciados automaticamente, que pode ser autenticada com o Microsoft Entra ID. Com o RBAC do Azure (controle de acesso baseado em função do Azure), a entidade de segurança de identidade gerenciada pode ser autorizada a acessar os serviços Azure Mapas. Alguns exemplos de identidades gerenciadas incluem: o Serviço de Aplicativo do Azure, o Azure Functions e as 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 saber mais sobre identidades gerenciadas, confira Gerenciar autenticação nos Azure Mapas.

Configurar a autenticação do Microsoft Entra do aplicativo

Os aplicativos são autenticados com o locatário do Microsoft Entra usando um ou mais cenários com suporte fornecidos pelo Microsoft Entra ID. Cada cenário de aplicativo do Microsoft Entra ID representa requisitos diferentes com base nas necessidades comerciais. Alguns aplicativos podem exigir experiências de logon do usuário e outros podem exigir uma experiência de logon do aplicativo. Para obter mais informações, veja Fluxos de autenticação e cenários de aplicativos.

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

Aqui está um exemplo de uma solicitação de rota do Azure Mapas que usa um token de portador OAuth 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 a ID do 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 não estiver familiarizado com o RBAC do Azure, a visão geral do RBAC (controle de acesso baseado em função) do Azure fornece aos tipos de entidade de segurança 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 Mapas dá suporte ao acesso a todos os tipos de entidades de segurança para o RBAC do Azure (controle de acesso baseado em função do Azure), 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 dos Azure Mapas é conhecida como um escopo. Uma atribuição de função é criada quando uma entidade de segurança, uma definição de função e um escopo são aplicados.

Visão geral

As seções a seguir discutem conceitos e componentes da integração dos Azure Mapas com o RBAC do Azure. Como parte do processo para configurar a conta do Azure Mapas, um diretório do Microsoft Entra é associado à assinatura do Azure na qual a conta do Azure Mapas 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, veja Atribuir funções do Azure usando o Portal do Azure.

Criar uma definição de função

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

Alguns serviços do Azure Mapas podem exigir privilégios elevados para a execução de ações de gravação ou exclusão em APIs REST do Azure Mapas. A função Colaborador de Dados do Azure Mapas é necessária para serviços que fornecem ações de gravação ou exclusão. A tabela a seguir descreve a quais serviços o Colaborador de Dados dos Azure Mapas é 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 de Leitor de Dados do Azure Mapas pode ser usada no lugar da função colaborador de dados do Azure Mapas.

¹ O Criador do Azure Mapas e o Registro de Dados e os serviços espaciais foram preteridos e serão desativados em 30/09/25.

Para obter informações sobre como exibir as configurações do RBAC do Azure, veja Como configurar o RBAC do Azure para os Azure Mapas.

Definições de função personalizadas

Um aspecto da segurança do aplicativo é o princípio de privilégios mínimos, a prática de limitar os direitos de acesso aos direitos exigidos para o trabalho atual. A limitação dos direitos de acesso é realizada criando definições de função personalizadas que oferecem suporte a 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íficos para incluir ou excluir para a definição.

A definição de função personalizada pode então 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 personalizada do Azure, veja Funções personalizadas do Azure.

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

Compreender o escopo

As atribuições de função são definidas na hierarquia de recursos do Azure, desde o grupo de gerenciamento de nível superior até o nível mais baixo, como uma conta do Azure Mapas.

Conceder uma atribuição de função a um grupo de recursos pode habilitar o acesso a várias contas ou recursos dos Azure Mapas no grupo.

Desabilitar autenticação local

As contas do Azure Mapas suportam a propriedade padrão do Azure na API de Gerenciamento para Microsoft.Maps/accounts chamada disableLocalAuth. Quando definido como verdadeiro, toda autenticação na API REST do plano de dados do Azure Mapas está desabilitada, exceto a autenticação do Microsoft Entra. Isso é configurado usando Azure Policy para controlar a distribuição e o gerenciamento de chaves compartilhadas e tokens SAS. Para saber mais, veja O que é o Azure Policy?.

A desabilitação da autenticação local não entrará em vigor imediatamente. Aguarde alguns minutos para que o serviço bloqueie solicitações de autenticação futuras. Para reabilitar a autenticação local, defina a propriedade como falsa e, depois de alguns minutos, a autenticação local será retomada.

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

Autenticação de token de assinatura de acesso compartilhado

Os tokens SAS (assinatura de acesso compartilhado) são tokens de autenticação criados no formato JWT (Token Web JSON). Esses tokens são assinados de maneira criptográfica para autenticar um aplicativo na API REST do Azure Mapas. Eles são criados pela integração de uma identidade gerenciada atribuída pelo usuário a uma conta do Azure Mapas em sua assinatura do Azure. A identidade gerenciada atribuída pelo usuário recebe autorização para a conta de Mapas do azure por meio do RBAC do azure usando definições de função internas ou personalizadas.

Diferenças de chave funcional do token SAS dos tokens de acesso do Microsoft Entra:

• Tempo de vida de um token para uma validade máxima de um ano (24 horas).
• Localização do Azure e controle de acesso de geografia por token.
• Limites de taxa por token para um aproximado de 1 a 500 solicitações por segundo.
• As chaves privadas do token são as chaves primárias e secundárias de um recurso de conta do Azure Mapas.
• O objeto de entidade de serviço para autorização é fornecido por uma identidade gerenciada atribuída pelo usuário.

Os tokens SAS são imutáveis. Depois de criados, eles permanecem válidos até a expiração e não é possível alterar as configurações deles, como regiões permitidas, limites de taxa e identidade gerenciada atribuída pelo usuário. Para saber mais sobre revogações de token SAS e modificações de controle de acesso, consulte Fundamentos do controle de acesso.

Noções básicas dos limites de taxa de token SAS

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

Se você definir um limite máximo de taxa no token (maxRatePerSecond), as taxas que excederem esse valor não serão cobradas na conta, o que permite estabelecer um limite para transações faturáveis. No entanto, uma vez que o limite é atingido, o aplicativo recebe respostas de erro do cliente com 429 (TooManyRequests) para todas as transações. É responsabilidade do aplicativo gerenciar a repetição e a distribuição de tokens SAS. Não há nenhuma restrição no número de tokens SAS que podem ser criados para uma conta. Para modificar o limite de um token existente, é preciso gerar um novo token SAS. O token SAS antigo permanece válido até a expiração.

Exemplo estimado:

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

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

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

1. Crie tokens SAS com locais do Azure permitidos designados para a geografia pretendida.
2. Usar pontos de extremidade da API REST do plano de dados geográficos https://us.atlas.microsoft.com 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 que os serviços de Mapas do Azure estão hospedados, como East US, West Central US, ou West US 2. A mesma ideia se aplica a outros pontos de extremidade geográficos, como https://eu.atlas.microsoft.com entre West Europe e North Europe. Para evitar negações de autorização inesperadas, use um token SAS que usa os mesmos locais do Azure que o aplicativo consome. O local do ponto de extremidade é definido usando a API REST de gerenciamento de Mapas do Azure.

Os limites de taxa padrão assumem precedentes em relação aos limites de taxa de token SAS

Conforme descrito em Limites de taxa do Azure Mapas, as ofertas de serviço individuais têm limites de taxa que são impostos coletivamente no nível da conta.

Considere o caso do serviço Pesquisa, Reverso Sem Lote , 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 do uso de 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 para uma duração de 60 segundos. O serviço Pesquisa, Reverso Sem Lote, tem um limite de taxa de 250, ou seja, do total de 30.000 solicitações feitas em 60 segundos; 15.000 dessas solicitações são transações faturáveis. As solicitações restantes resultam em código de status 429 (TooManyRequests).

Por exemplo, se dois tokens SAS forem criados e usarem o mesmo local que uma conta do Azure Mapas, cada token compartilhará o limite de taxa padrão de 250 QPS. Se ambos forem usados simultaneamente com a mesma taxa de transferência, cada token terá a concessão de 7.500 transações bem-sucedidas.

Introdução o controle de acesso do token SAS

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

Para atribuir acesso temporário e remover esse acesso antes da expiração do token SAS, revogue o token. Outro motivo para revogar o acesso é quando o token é distribuído acidentalmente com a função de colaborador de dados do Azure Mapas, que pode permitir a leitura/gravação de dados não autorizados em APIs REST do Azure Mapas e resultar na exposição de dados confidenciais ou em custos inesperados.

Há duas opções de revogação de acesso para tokens SAS:

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

Criar tokens SAS

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

Primeiro, você deve criar uma identidade gerenciada atribuída pelo usuário no mesmo local que a conta de Mapas do Azure.

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

Assim que a conta for criada ou atualizada com sucesso com a identidade gerenciada; atribua o controle de acesso baseado em função para a identidade gerenciada a uma função de dados do Azure Mapas no escopo da conta. Isso permite que a identidade gerenciada receba acesso à API REST do Azure Mapas para sua conta do mapa.

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

Parâmetros do token SAS:

Configurando o aplicativo com o token SAS

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

CORS (compartilhamento de recursos entre origens)

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

Pré-requisitos

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

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

Solicitações do CORS

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

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

• A solicitação real, feita no recurso desejado.

Solicitação de simulação

A solicitação de simulação é uma medida de segurança que garante que o servidor entenda o método e os cabeçalhos enviados na solicitação real, verifica a origem da solicitação e consulta as restrições do CORS estabelecidas para a conta do mapa. O navegador da Web (ou outro agente do 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 do mapa tentará buscar as regras de CORS se a autenticação da conta for possível por meio do protocolo de simulação de CORS.

Se a autenticação não for possível, o serviço de mapas avalia o 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 do Mapas é configurada para permitir que todas as origens habilitem a integração direta em navegadores da Web.

O serviço responde à solicitação de simulação com os cabeçalhos de Access-Control necessários se os critérios a seguir 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 simulação.
3. A autenticação foi ignorada devido a cabeçalhos de solicitação Authorization necessários que não podem ser especificados na solicitação de simulação.

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

O serviço rejeita solicitações de simulação se as seguintes condições ocorrerem:

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

Solicitação real

Depois que a solicitação de simulação é aceita e a resposta é retornada, o navegador envia a solicitação real em relação ao serviço de mapa. O navegador nega a solicitação real imediatamente se a solicitação de simulação for rejeitada.

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

Habilitar política CORS

Quando uma conta de mapa é criada ou atualizada, as propriedades dela especificam as origens permitidas. É possível definir uma regra de CORS nas propriedades da conta do Azure Mapas por meio do SDK de gerenciamento, da API REST e do portal do Azure Mapas. Depois de definir a regra de CORS para o serviço, solicitações autorizadas de domínios diferentes são avaliadas para garantir a conformidade 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"
          ]
        }
      ]
    }
  }
}

Somente uma regra CORS com sua lista de origens permitidas pode ser especificada. Cada origem permite que a solicitação HTTP seja feita ao Azure Mapas API REST no navegador da web da origem especificada.

Remover política CORS

Você pode remover o CORS:

• Manualmente no portal do Azure
• Programaticamente, usando:
  • O SDK dos Azure Mapas
  • A API REST de gerenciamento do Azure Mapas
  • Um modelo do ARM

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

Entender as transações de cobrança

O Azure Mapas não conta as transações de cobrança para:

• Códigos de status HTTP 5xx
• 401 (não autorizado)
• 403 (Proibido)
• 408 (Tempo limite)
• 429 (TooManyRequests)
• Solicitações de simulação do CORS

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

Próximas etapas

Para saber mais sobre as melhores práticas de segurança, confira:

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

Para saber mais sobre como autenticar o Controle do Azure Mapas com o Microsoft Entra ID, confira: