Authentication with Azure Maps

Artikkel
10/12/2023

Azure Maps supports three authentication methods: Shared Key, Microsoft Entra ID, and Shared Access Signature (SAS) Token. This article explains these authentication methods including details on account controls like 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 automatically generated when creating an Azure Maps Account. 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/map/tile?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=2024-04-01&tilesetId=microsoft.base.road&zoom=15&x=5236&y=12665&tileSize=256

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 might 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 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
Creator (Deprecated¹)	Azure Maps Data Contributor
Spatial (Deprecated¹)	Azure Maps Data Contributor
Batch Search and Route	Azure Maps Data Contributor

¹ Azure Maps Creator, and the Data registry and Spatial services are now deprecated and will be retired on 9/30/25.

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

Role assignments are defined within the Azure resource hierarchy, from the top-level management group to the lowest level 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. These tokens are cryptographically signed to authenticate an application with the Azure Maps REST API. These SAS tokens are 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. Once they're created, they remain valid until they expire and their settings such as allowed regions, rate limits, and user-assigned managed identity can't be altered. For more information on SAS token revocation and modifications to access control, see understanding access control.

Understand SAS token rate limits

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

When setting a maximum rate limit on the token (maxRatePerSecond), any rates exceeding this limit aren't billed to the account, enabling you to establish a cap on billable transactions. However, the application receives client error responses with 429 (TooManyRequests) for all transactions once that limit is reached. It's the application's responsibility to manage retries and distribution of SAS tokens. There's no restriction on the number of SAS tokens that can be created for an account. To modify an existing token's limit, a new SAS token must be generated. The old SAS token remains valid until it expires.

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. Suggestions to control costs and improve predictability:

Create SAS tokens with designated allowed Azure locations for targeted geography.
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, the rate limits for individual service offerings are enforced collectively at the account level.

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 and use the same location as an Azure Maps account, each token shares the default rate limit of 250 QPS. If both tokens are used simultaneously with the same throughput, each token would grant 7,500 successful transactions.

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.

To assign temporary access and remove it before the SAS token expires, revoke the token. Another reason to revoke access is if the token was distributed unintentionally with the Azure Maps Data Contributor role, which can allow unauthorized data read/write on Azure Maps REST APIs, leading to sensitive data exposure or unexpected costs.

There are two options to revoke access for SAS tokens:

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 can result in instances of your application using the SAS token and managed identity to return 401 Unauthorized or 403 Forbidden from Azure Maps REST APIs, leading to potential application disruptions.

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 within 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. Don't 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 isn't an authorization mechanism. Requests 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 a security measure but also ensures that the server understands the method and headers sent in the actual request, verifies the source of the request, and queries the CORS restrictions 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 define the permitted origins. A CORS rule can be set on the Azure Maps account properties through the Azure Maps Management SDK, Azure Maps Management REST API, and portal. After setting the CORS rule for the service, authorized requests from different domains are evaluated to ensure compliance with the specified rule. 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

Del via

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

Tilbakemeldinger

Flere ressurser

Del via

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

Tilbakemeldinger

Flere ressurser