Authentication with Azure Maps

Article
10/12/2023

Azure Maps supports three ways to authenticate requests: Shared Key authentication, Microsoft Entra ID authentication, and Shared Access Signature (SAS) Token authentication. This article explains authentication methods to help guide your implementation of Azure Maps services. The article also describes other account controls such as disabling local authentication for Azure Policy and Cross-Origin Resource Sharing (CORS).

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

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

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.

Example using the subscription key as a parameter in your URL:

https://atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Subscription-key}

Important

Primary and Secondary keys should be treated as sensitive data. The shared key is used to authenticate all Azure Maps REST API. Users who use a shared key should abstract the API key away, either through environment variables or secure secret storage, where it can be managed centrally.

Microsoft Entra authentication

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

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

Microsoft Entra 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 Microsoft Entra ID when you combine this client ID with other parameters.

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

For general information about authenticating with Microsoft Entra ID, see Authentication vs. authorization.

Managed identities for Azure resources and Azure Maps

Managed identities for Azure resources provide Azure services with an automatically managed application based security principal that can authenticate with Microsoft Entra ID. With Azure role-based access control (Azure 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 Azure services that can use managed identities to access other services. For more information on managed identities, see Manage authentication in Azure Maps.

Configure application Microsoft Entra authentication

Applications authenticate with the Microsoft Entra tenant using one or more supported scenarios provided by Microsoft Entra ID. Each Microsoft Entra 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 a Microsoft Entra ID 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.

Tip

Getting the Client ID programmatically

When using PowerShell, the Client ID is stored as the UniqueId Property in the IMapsAccount object. You retrieve this property using Get-AzMapsAccount, for example:

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

When using the Azure CLI use the az maps account show command with the --query parameter, for example:

$ClientId = az maps account show --name {Azure-Maps_Account-Name} --resource-group {Resource-Group-Name} --subscription {SubscriptionId} --query properties.uniqueId

Authorization with role-based access control

Prerequisites

If you're new to Azure RBAC, Azure role-based access control (Azure RBAC) overview provides Principal types are granted a set of permissions, also known as a role definition. A role definition provides permissions to REST API actions. Azure Maps supports access to all principal types for Azure role-based access control (Azure RBAC) including: individual Microsoft Entra users, groups, applications, Azure resources, and Azure managed identities. Applying access to one or more Azure Maps accounts is known as a scope. A role assignment is created when a principal, role definition, and scope are applied.

Overview

The next sections discuss concepts and components of Azure Maps integration with Azure RBAC. As part of the process to set up your Azure Maps account, a Microsoft Entra 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 Assign Azure roles using the Azure portal.

Picking a role definition

The following role definition types exist to support application scenarios.

Azure Role Definition	Description
Azure Maps Search and Render Data Reader	Provides access to only search and render Azure Maps REST APIs to limit access to basic web browser use cases.
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, defined by the actions: write and delete.
Azure Maps Data Read and Batch Role	This role can be used to assign read and batch actions on Azure Maps.
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 what services Azure Maps Data Contributor is applicable when using write or delete actions. When only read actions are required, the Azure Maps Data Reader role can be used in place of the Azure Maps Data Contributor role.

Azure Maps service	Azure Maps Role Definition
Data	Azure Maps Data Contributor
Creator	Azure Maps Data Contributor
Spatial	Azure Maps Data Contributor
Batch Search and Route	Azure Maps Data Contributor

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

Custom role definitions

One aspect of application security is the principle of least privilege, the practice of limiting access rights to the rights required for the current job. Limiting access rights is accomplished by creating custom role definitions that support use cases requiring further granularity to access control. To create a custom role definition, 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 a 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. Defined as a map data editor role that doesn't allow access to other REST API like base map tiles.	`Microsoft.Maps/accounts/services/data/read`, `Microsoft.Maps/accounts/services/data/write`, `Microsoft.Maps/accounts/services/data/delete`

Understand scope

When creating a role assignment, it's defined within the Azure resource hierarchy. 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.

Disable local authentication

Azure Maps accounts support the standard Azure property in the Management API for Microsoft.Maps/accounts called disableLocalAuth. When true, all authentication to the Azure Maps data-plane REST API is disabled, except Microsoft Entra authentication. This is configured using Azure Policy to control distribution and management of shared keys and SAS tokens. For more information, see What is Azure Policy?.

Disabling local authentication doesn't take effect immediately. Allow a few minutes for the service to block future authentication requests. To re-enable local authentication, set the property to false and after a few minutes local authentication resumes.

{
  // omitted other properties for brevity.
  "properties": {
    "disableLocalAuth": true
  }
}

Shared access signature token authentication

Shared access signature (SAS) tokens are authentication tokens created using the JSON Web token (JWT) format and are cryptographically signed to prove authentication for an application to the Azure Maps REST API. A SAS token, created by integrating a user-assigned managed identity with an Azure Maps account in your Azure subscription. The user-assigned managed identity is given authorization to the Azure Maps account through Azure RBAC using either built-in or custom role definitions.

Functional key differences of SAS token from Microsoft Entra access tokens:

Lifetime of a token for a max expiration of one day (24 hours).
Azure location and geography access control per token.
Rate limits per token for an approximate of 1 to 500 requests per second.
Private keys of the token are the primary and secondary keys of an Azure Maps account resource.
Service Principal object for authorization is supplied by a user-assigned managed identity.

SAS tokens are immutable. This means that once a token is created, the SAS token is valid until the expiry has been met and the configuration of the allowed regions, rate limits, and user-assigned managed identity can't be changed. Read more below on understanding access control for SAS token revocation and changes to access control.

Understand SAS token rate limits

SAS token maximum rate limit can control billing for an Azure Maps resource

When specifying a maximum rate limit on the token (maxRatePerSecond), the excess rates aren't billed to the account allowing you to set an upper limit of billable transactions for the account, when using the token. However, the application receives client error responses with 429 (TooManyRequests) for all transactions once that limit it reached. It's the responsibility of the application to manage retry and distribution of SAS tokens. There's no limit on how many SAS tokens can be created for an account. To allow for an increase or decrease in an existing token's limit; a new SAS token must be created. The old SAS token is still valid until its expiration.

Estimated Example:

Approximate Maximum Rate Per Second	Actual Rate Per Second	Duration of sustained rate in seconds	Total billable transactions
10	20	600	6,000

Actual rate limits vary based on Azure Maps ability to enforce consistency within a span of time. However, this allows for preventive control of billing cost.

Rate limits are enforced per Azure location, not globally or geographically

For example, a single SAS token with a maxRatePerSecond of 10 can be used to limit the throughput in the East US location. If that same token is used in West US 2, a new counter is created to limit the throughput to 10 in that location, independent of the East US location. To control costs and improve predictability, we recommend:

Create SAS tokens with designated allowed Azure locations for targeted geography. Continue reading to understand creating SAS tokens.
Use geographic data-plane REST API endpoints, https://us.atlas.microsoft.com or https://eu.atlas.microsoft.com.

Consider the application topology where the endpoint https://us.atlas.microsoft.com routes to the same US locations that the Azure Maps services are hosted, such as East US, West Central US, or West US 2. The same idea applies to other geographical endpoints such as https://eu.atlas.microsoft.com between West Europe and North Europe. To prevent unexpected authorization denials, use a SAS token that uses the same Azure locations that the application consumes. The endpoint location is defined using the Azure Maps Management REST API.

Default rate limits take precedent over SAS token rate limits

As described in Azure Maps rate limits, individual service offerings have varying rate limits that are enforced as an aggregate of the account.

Consider the case of Search service - Non-Batch Reverse, with its limit of 250 queries per second (QPS) for the following tables. Each table represents estimated total successful transactions from example usage.

The first table shows one token that has a maximum request per second of 500, and actual usage of the application is 500 request per second for a duration of 60 seconds. Search service - Non-Batch Reverse has a rate limit of 250, meaning of the total 30,000 requests made in the 60 seconds; 15,000 of those requests are billable transactions. The remaining requests result in status code 429 (TooManyRequests).

Name	Approximate Maximum Rate Per Second	Actual Rate Per Second	Duration of sustained rate in seconds	Approximate total successful transactions
token	500	500	60	~15,000

For example, if two SAS tokens are created in, and use the same location as an Azure Maps account, each token now shares the default rate limit of 250 QPS. If each token is used at the same time with the same throughput token 1 and token 2 would successfully grant 7500 successful transactions each.

Name	Approximate Maximum Rate Per Second	Actual Rate Per Second	Duration of sustained rate in seconds	Approximate total successful transactions
token 1	250	250	60	~7500
token 2	250	250	60	~7500

Understand SAS token access control

SAS tokens use RBAC to control access to the REST API. When you create a SAS token, the prerequisite managed identity on the Map Account is assigned an Azure RBAC role that grants access to specific REST API actions. See Picking a role definition to determine which APIs the application allows.

If you want to assign temporary access and remove access for before the SAS token expires, revoke the token. Other reasons to revoke access may be if the token is distributed with Azure Maps Data Contributor role assignment unintentionally and anyone with the SAS token may be able to read and write data to Azure Maps REST APIs that may expose sensitive data or unexpected financial cost from usage.

there are two options to revoke access for SAS token(s):

Regenerate the key that was used by the SAS token or secondaryKey of the map account.
Remove the role assignment for the managed identity on the associated map account.

Warning

Deleting a managed identity used by a SAS token or revoking access control of the managed identity will cause instances of your application using the SAS token and managed identity to intentionally return 401 Unauthorized or 403 Forbidden from Azure Maps REST APIs which will create application disruption.

To avoid disruption:

Add a second managed identity to the Map Account and grant the new managed identity the correct role assignment.
Create a SAS token using secondaryKey, or a different managed identity than the previous one, as the signingKey and distribute the new SAS token to the application.
Regenerate the primary key, remove the managed identity from the account, and remove the role assignment for the managed identity.

Create SAS tokens

To create SAS tokens, you must have Contributor role access to both manage Azure Maps accounts and user-assigned identities in the Azure subscription.

Important

Existing Azure Maps accounts created in the Azure location global don't support managed identities.

First, you should Create a user-assigned managed identity in the same location as the Azure Maps account.

Tip

You should use the same location for both the managed identity and the Azure Maps account.

Once a managed identity is created, you can create or update the Azure Maps account and attach it. For more information, see Manage your Azure Maps account.

Once the account is successfully created or updated with the managed identity; assign role-based access control for the managed identity to an Azure Maps data role at the account scope. This enables the managed identity to be given access to the Azure Maps REST API for your map account.

Next, create a SAS token using the Azure Management SDK tooling, List SAS operation on Account Management API, or the Azure portal Shared Access Signature page of the Map account resource.

SAS token parameters:

Parameter Name	Example Value	Description
signingKey	`primaryKey`	Required, the string enum value for the signingKey either `primaryKey`, `secondaryKey` or managed identity is used to create the signature of the SAS.
principalId	`<GUID>`	Required, the principalId is the Object (principal) ID of the user-assigned managed identity attached to the map account.
regions	`[ "eastus", "westus2", "westcentralus" ]`	Optional, the default value is `null`. The regions control which regions the SAS token can be used in the Azure Maps REST data-plane API. Omitting regions parameter allows the SAS token to be used without any constraints. When used in combination with an Azure Maps data-plane geographic endpoint like `us.atlas.microsoft.com` and `eu.atlas.microsoft.com` allows the application to control usage with-in the specified geography. This allows prevention of usage in other geographies.
maxRatePerSecond	500	Required, the specified approximate maximum request per second which the SAS token is granted. Once the limit is reached, more throughput is rate limited with HTTP status code `429 (TooManyRequests)`.
start	`2021-05-24T10:42:03.1567373Z`	Required, a UTC date that specifies the date and time the token becomes active.
expiry	`2021-05-24T11:42:03.1567373Z`	Required, a UTC date that specifies the date and time the token expires. The duration between start and expiry can't be more than 24 hours.

Configuring application with SAS token

After the application receives a SAS token, the Azure Maps SDK and/or applications send an HTTPS request with the following required HTTP header in addition to other REST API HTTP headers:

Header Name	Value
Authorization	jwt-sas eyJ0e….HNIVN

Note

jwt-sas is the authentication scheme to denote using SAS token. Do not include x-ms-client-id or other Authorization headers or subscription-key query string parameter.

CORS is an HTTP protocol that enables a web application running under one domain to access resources in another domain. Web browsers implement a security restriction known as same-origin policy that prevents a web page from calling APIs in a different domain; CORS provides a secure way to allow one domain (the origin domain) to call APIs in another domain. Using the Azure Maps account resource, you can configure which origins are allowed to access the Azure Maps REST API from your applications.

Important

CORS is not an authorization mechanism. Any request made to a map account using REST API, when CORS is enabled, also needs a valid map account authentication scheme such as Shared Key, Microsoft Entra ID, or SAS token.

CORS is supported for all map account pricing tiers, data-plane endpoints, and locations.

Prerequisites

To prevent malicious code execution on the client, modern browsers block requests from web applications to resources running in a separate domain.

If you're unfamiliar with CORS, see Cross-origin resource sharing (CORS), it lets an Access-Control-Allow-Origin header declare which origins are allowed to call endpoints of an Azure Maps account. CORS protocol isn't specific to Azure Maps.

CORS requests

A CORS request from an origin domain may consist of two separate requests:

A preflight request, which queries the CORS restrictions imposed by the service. The preflight request is required unless the request is standard method GET, HEAD, POST, or requests that contain Authorization request header.
The actual request, made against the desired resource.

Preflight request

The preflight request is done not only as a security measure to ensure that the server understands the method and headers that are sent in the actual request and that the server knows and trusts the source of the request, but it also queries the CORS restrictions that have been established for the map account. The web browser (or other user agent) sends an OPTIONS request that includes the request headers, method and origin domain. The map account service tries to fetch any CORS rules if account authentication is possible through the CORS preflight protocol.

If authentication isn't possible, the maps service evaluates a preconfigured set of CORS rules that specify which origin domains, request methods, and request headers may be specified on an actual request against the maps service. By default, a maps account is configured to allow all origins to enable seamless integration into web browsers.

The service responds to the preflight request with the required Access-Control headers if the following criteria are met:

The OPTIONS request contains the required CORS headers (the Origin and Access-Control-Request-Method headers)
Authentication was successful and A CORS rule is enabled for the account that matches the preflight request.
Authentication was skipped due to required Authorization request headers that can't be specified on preflight request.

When preflight request is successful, the service responds with status code 200 (OK), and includes the required Access-Control headers in the response.

The service rejects preflight requests if the following conditions occur:

If the OPTIONS request doesn’t contain the required CORS headers (the Origin and Access-Control-Request-Method headers), the service responds with status code 400 (Bad request).
If authentication was successful on preflight request and no CORS rule matches the preflight request, the service responds with status code 403 (Forbidden). This may occur if the CORS rule is configured to accept an origin that doesn't match the current browser client origin request header.

Note

A preflight request is evaluated against the service and not against the requested resource. The account owner must have enabled CORS by setting the appropriate account properties in order for the request to succeed.

Actual request

Once the preflight request is accepted and the response is returned, the browser dispatches the actual request against the map service. The browser denies the actual request immediately if the preflight request is rejected.

The actual request is treated as a normal request against the map service. The presence of the Origin header indicates that the request is a CORS request and the service then validates against the CORS rules. If a match is found, the Access-Control headers are added to the response and sent back to the client. If a match isn't found, the response returns a 403 (Forbidden) indicating a CORS origin error.

Enable CORS policy

When a Map account is created or updated, its properties specify the allowed origins to be configured. You can set a CORS rule on the Azure Maps account properties through Azure Maps Management SDK, Azure Maps Management REST API, and portal. Once you set the CORS rule for the service, then a properly authorized request made to the service from a different domain are evaluated to determine whether it's allowed according to the rule you've specified. For example:

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
    "cors": {
      "corsRules": [
        {
          "allowedOrigins": [
            "https://www.azure.com",
            "https://www.microsoft.com"
          ]
        }
      ]
    }
  }
}

Only one CORS rule with its list of allowed origins can be specified. Each origin allows the HTTP request to be made to Azure Maps REST API in the web browser of the specified origin.

Remove CORS policy

You can remove CORS:

Manually in the Azure portal
Programmatically using:
- The Azure Maps SDK
- Azure Maps management REST API
- An ARM template

Tip

If you use the Azure Maps management REST API , use PUT or PATCH with an empty corsRule list in the request body.

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
        "cors": {
          "corsRules": []
        }
    }
  }
}

Understand billing transactions

Azure Maps doesn't count billing transactions for:

5xx HTTP Status Codes
401 (Unauthorized)
403 (Forbidden)
408 (Timeout)
429 (TooManyRequests)
CORS preflight requests

For more information on billing transactions and other Azure Maps pricing information, see Azure Maps pricing.

Next steps

To learn more about security best practices, see:

Authentication and authorization best practices

To learn more about authenticating an application with Microsoft Entra ID and Azure Maps, see:

Manage authentication in Azure Maps

To learn more about authenticating the Azure Maps Control with Microsoft Entra ID, see:

Use the Azure Maps Map Control

Authentication with Azure Maps

Shared Key authentication

Microsoft Entra authentication

Managed identities for Azure resources and Azure Maps

Configure application Microsoft Entra authentication

Authorization with role-based access control

Prerequisites

Overview

Picking a role definition

Custom role definitions

Understand scope

Disable local authentication

Shared access signature token authentication

Understand SAS token rate limits

SAS token maximum rate limit can control billing for an Azure Maps resource

Rate limits are enforced per Azure location, not globally or geographically

Default rate limits take precedent over SAS token rate limits

Understand SAS token access control

Create SAS tokens

Configuring application with SAS token

Prerequisites

CORS requests

Preflight request

Actual request

Enable CORS policy

Remove CORS policy

Understand billing transactions

Next steps

Feedback

Additional resources

Authentication with Azure Maps

Shared Key authentication

Microsoft Entra authentication

Managed identities for Azure resources and Azure Maps

Configure application Microsoft Entra authentication

Authorization with role-based access control

Prerequisites

Overview

Picking a role definition

Custom role definitions

Understand scope

Disable local authentication

Shared access signature token authentication

Understand SAS token rate limits

SAS token maximum rate limit can control billing for an Azure Maps resource

Rate limits are enforced per Azure location, not globally or geographically

Default rate limits take precedent over SAS token rate limits

Understand SAS token access control

Create SAS tokens

Configuring application with SAS token

Cross origin resource sharing (CORS)

Prerequisites

CORS requests

Preflight request

Actual request

Enable CORS policy

Remove CORS policy

Understand billing transactions

Next steps

Feedback

Additional resources