Compartilhar via


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).

Observação

Para melhorar a comunicação segura com os Azure Mapas, agora damos suporte ao protocolo TLS (Transport Layer Security) 1.2 e estamos desativando o suporte ao TLS 1.0 e 1.1. Se você usar atualmente o TLS 1.x, avalie a preparação do TLS 1.2 e desenvolva um plano de migração com o teste descrito em Resolver o problema do TLS 1.0.

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

Importante

As chaves primária e secundária devem ser tratadas como dados confidenciais. A chave compartilhada é usada para autenticar todas as API REST do Azure Mapas. Os usuários que usam uma chave compartilhada devem abstrair a chave de API, seja por meio de variáveis de ambiente ou armazenamento secreto seguro, em que ela possa ser gerenciada centralmente.

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:

Nome do cabeçalho Valor
x-ms-client-id 30d7cc…9f55
Autorização Portador eyJ0e…HNIVN

Observação

x-ms-client-id é o GUID baseado na conta dos Azure Mapas exibido na página de autenticação dos Azure Mapas.

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.

Dica

Obter a ID do cliente programaticamente

Ao usar o PowerShell, a ID do Cliente é armazenada como a Propriedade UniqueId no objeto IMapsAccount. Você recupera essa propriedade usando Get-AzMapsAccount, por exemplo:

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

Ao usar o CLI do Azure use o az maps account show comando com o parâmetro, por --query exemplo:

$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.

Definição de função do Azure Descrição
Pesquisar e Renderizar Leitor de Dados do Azure Mapas Fornece acesso apenas para pesquisar e renderizar as APIs REST Mapas Azure para limitar o acesso a casos de uso básicos do navegador da Web.
Leitor de Dados do Azure Mapas Fornece acesso às APIs REST imutáveis dos Azure Mapas.
Colaborador de dados dos Azure Mapas Fornece acesso às APIs REST imutáveis dos Azure Mapas. Imutabilidade, definida pelas ações: gravar e excluir.
Função de leitura de dados e lote do Azure Mapas Essa função pode ser usada para atribuir ações de leitura e lote no Azure Mapas.
Definição de função personalizada Crie uma função elaborada para habilitar o acesso restrito flexível às APIs REST dos Azure Mapas.

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.

Serviço do Azure Mapas Definição de Função dos Azure Mapas
Criador (preterido1) Colaborador de dados dos Azure Mapas
Espacial (preterido 1) Colaborador de dados dos Azure Mapas
Pesquisa e rota emlote Colaborador de Dados dos Azure Mapas

1 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.

Cenário Ações de dados de função personalizada
Uma página da Web voltada para o público ou de entrada interativa com peças de mapa base e nenhuma outra API REST. Microsoft.Maps/accounts/services/render/read
Um aplicativo que requer apenas geocodificação inversa e nenhuma outra API REST. Microsoft.Maps/accounts/services/search/read
Uma função para uma entidade de segurança que solicita uma leitura de dados de mapa baseados no Criador do Azure Mapas e as APIs REST de peças de mapa base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/read
Uma função para uma entidade de segurança que requer leitura, gravação e exclusão de dados de mapa baseados no Criador. Definido como uma função de editor de dados de mapa que não permite o acesso a outra API REST, como peças de mapa base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/delete

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.

Dica

A recomendação geral da Microsoft é atribuir acesso ao escopo da conta dos Azure Mapas porque impede o acesso não intencional a outras contas dos Azure Mapas existentes na mesma assinatura do Azure.

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:

Taxa máxima aproximada por segundo Taxa real por segundo Duração da taxa sustentada em segundos Total de transações faturáveis
10 20 600 6\.000

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).

Nome Taxa máxima aproximada por segundo Taxa real por segundo Duração da taxa sustentada em segundos Total aproximado de transações bem-sucedidas
token 500 500 60 ~15.000

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.

Nome Taxa máxima aproximada por segundo Taxa real por segundo Duração da taxa sustentada em segundos Total aproximado de transações bem-sucedidas
token 1 250 250 60 ~7500
token 2 250 250 60 ~7500

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.

Aviso

Ao excluir uma identidade gerenciada usada por um token SAS ou revogar o controle de acesso dela, instâncias do aplicativo que usam o token SAS e a identidade gerenciada retornarão 401 Unauthorized ou 403 Forbidden por meio das APIs REST do Azure Mapas, o que poderá causar a interrupção do aplicativo.

Para evitar a interrupção:

  1. Adicione uma segunda identidade gerenciada à conta do mapa e conceda à nova identidade gerenciada a atribuição de função correta.
  2. Crie um token SAS usando secondaryKey ou uma identidade gerenciada diferente da anterior, como a signingKey e distribua o novo token SAS para o aplicativo.
  3. Gere novamente a chave primária, remova a identidade gerenciada da conta e remova a atribuição de função para a identidade gerenciada.

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.

Importante

As contas existentes do azure Mapas criadas no local do Azure global não dão suporte a identidades gerenciadas.

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

Dica

Você deve usar o mesmo local para a identidade gerenciada e a conta do Azure Mapas.

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:

Nome do Parâmetro Exemplo de valor Descrição
SigningKey primaryKey Obrigatório, no valor de enumeração da cadeia de caracteres para o signingKey é usado primaryKey, secondaryKey ou identidade gerenciada para criar a assinatura da SAS.
principalId <GUID> Obrigatório, o PrincipalId é a ID do objeto (principal) da identidade gerenciada atribuída pelo usuário anexada à conta do mapa.
regions [ "eastus", "westus2", "westcentralus" ] Opcional; o valor padrão é null. As regiões controlam quais regiões do token SAS podem ser usadas na API do plano de dados REST do Azure Mapas. A omissão do parâmetro regiões permite que o token SAS seja usado sem nenhuma restrição. Quando usado em combinação com um ponto de extremidade geográfico do plano de dados do Azure Mapas como us.atlas.microsoft.com e eu.atlas.microsoft.com permite que o aplicativo controle o uso com-na geografia especificada. Isso permite a prevenção de uso em outras regiões geográficas.
maxRatePerSecond 500 Obrigatório, a solicitação máxima aproximada especificada por segundo, que o token SAS é concedido. Depois que o limite for atingido, mais taxa de transferência é limitada com o código de status HTTP 429 (TooManyRequests).
iniciar 2021-05-24T10:42:03.1567373Z Obrigatório, uma data UTC que especifica a data e a hora em que o token se torna ativo.
data de expiração 2021-05-24T11:42:03.1567373Z Obrigatório, uma data UTC que especifica a data e a hora em que o token expira. A duração entre o início e a expiração não pode ser superior a 24 horas.

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:

Nome do cabeçalho Valor
Autorização jwt-sas eyJ0e….HNIVN

Observação

jwt-sas é o esquema de autenticação para indicar o uso do token SAS. Não inclua x-ms-client-id, outros cabeçalhos de autorização ou o parâmetro de cadeia de caracteres de consulta subscription-key.

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.

Importante

O CORS não é um mecanismo de autorização. Quando o CORS está habilitado, qualquer solicitação feita a uma conta de mapa usando a API REST também precisa de um esquema de autenticação de conta de mapa válido, como uma chave compartilhada, o Microsoft Entra ID ou um token SAS.

O CORS tem suporte para todos os tipos de preço da conta do mapa, pontos de extremidade do plano de dados e locais.

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.

Observação

Uma solicitação de simulação é avaliada em relação ao serviço e não em relação ao recurso solicitado. O proprietário da conta deve ter CORS habilitado, definindo as propriedades da conta apropriadas para que a solicitação seja bem-sucedida.

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

Dica

Se você usar a API REST de gerenciamento do Azure Mapas, use PUT ou PATCH com uma lista corsRule vazia no corpo da solicitação.

{
  "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: