Autenticação com o Azure Maps

Artigo
10/18/2023

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

Nota

Para melhorar a comunicação segura com o Azure Maps, agora oferecemos suporte ao Transport Layer Security (TLS) 1.2 e estamos desativando o suporte para TLS 1.0 e 1.1. Se você usa atualmente o TLS 1.x, avalie sua preparação para o TLS 1.2 e desenvolva um plano de migração com o teste descrito em Resolvendo o problema do TLS 1.0.

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/mapData/upload?api-version=1.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Subscription-key}

Importante

As chaves primária e secundária devem ser tratadas como dados confidenciais. A chave compartilhada é usada para autenticar toda a API REST do Azure Maps. Os usuários que usam uma chave compartilhada devem abstrair a chave da API, seja por meio de variáveis de ambiente ou armazenamento secreto seguro, onde ela pode 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 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:

Nome do Cabeçalho	valor
ID DO CLIENTE X-MS-	30d7cc... 9F55
Autorização	Portador eyJ0e... HNIVN

Nota

x-ms-client-id é o GUID baseado em conta do Azure Maps que aparece na página de autenticação do Azure Maps.

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.

Gorjeta

Obtendo a ID do Cliente programaticamente

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

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

Ao usar a CLI do Azure, use o comando com o az maps account show--query parâmetro, por 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 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.

Definição de função do Azure	Description
Azure Maps Search e Render Data Reader	Fornece acesso apenas para pesquisar e renderizar APIs REST do Azure Maps para limitar o acesso a casos básicos de uso do navegador da Web.
Azure Maps Data Reader	Fornece acesso a APIs REST imutáveis do Azure Maps.
Azure Maps Data Contributor	Fornece acesso a APIs REST mutáveis do Azure Maps. Mutabilidade, definida pelas ações: escrever e excluir.
Função de leitura de dados e lote do Azure Maps	Essa função pode ser usada para atribuir ações de leitura e em lote no Azure Maps.
Definição de função personalizada	Crie uma função criada para habilitar o acesso restrito flexível às APIs REST do Azure Maps.

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.

Serviço Azure Maps	Definição de função do Azure Maps
Dados	Azure Maps Data Contributor
Criador	Azure Maps Data Contributor
Spatial	Azure Maps Data Contributor
Pesquisa e Rota em Lote	Azure Maps Data Contributor

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.

Cenário	Ação(ões) de dados de função personalizada
Uma página Web de início de sessão interativa ou voltada para o público com mosaicos de mapa base e sem outras APIs REST.	`Microsoft.Maps/accounts/services/render/read`
Um aplicativo, que requer apenas geocodificação reversa e nenhuma outra API REST.	`Microsoft.Maps/accounts/services/search/read`
Uma função para uma entidade de segurança, que solicita uma leitura dos dados de mapa baseados no Azure Maps Creator e das APIs REST de mosaico 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, escrita e exclusão de dados de mapa baseados no Creator. Definida como uma função de editor de dados de mapa que não permite acesso a outras APIs REST, como blocos de mapa base.	`Microsoft.Maps/accounts/services/data/read`, , `Microsoft.Maps/accounts/services/data/writeMicrosoft.Maps/accounts/services/data/delete`

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.

Gorjeta

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

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:

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	6000

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:

Crie tokens SAS com locais do Azure permitidos designados para a geografia de destino. Continue lendo para entender a criação de tokens SAS.
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 .

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

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
ficha 1	250	250	60	~7500
ficha 2	250	250	60	~7500

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 atribuição de função involuntariamente e qualquer pessoa com Azure Maps Data Contributor 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:

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

Aviso

Excluir uma identidade gerenciada usada por um token SAS ou revogar o controle de acesso da identidade gerenciada fará com que instâncias do seu aplicativo usando o token SAS e a identidade gerenciada retornem 401 Unauthorized intencionalmente ou 403 Forbidden das APIs REST do Azure Maps, o que criará interrupção do aplicativo.

Para evitar interrupções:

Adicione uma segunda identidade gerenciada à Conta do Mapa e conceda à nova identidade gerenciada a atribuição de função correta.
Crie um token SAS usando secondaryKey, ou uma identidade gerenciada diferente da anterior, como o e distribua o novo token SAS para o signingKey aplicativo.
Regenere 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 Contributor acesso à função para gerenciar contas do Azure Maps e identidades atribuídas pelo usuário na assinatura do Azure.

Importante

As contas existentes do Azure Maps criadas na localização global do Azure não suportam identidades geridas.

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

Gorjeta

Você deve usar o mesmo local para a identidade gerenciada e a 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:

Nome do Parâmetro	Valor de Exemplo	Description
assinaturaChave	`primaryKey`	Obrigatório, o valor de enum da cadeia de caracteres para a signingKey ou `primaryKeysecondaryKey` a identidade gerenciada é usado para criar a assinatura da SAS.
principalId	`<GUID>`	Obrigatório, o principalId é o ID do objeto (principal) da identidade gerenciada atribuída pelo usuário anexada à conta do mapa.
regiões	`[ "eastus", "westus2", "westcentralus" ]`	Opcional, o valor padrão é `null`. As regiões controlam quais regiões o token SAS pode ser usado na API de plano de dados REST do Azure Maps. Omitir o parâmetro regions permite que o token SAS seja usado sem restrições. Quando usado em combinação com um ponto de extremidade geográfico do plano de dados do Azure Maps, como `us.atlas.microsoft.com` e `eu.atlas.microsoft.com` permite que o aplicativo controle o uso com a geografia especificada. Isso permite a prevenção do uso em outras geografias.
maxRatePerSecond	500	Obrigatório, a solicitação máxima aproximada especificada por segundo à qual o token SAS é concedido. Quando o limite é atingido, mais taxa de transferência é limitada com o código `429 (TooManyRequests)`de status HTTP.
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.
expiry (expira)	`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 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:

Nome do Cabeçalho	valor
Autorização	jwt-sas eyJ0e....HNIVN

Nota

jwt-sas é o esquema de autenticação a ser indicado usando o 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 é 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.

Importante

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

O CORS é suportado para todos os níveis de preços de contas de mapas, pontos finais de plano de dados e locais.

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:

A solicitação OPTIONS contém os cabeçalhos CORS necessários (os cabeçalhos Origin e Access-Control-Request-Method)
A autenticação foi bem-sucedida e uma regra CORS está habilitada para a conta que corresponde à solicitação de comprovação.
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:

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

Nota

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

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

Gorjeta

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

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

Gerenciar a autenticação no Azure Maps

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

Usar o Controle de Mapa do Azure Maps

Autenticação com o Azure Maps

Autenticação de chave compartilhada

Autenticação do Microsoft Entra

Identidades gerenciadas para recursos do Azure e Azure Maps

Configurar a autenticação do aplicativo Microsoft Entra

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

Pré-requisitos

Descrição geral

Escolhendo uma definição de função

Definições de função personalizadas

Compreender o âmbito

Desativar autenticação local

Autenticação de token de assinatura de acesso compartilhado

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

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

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

Compreender o controle de acesso ao token SAS

Criar tokens SAS

Configurando o aplicativo com token SAS

Compartilhamento de recursos entre origens (CORS)

Pré-requisitos

Pedidos CORS

Pedido de comprovação

Pedido real

Ativar a política CORS

Remover política CORS

Compreender as transações de faturação

Próximos passos

Recursos adicionais