Compartilhar via

Autenticação com Azure Mapas

  • Artigo

O Azure Mapas dá suporte a três maneiras de autenticar solicitações: autenticação de chave compartilhada, autenticação [Microsoft Entra ID] e autenticação de token SAS (Assinatura de Acesso Compartilhado). Este artigo explica métodos de autenticação para ajudar a orientar a implementação dos serviços Azure Mapas. O artigo também descreve outros controles de conta, como desabilitar a autenticação local para Azure Policy e 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.

As chaves primária e secundária são geradas depois que a conta dos Azure Mapas é criada. 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 entrada do usuário e outros aplicativos podem exigir uma experiência de entrada 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 Azure Mapas podem exigir privilégios elevados para executar ações de gravação ou exclusão em APIs REST dos 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

Ao criar uma atribuição de função, ela é definida na hierarquia de recursos do Azure. A parte superior da hierarquia é um grupo de gerenciamento e o mais baixo é um recurso do Azure, como uma conta dos 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 true, toda a autenticação para a 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 false e depois de alguns minutos em que 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 de SAS (assinatura de acesso compartilhado) são tokens de autenticação criados usando o formato JWT (token Web JSON) e são assinados criptograficamente para provar a autenticação de um aplicativo para a API REST do Azure Mapas. Um token SAS, criado pela integração de uma identidade gerenciada atribuída pelo usuário com 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. Isso significa que depois que um token é criado, o token SAS é válido até que a expiração seja atendida 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 noções básicas sobre o controle de acesso para revogação de token SAS e alterações no 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

Ao especificar um limite de taxa máximo no token (maxRatePerSecond), as taxas excedentes não serã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 atingido. É responsabilidade do aplicativo gerenciar a repetição e a distribuição de tokens SAS. Não há nenhum limite de quantos tokens SAS podem ser criados para uma conta. Para ser possível aumentar ou diminuir o limite de um token existente deve-se criar um novo token SAS. O token SAS antigo ainda será válido até a expiração dele.

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, recomendamos:

  1. Crie tokens SAS com locais do Azure permitidos designados para Geografia de destino. Continue lendo para entender a criação de tokens SAS.
  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 variáveis que são impostos como uma agregação 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 no e usar o mesmo local que uma conta de Mapas do Azure, cada token agora compartilhará 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 êxito 7500 transações bem-sucedidas cada.

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.

Se desejar atribuir acesso temporário e remover o acesso para antes que o token SAS expire, revogue o token. Outros motivos para revogar o acesso podem ser se o token for distribuído com a atribuição de função Azure Maps Data Contributor involuntariamente e qualquer pessoa com o token SAS puder ler e gravar dados nas APIs REST do Azure Mapas que podem expor dados confidenciais ou um custo financeiro inesperado do uso.

Há duas opções para revogar o 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

Excluir uma identidade gerenciada usada por um token sas ou revogar o controle de acesso da identidade gerenciada causará instâncias do seu aplicativo usando o token sas e a identidade gerenciada para retornar intencionalmente 401 Unauthorized ou 403 Forbidden do Azure Mapas APIs REST que criarão 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 ou outros cabeçalhos de autorização ou subscription-key parâmetro de cadeia de caracteres de consulta.

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. Qualquer solicitação feita a uma conta de mapa usando a API REST, quando CORS está habilitado, também precisa de um esquema de autenticação de conta de mapa válido, como chave compartilhada, Microsoft Entra ID ou 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 é feita não apenas como medida de segurança para garantir que o servidor compreenda o método e os cabeçalhos que são enviados na solicitação real e que o servidor saiba e confie na origem da solicitação, mas também consulta as restrições de CORS que foram 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 de solicitação, o domínio de origem e de método. 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 do mapa é criada ou atualizada, suas propriedades especificam as origens permitidas a serem configuradas. É possível definir uma regra de CORS nas propriedades da conta do Mapas do azure por meio do SDK de gerenciamento de Mapas do azure, da API REST do gerenciamento de Mapas do azure e do portal. Depois de definir a regra CORS para o serviço, uma solicitação autorizada corretamente feita ao serviço de um domínio diferente é avaliada para determinar se é permitida de acordo com a regra que você especificou. 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 de Mapas do Azure, use PUT ou PATCH com uma corsRule lista 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:

Melhores práticas de autenticação e autorização

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

Gerenciar autenticação no Azure Mapas

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

Usar o Controle de Mapeamento do Azure Mapas