title	titleSuffix	description	author	ms.author	ms.date	ms.topic	ms.service	services	ms.custom
Authentication with Microsoft Azure Maps	Azure Maps	Learn about two ways of authenticating requests in Azure Maps: shared key authentication and Azure Active Directory (Azure AD) authentication.	stevemunk	v-munksteve	05/25/2021	conceptual	azure-maps	azure-maps	mvc

Authentication with Azure Maps

Azure Maps supports three ways to authenticate requests: Shared Key authentication, Azure Active Directory (Azure AD) 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 additional 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 Manage 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.

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={Azure-Maps-Primary-Subscription-key}

Important

Primary and Secondary keys should be treated as sensitive data. The shared key is used to authenticate all Azure Maps REST APIs. 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.

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 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 Azure AD. 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 Services that support managed identities for Azure resources. To add and remove managed identities read more on Manage authentication in Azure Maps.

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

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 are 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 Azure AD users, groups, applications, Azure resources, and Azure managed identities. 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.

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, 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 Assign Azure roles.

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 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 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 only those needed to do the job at hand. To accomplish this, create custom role definitions that support use cases, which require 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. 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`

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

Disable local authentication

Azure Maps accounts support the standard Azure property in the Azure Maps Management REST API for Microsoft.Maps/accounts called disableLocalAuth. When true, all authentication to the Azure Maps data-plane REST API is disabled, except Azure AD 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 will resume.

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

Shared access signature token authentication

[!INCLUDE preview features callout]

Shared Access Signature token authentication is in preview.

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 is created by first 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 one of the built-in or custom role definitions.

Functional key differences of SAS token from Azure AD Access tokens:

Lifetime of a token for a max expiration of 1 year (365 days).
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 cannot 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

By specifying a maximum rate limit on the token (maxRatePerSecond), the excess rate will not be billed to the account allowing you to set an upper limit of billable transactions for the account, when using the token. However, the application will receive client error responses with 429 (TooManyRequests) for all transactions once that limit it reached. It is the responsibility of the application to manage retry and distribution of SAS tokens. There is 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 but remember that 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	6000

This is an estimate, actual rate limits vary slightly 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, leverage 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 which 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 1 token which has a maximum request per second of 500, and then actual usage of the application was 500 request per second for a duration of 60 seconds. Search Service - Non-Batch Reverse has a rate limit of 250, this means of the total 30000 requests made in the 60 seconds; 15000 of those requests will be billable transactions. The remaining requests will 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	~15000

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 which grants access to specific REST API actions. See Picking a role definition to determine which API should be allowed by the application.

If you want to assign temporary access and remove access for before the SAS token expires, you will want to 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 which may expose sensitive data or unexpected financial cost from usage.

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

Regenerate the key which was used by the SAS token, the primaryKey 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 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. See Manage your Azure Maps account for more information.

After the account has been 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, you'll need to 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` or `secondaryKey` 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 is allowed to be used in the Azure Maps REST data-plane API. Omitting regions parameter will allow 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` will allow 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, additional throughput will be 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 cannot be more than 365 days.

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.

Cross origin resource sharing (CORS)

[!INCLUDE preview features callout]

Cross Origin Resource Sharing (CORS) is in preview.

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 check out 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 is non-specific to Azure Maps.

Account 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. Azure Maps account resource supports the ability to configure allowed origins for your app which can access the Azure Maps REST API.

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, Azure AD, or SAS token.

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

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 which 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 will be 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 is not possible, the maps service evaluates pre-configured 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 will respond 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 which matches the preflight request.
Authentication was skipped due to required Authorization request headers which cannot 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 will reject 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 will respond with status code 400 (Bad request).
If authentication was successful on preflight request and no CORS rule matches the preflight request, the service will respond with status code 403 (Forbidden). This may occur if the CORS rule is configured to accept an origin which does not 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 will dispatch the actual request against the map service. The browser will deny 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 will then validate 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 is not found, the response will return a 403 (Forbidden) indicating a CORS origin error.

Enable CORS policy

When creating or updating an existing Map account, the Map account properties can 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 will be evaluated to determine whether it is allowed according to the rule you have specified. See an example below:

{
  "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, or programmatically using the Azure Maps SDK, Azure Maps management REST API or 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 does not count billing transactions for:

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

See Azure Maps pricing for additional information on billing transactions as well as other Azure Maps pricing information.

Next steps

To learn more about security best practices, see

[!div class="nextstepaction"] Authentication and authorization best practices

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

[!div class="nextstepaction"] Manage authentication in Azure Maps

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

[!div class="nextstepaction"] Use the Azure Maps Map Control

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

azure-maps-authentication.md

azure-maps-authentication.md

Authentication with Azure Maps

Shared Key authentication

Azure AD authentication

Managed identities for Azure resources and Azure Maps

Configure application Azure AD 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

Account CORS

CORS requests

Preflight request

Actual request

Enable CORS policy

Remove CORS policy

Understand billing transactions

Next steps

Files

azure-maps-authentication.md

Latest commit

History

azure-maps-authentication.md

File metadata and controls

Authentication with Azure Maps

Shared Key authentication

Azure AD authentication

Managed identities for Azure resources and Azure Maps

Configure application Azure AD 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

Account CORS

CORS requests

Preflight request

Actual request

Enable CORS policy

Remove CORS policy

Understand billing transactions

Next steps