Authentication with Azure Maps

Azure Maps supports two ways to authenticate requests: Shared Key authentication and Azure Active Directory (Azure AD) authentication. This article explains both authentication methods to help guide your implementation of Azure Maps services.

Note

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

Shared Key authentication

Primary and secondary keys are generated after the Azure Maps account is created. You're encouraged to use the primary key as the subscription key when calling Azure Maps with shared key authentication. Shared Key authentication passes a key generated by an Azure Maps account to an Azure Maps service. For each request to Azure Maps services, add the subscription key as a parameter to the URL. The secondary key can be used in scenarios like rolling key changes.

For information about viewing your keys in the Azure portal, see Manage authentication.

Tip

For security purposes, it is recommended that you rotate between your primary and secondary keys. 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. The old primary key will be disabled. For more information on key rotation, see Set up Azure Key Vault with key rotation and auditing

Azure AD authentication

Azure Subscriptions are provided with an Azure AD tenant to enable fine grained access control. Azure Maps offers authentication for Azure Maps services using Azure AD. Azure AD provides identity-based authentication for users and applications registered in the Azure AD tenant.

Azure Maps accepts OAuth 2.0 access tokens for Azure AD tenants associated with an Azure subscription that contains an Azure Maps account. Azure Maps also accepts tokens for:

  • Azure AD users
  • Partner applications that use permissions delegated by users
  • Managed identities for Azure resources

Azure Maps generates a unique identifier (client ID) for each Azure Maps account. You can request tokens from Azure AD when you combine this client ID with additional parameters.

For more information about how to configure Azure AD and request tokens for Azure Maps, see Manage authentication in Azure Maps.

For general information about authenticating with Azure AD, see What is authentication?.

Managed identities for Azure resources and Azure Maps

Managed identities for Azure resources provide Azure services with an automatically managed application based security principal which can authenticate with Azure AD. With role-based access control (RBAC), the managed identity security principal can be authorized to access Azure Maps services. Some examples of managed identities include: Azure App Service, Azure Functions, and Azure Virtual Machines. For a list of managed identities, see managed identities for Azure resources.

Configuring application Azure AD authentication

Applications will authenticate with the Azure AD tenant using one or more supported scenarios provided by Azure AD. Each Azure AD application scenario represents different requirements based on business needs. Some applications may require user sign-in experiences and other applications may require an application sign-in experience. For more information, see Authentication flows and application scenarios.

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:

Header Name Value
x-ms-client-id 30d7cc….9f55
Authorization Bearer eyJ0e….HNIVN

Note

x-ms-client-id is the Azure Maps account-based GUID that appears on the Azure Maps authentication page.

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

For information about viewing your client ID, see View authentication details.

Authorization with role-based access control

Azure Maps supports access to all principal types for Azure role-based access control (Azure RBAC) including: individual Azure AD users, groups, applications, Azure resources, and Azure Managed identities. Principal types are granted a set of permissions, also known as a role definition. A role definition provides permissions to REST API actions. Applying access to one or more Azure Maps accounts is known as a scope. When applying a principal, role definition, and scope then a role assignment is created.

The next sections discuss concepts and components of Azure Maps integration with Azure AD role based access control. 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.

When you configure Azure RBAC, you choose a security principal and apply it to a role assignment. To learn how to add role assignments on the Azure portal, see Add or remove Azure role assignments.

Picking a role definition

The following role definition types exist to support application scenarios.

Azure Role Definition Description
Azure Maps Data Reader Provides access to immutable Azure Maps REST APIs.
Azure Maps Data Contributor Provides access to mutable Azure Maps REST APIs. Mutability is defined by the actions: write and delete.
Custom Role Definition Create a crafted role to enable flexible restricted access to Azure Maps REST APIs.

Some Azure Maps services may require elevated privileges to perform write or delete actions on Azure Maps REST APIs. Azure Maps Data Contributor role is required for services which provide write or delete actions. The following table describes which services Azure Maps Data Contributor is applicable for when using write or delete actions on the given service. If only read actions are used on the service, then Azure Maps Data Reader can be used instead of Azure Maps Data Contributor.

Azure Maps Service Azure Maps Role Definition
Data Azure Maps Data Contributor
Creator Azure Maps Data Contributor
Spatial Azure Maps Data Contributor

For information about viewing your RBAC settings, see How to configure RBAC for Azure Maps.

Custom role definitions

One aspect of application security is to apply the principle of least privilege. This principle implies that the security principal should only be allowed the access which is required, and have no additional access. Creating custom role definitions can support use cases which require further granularity to access control. To create a custom role definition, you can select specific data actions to include or exclude for the definition.

The custom role definition can then be used in a role assignment for any security principal. To learn more about Azure custom role definitions, see Azure custom roles.

Here are some example scenarios where custom roles can improve application security.

Scenario Custom Role Data Action(s)
A public facing or interactive sign-in web page with base map tiles and no other REST APIs. Microsoft.Maps/accounts/services/render/read
An application which only requires reverse geocoding and no other REST APIs. Microsoft.Maps/accounts/services/search/read
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/read
A role for a security principal which requires reading, writing, and deleting of Creator based map data. 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/delete

Understanding scope

When creating a role assignment, it is defined within the Azure resource hierarchy. At the top of the hierarchy is a management group and the lowest is an Azure resource, like an Azure Maps account. Assigning a role assignment to a resource group can enable access to multiple Azure Maps accounts or resources in the group.

Tip

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.

Next steps

To learn more about RBAC, see

To learn more about authenticating an application with Azure AD and Azure Maps, see

To learn more about authenticating the Azure Maps Map Control with Azure AD, see