Autenticação com Azure MapasAuthentication with Azure Maps

O mapas do Azure dá suporte a duas maneiras de autenticar solicitações: autenticação de chave compartilhada e autenticação do Azure Active Directory (AD do Azure) .Azure Maps supports two ways to authenticate requests: Shared Key authentication and Azure Active Directory (Azure AD) authentication. Este artigo explica os dois métodos de autenticação para ajudar a orientar sua implementação dos serviços do Azure Maps.This article explains both authentication methods to help guide your implementation of Azure Maps services.

Observação

Para melhorar a comunicação segura com o Azure Maps, agora damos suporte ao protocolo TLS 1,2 e estamos desativando o suporte para TLS 1,0 e 1,1.To improve secure communication with Azure Maps, we now support Transport Layer Security (TLS) 1.2, and we're retiring support for TLS 1.0 and 1.1. Se você usa 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 resolvendo o problema do tls 1,0.If you currently use TLS 1.x, evaluate your TLS 1.2 readiness and develop a migration plan with the testing described in Solving the TLS 1.0 Problem.

Autenticação de Chave CompartilhadaShared Key authentication

As chaves primária e secundária são geradas depois que a conta do Azure Maps é criada.Primary and secondary keys are generated after the Azure Maps account is created. Você é incentivado a usar a chave primária como a chave de assinatura ao chamar o Azure Maps com autenticação de chave compartilhada.You're encouraged to use the primary key as the subscription key when calling Azure Maps with shared key authentication. A autenticação de chave compartilhada passa uma chave gerada por uma conta do Azure Maps para um serviço do Azure Maps.Shared Key authentication passes a key generated by an Azure Maps account to an Azure Maps service. Para cada solicitação para os serviços do Azure Maps, adicione a chave de assinatura como um parâmetro à URL.For each request to Azure Maps services, add the subscription key as a parameter to the URL. A chave secundária pode ser usada em cenários como alterações de chave sem interrupção.The secondary key can be used in scenarios like rolling key changes.

Para obter informações sobre como exibir suas chaves no portal do Azure, consulte gerenciar a autenticação.For information about viewing your keys in the Azure portal, see Manage authentication.

Dica

Para fins de segurança, é recomendável que você gire entre as chaves primária e secundária.For security purposes, it is recommended that you rotate between your primary and secondary keys. Para fazer a rotação das chaves, atualize seu aplicativo para usar a chave secundária, implante, em seguida, pressione o botão ciclo/atualizar ao lado da chave primária para gerar uma nova chave primária.To rotate keys, update your app to use the secondary key, deploy, then press the cycle/refresh button beside the primary key to generate a new primary key. A chave primária antiga será desabilitada.The old primary key will be disabled. Para obter mais informações sobre a rotação de chaves, confira Configurar o Azure Key Vault com a rotação de chaves e auditoriaFor more information on key rotation, see Set up Azure Key Vault with key rotation and auditing

Autenticação do Azure ADAzure AD authentication

As assinaturas do Azure são fornecidas com um locatário do Azure AD para habilitar o controle de acesso refinado.Azure Subscriptions are provided with an Azure AD tenant to enable fine grained access control. O Azure Maps oferece autenticação para os serviços do Azure Maps usando o Azure AD.Azure Maps offers authentication for Azure Maps services using Azure AD. O Azure AD fornece autenticação baseada em identidade para usuários e aplicativos registrados no locatário do Azure AD.Azure AD provides identity-based authentication for users and applications registered in the Azure AD tenant.

Os Azure Mapas aceitam tokens de acesso OAuth 2.0 para locatários do Azure AD associados à assinatura do Azure que contêm uma conta dos Azure Mapas.Azure Maps accepts OAuth 2.0 access tokens for Azure AD tenants associated with an Azure subscription that contains an Azure Maps account. O Azure Maps também aceita tokens para:Azure Maps also accepts tokens for:

  • Usuários do Azure ADAzure AD users
  • Aplicativos de parceiros que usam permissões delegadas por usuáriosPartner applications that use permissions delegated by users
  • Identidades gerenciadas dos recursos do AzureManaged identities for Azure resources

Azure Mapas gera um identificador exclusivo (ID do cliente) para cada conta do Azure Mapas.Azure Maps generates a unique identifier (client ID) for each Azure Maps account. Você pode solicitar tokens do Azure AD ao combinar essa ID de cliente com parâmetros adicionais.You can request tokens from Azure AD when you combine this client ID with additional parameters.

Para obter mais informações sobre como configurar o Azure AD e solicitar tokens para os Azure Mapas, confira Como gerenciar a autenticação nos Azure Mapas.For more information about how to configure Azure AD and request tokens for Azure Maps, see Manage authentication in Azure Maps.

Para obter informações gerais sobre como autenticar com o Azure AD, consulte o que é autenticação?.For general information about authenticating with Azure AD, see What is authentication?.

Identidades gerenciadas para recursos do Azure e os Azure MapasManaged identities for Azure resources and Azure Maps

Identidades gerenciadas para recursos do Azure fornecem serviços do Azure com uma entidade de segurança baseada em aplicativo gerenciado automaticamente, que pode ser autenticada com o Azure AD.Managed identities for Azure resources provide Azure services with an automatically managed application based security principal which can authenticate with Azure AD. Com o RBAC (controle de acesso baseado em função), a entidade de segurança de identidade gerenciada pode ser autorizada a acessar os serviços do Azure Maps.With role-based access control (RBAC), the managed identity security principal can be authorized to access Azure Maps services. Alguns exemplos de identidades gerenciadas incluem: Azure App Service, Azure Functions e máquinas virtuais do Azure.Some examples of managed identities include: Azure App Service, Azure Functions, and Azure Virtual Machines. Para obter uma lista de identidades gerenciadas, consulte identidades gerenciadas para recursos do Azure.For a list of managed identities, see managed identities for Azure resources.

Configurando a autenticação do Azure AD do aplicativoConfiguring application Azure AD authentication

Os aplicativos serão autenticados com o locatário do Azure AD usando um ou mais cenários com suporte fornecidos pelo Azure AD.Applications will authenticate with the Azure AD tenant using one or more supported scenarios provided by Azure AD. Cada cenário de aplicativo do Azure AD representa requisitos diferentes com base nas necessidades de negócios.Each Azure AD application scenario represents different requirements based on business needs. Alguns aplicativos podem exigir experiências de entrada do usuário e outros aplicativos podem exigir uma experiência de entrada do aplicativo.Some applications may require user sign-in experiences and other applications may require an application sign-in experience. Para obter mais informações, consulte fluxos de autenticação e cenários de aplicativos.For more information, see Authentication flows and application scenarios.

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:After the application receives an access token, the SDK and/or application sends an HTTPS request with the following set of required HTTP headers in addition to other REST API HTTP headers:

Nome do cabeçalhoHeader Name ValorValue
x-ms-client-idx-ms-client-id 30d7cc….9f5530d7cc….9f55
AutorizaçãoAuthorization Portador eyJ0e….HNIVNBearer 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.x-ms-client-id is the Azure Maps account-based GUID that appears on the Azure Maps authentication page.

Aqui está um exemplo de uma solicitação de rota do Azure Maps que usa um token de portador OAuth do Azure AD:Here's an example of an Azure Maps route request that uses an Azure AD OAuth Bearer token:

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.For information about viewing your client ID, see View authentication details.

Autorização com controle de acesso baseado em funçãoAuthorization with role-based access control

O Azure Maps dá suporte ao acesso a todos os tipos principais para o controle de acesso baseado em função do Azure, incluindo: usuários individuais do Azure AD, grupos, aplicativos, recursos do Azure e identidades gerenciadas do Azure.Azure Maps supports access to all principal types for Azure role-based access control including: individual Azure AD users, groups, applications, Azure resources, and Azure Managed identities. Os tipos de entidade são concedidos a um conjunto de permissões, também conhecido como uma definição de função.Principal types are granted a set of permissions, also known as a role definition. Uma definição de função fornece permissões para ações da API REST.A role definition provides permissions to REST API actions. A aplicação de acesso a uma ou mais contas do Azure Maps é conhecida como um escopo.Applying access to one or more Azure Maps accounts is known as a scope. Ao aplicar uma entidade de segurança, definição de função e escopo, uma atribuição de função é criada.When applying a principal, role definition, and scope then a role assignment is created.

As seções a seguir discutem conceitos e componentes da integração do Azure Maps com o controle de acesso baseado em função do Azure AD.The next sections discuss concepts and components of Azure Maps integration with Azure AD role based access control. Como parte do processo para configurar sua conta do Azure Maps, um diretório do AD do Azure é associado à assinatura do Azure que a conta do Azure Maps reside.As part of the process to set up your Azure Maps account, an Azure AD directory is associated to the Azure subscription which the Azure Maps account resides.

Ao configurar o RBAC do Azure, você escolhe uma entidade de segurança e a aplica a uma atribuição de função.When you configure Azure RBAC, you choose a security principal and apply it to a role assignment. Para saber como adicionar atribuições de função no portal do Azure, consulte Adicionar ou remover atribuições de função do Azure.To learn how to add role assignments on the Azure portal, see Add or remove Azure role assignments.

Escolhendo uma definição de funçãoPicking a role definition

Os tipos de definição de função a seguir existem para dar suporte a cenários de aplicativo.The following role definition types exist to support application scenarios.

Definição de função do AzureAzure Role Definition DescriçãoDescription
Leitor de Dados do Azure MapasAzure Maps Data Reader Fornece acesso a APIs REST imutáveis do Azure Maps.Provides access to immutable Azure Maps REST APIs.
Colaborador de dados do Azure MapsAzure Maps Data Contributor Fornece acesso a APIs REST mutáveis do Azure Maps.Provides access to mutable Azure Maps REST APIs. A imutabilidade é definida pelas ações: gravar e excluir.Mutability is defined by the actions: write and delete.
Definição de função personalizadaCustom Role Definition Crie uma função criada para habilitar o acesso restrito flexível às APIs REST do Azure Maps.Create a crafted role to enable flexible restricted access to Azure Maps REST APIs.

Alguns serviços do Azure Maps podem exigir privilégios elevados para executar ações de gravação ou exclusão em APIs REST do Azure Maps.Some Azure Maps services may require elevated privileges to perform write or delete actions on Azure Maps REST APIs. A função colaborador de dados do Azure Maps é necessária para serviços que fornecem ações de gravação ou exclusão.Azure Maps Data Contributor role is required for services which provide write or delete actions. A tabela a seguir descreve a quais serviços o colaborador de dados do Azure Maps é aplicável ao usar ações de gravação ou exclusão no serviço em questão.The following table describes which services Azure Maps Data Contributor is applicable for when using write or delete actions on the given service. Se apenas as ações de leitura forem usadas no serviço, o leitor de dados do Azure Maps poderá ser usado em vez do colaborador de dados do Azure Maps.If only read actions are used on the service, then Azure Maps Data Reader can be used instead of Azure Maps Data Contributor.

Serviço de mapas do AzureAzure Maps Service Definição de função do Azure MapsAzure Maps Role Definition
DadosData Colaborador de dados do Azure MapsAzure Maps Data Contributor
CriadorCreator Colaborador de dados do Azure MapsAzure Maps Data Contributor
EspacialSpatial Colaborador de dados do Azure MapsAzure Maps Data Contributor

Para obter informações sobre como exibir as configurações do RBAC, confira Como configurar o RBAC para os Azure Mapas.For information about viewing your RBAC settings, see How to configure RBAC for Azure Maps.

Definições de função personalizadasCustom role definitions

Um aspecto da segurança do aplicativo é aplicar o princípio de privilégios mínimos.One aspect of application security is to apply the principle of least privilege. Esse princípio implica que a entidade de segurança só deve receber permissão de acesso necessário e não ter acesso adicional.This principle implies that the security principal should only be allowed the access which is required, and have no additional access. A criação de definições de função personalizadas pode dar suporte a casos de uso que exigem maior granularidade para o controle de acesso.Creating custom role definitions can support use cases which require further granularity to access control. Para criar uma definição de função personalizada, você pode selecionar ações de dados específicas para incluir ou excluir para a definição.To create a custom role definition, you can select specific data actions to include or exclude for the definition.

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.The custom role definition can then be used in a role assignment for any security principal. Para saber mais sobre as definições de função personalizada do Azure, consulte funções personalizadas do Azure.To learn more about Azure custom role definitions, see Azure custom roles.

Aqui estão alguns cenários de exemplo em que as funções personalizadas podem melhorar a segurança do aplicativo.Here are some example scenarios where custom roles can improve application security.

CenárioScenario Ação (ões) de dados de função personalizadaCustom Role Data Action(s)
Uma página da Web voltada para o público ou de entrada interativa com blocos de mapa base e nenhuma outra API REST.A public facing or interactive sign-in web page with base map tiles and no other REST APIs. Microsoft.Maps/accounts/services/render/read
Um aplicativo que requer apenas geocodificação inversa e nenhuma outra API REST.An application which only requires reverse geocoding and no other REST APIs. Microsoft.Maps/accounts/services/search/read
Uma função para uma entidade de segurança que solicita a leitura de dados de mapa baseados no criador do Azure Maps e APIs REST de bloco de mapa base.A role for a security principal which requests reading of Azure Maps Creator based map data and base map tile REST APIs. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/readMicrosoft.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 em criador.A role for a security principal which requires reading, writing, and deleting of Creator based map data. Isso pode ser definido como uma função de editor de dados de mapa, mas não permite o acesso a outras APIs REST, como blocos de mapa base.This can be defined as a map data editor role but does not allow access to other REST APIs like base map tiles. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/deleteMicrosoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/delete

Entendendo o escopoUnderstanding scope

Ao criar uma atribuição de função, ela é definida na hierarquia de recursos do Azure.When creating a role assignment, it is defined within the Azure resource hierarchy. Na parte superior da hierarquia há um grupo de gerenciamento e o mais baixo é um recurso do Azure, como uma conta do Azure Maps.At the top of the hierarchy is a management group and the lowest is an Azure resource, like an Azure Maps account. Atribuir uma atribuição de função a um grupo de recursos pode habilitar o acesso a várias contas ou recursos do Azure Maps no grupo.Assigning a role assignment to a resource group can enable access to multiple Azure Maps accounts or resources in the group.

Dica

A recomendação geral da Microsoft é atribuir acesso ao escopo da conta do Azure Maps porque impede o acesso não intencional a outras contas do Azure Maps existentes na mesma assinatura do Azure.Microsoft's general recommendation is to assign access to the Azure Maps account scope because it prevents unintended access to other Azure Maps accounts existing in the same Azure subscription.

Próximas etapasNext steps

Para saber mais sobre o RBAC, consulteTo learn more about RBAC, see

Para saber mais sobre como autenticar um aplicativo com o Azure AD e o Azure Maps, consulteTo learn more about authenticating an application with Azure AD and Azure Maps, see

Para saber mais sobre como autenticar o Controle de Mapeamento do Azure Maps com o Azure AD, consulteTo learn more about authenticating the Azure Maps Map Control with Azure AD, see