Authentication with Azure Maps

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

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}

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:

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.

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

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

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.

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.

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.

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:

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:

1. Create SAS tokens with designated allowed Azure locations for targeted geography. Continue reading to understand creating SAS tokens.
2. 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).

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.

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

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

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.

First, you should Create a user-assigned managed identity in the same location as 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:

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:

Cross origin resource sharing (CORS)

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.

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:

1. The OPTIONS request contains the required CORS headers (the Origin and Access-Control-Request-Method headers)
2. Authentication was successful and A CORS rule is enabled for the account that matches the preflight request.
3. 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:

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

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

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

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

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