Azure Maps Authentication Guide

Learn how to securely integrate Azure Maps into your ASP.NET Core applications with proper authentication and authorization. This guide provides three progressive examples that demonstrate different authentication approaches, from basic subscription keys to enterprise-grade Microsoft Entra ID integration.

🎯 What You'll Learn

• How to set up Azure Maps with different authentication methods
• Best practices for securing map applications in production
• Progressive security implementation from development to enterprise deployment
• Azure CLI commands to provision required infrastructure

📋 Prerequisites

• .NET 9.0 SDK
• Azure CLI
• An Azure subscription
• Basic knowledge of ASP.NET Core MVC

🏗️ Architecture Overview

This repository contains three progressive samples that build upon each other:

Sample	Authentication Method	Use Case	Security Level
KeyOnly	Subscription Key	Development & Learning	⚠️ Basic
Anonymous	Managed Identity	Production Apps	✅ Secure
Authentication	Microsoft Entra ID + Managed Identity	Enterprise Apps	🔒 Highly Secure

🚀 Quick Start

Step 1: Set Up Azure Infrastructure

First, create the required Azure resources using Azure CLI:

# Sign in to Azure
az login

# Create a resource group
az group create --location westeurope --name rg-azuremaps

# Create Azure Maps account
az maps account create --name map-azuremaps --resource-group rg-azuremaps --sku S2

# Get your Maps account details
az maps account show --name map-azuremaps --resource-group rg-azuremaps

Step 2: Choose Your Authentication Path

⚠️ CRITICAL SETUP NOTE
Azure Maps has its own Client ID that is different from Microsoft Entra ID App Registration Client IDs.
Always use the Azure Maps Client ID for the AzureMaps:ClientId setting.
Get it with: az maps account show --name map-azuremaps --resource-group rg-azuremaps --query "properties.uniqueId" --output tsv

🟡 Option A: Start with Subscription Key (Development)

Perfect for learning and local development. Not recommended for production.

# Get your subscription key
az maps account keys list --name map-azuremaps --resource-group rg-azuremaps

# Run the KeyOnly sample
cd source/KeyOnly
dotnet user-secrets set "AzureMaps:SubscriptionKey" "<your-key>"
dotnet run

📖 See detailed KeyOnly setup →

🟢 Option B: Use Managed Identity (Recommended for Production)

Eliminates shared secrets and provides automatic token rotation.

# Create App Service for deployment
az appservice plan create --resource-group rg-azuremaps --name plan-azuremaps --location westeurope --sku B1
az webapp create --resource-group rg-azuremaps --plan plan-azuremaps --name web-azuremaps --runtime "DOTNET|9.0"

# Enable managed identity and assign permissions
az webapp identity assign --name web-azuremaps --resource-group rg-azuremaps
az role assignment create --assignee "[PRINCIPAL_ID]" --role "Azure Maps Data Reader" --scope "/subscriptions/[SUBSCRIPTION_ID]/resourceGroups/rg-azuremaps/providers/Microsoft.Maps/accounts/map-azuremaps"

# Run the Anonymous sample
cd source/Anonymous
dotnet user-secrets set "AzureMaps:ClientId" "<your-maps-client-id>"
dotnet run

📖 See detailed Anonymous setup →

🔵 Option C: Add User Authentication (Enterprise)

Requires users to sign in with Microsoft Entra ID before accessing the application.

# Register application in Microsoft Entra ID
az ad app create --display-name "Azure Maps Demo App" \
  --web-redirect-uris https://web-azuremaps.azurewebsites.net/signin-oidc \
  --enable-access-token-issuance true \
  --enable-id-token-issuance true

# Run the Authentication sample
cd source/Authentication
dotnet user-secrets set "AzureMaps:ClientId" "<your-maps-client-id>"
dotnet run

📖 See detailed Authentication setup →

🔐 Security Best Practices

Development vs Production

• Development: Use subscription keys with user secrets
• Production: Always use Managed Identity + Azure RBAC
• Enterprise: Add user authentication with Microsoft Entra ID

Key Security Considerations

# Disable subscription key authentication in production
az maps account update --name map-azuremaps --resource-group rg-azuremaps --disable-local-auth true

Authentication Flow Overview

User Request → Microsoft Entra Authentication → App Service (Managed Identity) → Azure Maps Token → Map Rendering

🛠️ Common Setup Commands

Get Azure Maps Client ID (Important!)

# Get your Azure Maps Client ID - THIS IS NOT THE SAME as your App Registration Client ID
az maps account show --name map-azuremaps --resource-group rg-azuremaps --query "properties.uniqueId" --output tsv

Get other Azure information:

# Get subscription ID
az account show --query id --output tsv

# Get tenant ID  
az account show --query tenantId --output tsv

# List your Azure Maps accounts
az maps account list --output table

📚 Learning Path

1. Start Here: Run the KeyOnly sample to understand basic Azure Maps integration
2. Security Upgrade: Move to Anonymous sample to implement Managed Identity
3. Enterprise Ready: Implement the Authentication sample for user login requirements
4. Deploy: Use the provided Azure CLI commands to deploy to Azure App Service

🔧 Troubleshooting

⚠️ Critical: Two Different Client IDs

This is the #1 source of confusion for developers

There are TWO different Client IDs used in this solution:

Client ID Type	Purpose	Where to Find	Used In
Azure Maps Client ID	Identifies your Maps account	Azure Portal → Your Maps Account → Authentication	AzureMaps:ClientId setting
App Registration Client ID	Identifies your Microsoft Entra ID app	Azure Portal → Microsoft Entra ID → App Registrations	AzureAd:ClientId setting

⚠️ Common Mistake: Using the App Registration Client ID in the AzureMaps:ClientId setting will cause 401 authentication errors.

Common Issues

• Map not loading: Check browser console for authentication errors
• Token errors: Verify managed identity has correct RBAC permissions
• 401 Unauthorized: Usually caused by mixing up the two different Client IDs (see table above)
• Local development: Ensure user secrets are properly configured

Debug Commands

# Check managed identity status
az webapp identity show --name web-azuremaps --resource-group rg-azuremaps

# Verify role assignments
az role assignment list --assignee "[PRINCIPAL_ID]" --output table

# Test your deployed app
curl https://web-azuremaps.azurewebsites.net/api/GetAzureMapsToken

📖 Additional Resources

• Azure Maps Authentication Documentation
• Azure Maps Samples
• Managed Identity Best Practices
• Azure RBAC Documentation

---

🎯 Next Steps

After completing this guide, you'll have a solid foundation for implementing secure Azure Maps authentication in your applications. Consider exploring:

• Advanced Azure Maps features like custom styling and data visualization
• Integration with other Azure services like Azure SQL Database or Cosmos DB
• Implementing custom map controls and user interactions
• Setting up CI/CD pipelines for automated deployment

Happy mapping! 🗺️