Secure an input constrained device by using Microsoft Entra ID and Azure Maps REST APIs
This guide discusses how to secure public applications or devices that can't securely store secrets or accept browser input. These types of applications fall under the internet of things (IoT) category. Examples include Smart TVs and sensor data emitting applications.
To view your Azure Maps account authentication details in the Azure portal:
Sign in to the Azure portal.
Navigate to the Azure portal menu. Select All resources, and then select your Azure Maps account.
Under Settings in the left pane, select Authentication.
Three values are created when the Azure Maps account is created. They're used to support two types of authentication in Azure Maps:
- Microsoft Entra authentication: The
Client ID
represents the account that is to be used for REST API requests. TheClient ID
value should be stored in application configuration, and then it should be retrieved before making Azure Maps HTTP requests that use Microsoft Entra authentication. - Shared Key Authentication: The
Primary Key
andSecondary Key
are used as the subscription key for Shared Key authentication. Shared Key authentication relies on passing the key generated by the Azure Maps account with each request to Azure Maps. We recommend that you regularly regenerate your keys. To maintain current connections during regeneration, two keys are provided. One key can be in use, while regenerating the other. When you regenerate your keys, you must update any applications that access this account to use the new keys. For more information, see Authentication with Azure Maps
Create an application registration in Microsoft Entra ID
Note
- Prerequisite Reading: Scenario: Desktop app that calls web APIs
- The following scenario uses the device code flow, which does not involve a web browser to acquire a token.
Create the device based application in Microsoft Entra ID to enable Microsoft Entra sign-in, which is granted access to Azure Maps REST APIs.
In the Azure portal, in the list of Azure services, select Microsoft Entra ID > App registrations > New registration.
Enter a Name, choose Accounts in this organizational directory only as the Supported account type. In Redirect URIs, specify Public client / native (mobile & desktop) then add
https://login.microsoftonline.com/common/oauth2/nativeclient
to the value. For more information, see Microsoft Entra ID Desktop app that calls web APIs: App registration. Then Register the application.Navigate to Authentication and enable Treat application as a public client to enable device code authentication with Microsoft Entra ID.
To assign delegated API permissions to Azure Maps, go to the application. Then select API permissions > Add a permission. Under APIs my organization uses, search for and select Azure Maps.
Select the check box next to Access Azure Maps, and then select Add permissions.
Configure Azure role-based access control (Azure RBAC) for users or groups. For more information, see Grant role-based access for users to Azure Maps.
Add code for acquiring token flow in the application, for implementation details see Device code flow. When acquiring tokens, reference the scope:
user_impersonation
that was selected on earlier steps.Tip
Use Microsoft Authentication Library (MSAL) to acquire access tokens. For more information, see Desktop app that calls web APIs: Code configuration in the active directory documentation.
Compose the HTTP request with the acquired token from Microsoft Entra ID, and sent request with a valid HTTP client.
Sample request
Here's a sample request body for uploading a simple Geofence represented as a circle geometry using a center point and a radius.
POST /mapData?api-version=2.0&dataFormat=geojson
Host: us.atlas.microsoft.com
x-ms-client-id: 30d7cc….9f55
Authorization: Bearer eyJ0e….HNIVN
The following sample request body is in GeoJSON:
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-122.126986, 47.639754]
},
"properties": {
"geometryId": "001",
"radius": 500
}
}]
}
Sample response header
Operation-Location: https://us.atlas.microsoft.com/mapData/operations/{udid}?api-version=2.0
Access-Control-Expose-Headers: Operation-Location
Grant role-based access for users to Azure Maps
You can grant Azure role-based access control (Azure RBAC) by assigning a Microsoft Entra group or security principal to one or more Azure Maps role definitions.
To view the available Azure role definitions for Azure Maps, see View built-in Azure Maps role definitions.
For detailed steps about how to assign an available Azure Maps role to the created managed identity or the service principal, see Assign Azure roles using the Azure portal
To efficiently manage the Azure Maps app and resource access of a large amount of users, see Microsoft Entra groups.
Important
For users to be allowed to authenticate to an application, the users must first be created in Microsoft Entra ID. For more information, see Add or delete users using Microsoft Entra ID.
To learn about how to effectively manage a large directory for users, see Microsoft Entra ID.
Warning
Azure Maps built-in role definitions provide a very large authorization access to many Azure Maps REST APIs. To restrict APIs access to a minimum, see create a custom role definition and assign the system-assigned identity to the custom role definition. This enables the least privilege necessary for the application to access Azure Maps.
Next steps
Find the API usage metrics for your Azure Maps account: