Autentisering med Azure Maps

Azure Maps stöder tre sätt att autentisera begäranden: autentisering med delad nyckel, Microsoft Entra-ID-autentisering och SAS-tokenautentisering (Signatur för delad åtkomst). I den här artikeln beskrivs autentiseringsmetoder som hjälper dig att implementera Azure Maps-tjänster. Artikeln beskriver även andra kontokontroller, till exempel inaktivering av lokal autentisering för Azure Policy och resursdelning mellan ursprung (CORS).

Autentisering med delad nyckel

Information om hur du visar dina nycklar i Azure Portal finns i Visa autentiseringsinformation.

Primära och sekundära nycklar genereras när Azure Maps-kontot har skapats. Du uppmanas att använda primärnyckeln som prenumerationsnyckel när du anropar Azure Maps med autentisering med delad nyckel. Autentisering med delad nyckel skickar en nyckel som genereras av ett Azure Maps-konto till en Azure Maps-tjänst. För varje begäran till Azure Maps-tjänster lägger du till prenumerationsnyckeln som en parameter i URL:en. Den sekundära nyckeln kan användas i scenarier som rullande nyckeländringar.

Exempel med prenumerationsnyckeln som en parameter i url:en:

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

Microsoft Entra-autentisering

Azure-prenumerationer tillhandahålls med en Microsoft Entra-klient för att aktivera detaljerad åtkomstkontroll. Azure Maps erbjuder autentisering för Azure Maps-tjänster med hjälp av Microsoft Entra-ID. Microsoft Entra ID tillhandahåller identitetsbaserad autentisering för användare och program som är registrerade i Microsoft Entra-klientorganisationen.

Azure Maps accepterar OAuth 2.0-åtkomsttoken för Microsoft Entra-klienter som är associerade med en Azure-prenumeration som innehåller ett Azure Maps-konto. Azure Maps accepterar även token för:

• Microsoft Entra-användare
• Partnerprogram som använder behörigheter som delegerats av användare
• Hanterade identiteter för Azure-resurser

Azure Maps genererar en unik identifierare (klient-ID) för varje Azure Maps-konto. Du kan begära token från Microsoft Entra-ID när du kombinerar det här klient-ID:t med andra parametrar.

Mer information om hur du konfigurerar Microsoft Entra-ID och begärandetoken för Azure Maps finns i Hantera autentisering i Azure Maps.

Allmän information om autentisering med Microsoft Entra-ID finns i Autentisering kontra auktorisering.

Hanterade identiteter för Azure-resurser och Azure Maps

Hanterade identiteter för Azure-resurser tillhandahåller Azure-tjänster med ett automatiskt hanterat programbaserat säkerhetsobjekt som kan autentiseras med Microsoft Entra-ID. Med rollbaserad åtkomstkontroll i Azure (Azure RBAC) kan det hanterade identitetssäkerhetsobjektet ha behörighet att komma åt Azure Maps-tjänster. Några exempel på hanterade identiteter är: Azure App Service, Azure Functions och Azure Virtual Machines. En lista över hanterade identiteter finns i Azure-tjänster som kan använda hanterade identiteter för att få åtkomst till andra tjänster. Mer information om hanterade identiteter finns i Hantera autentisering i Azure Maps.

Konfigurera Microsoft Entra-autentisering för program

Program autentiseras med Microsoft Entra-klientorganisationen med ett eller flera scenarier som stöds av Microsoft Entra ID. Varje Microsoft Entra-programscenario representerar olika krav baserat på affärsbehov. Vissa program kan kräva användarinloggning och andra program kan kräva en programinloggning. Mer information finns i Autentiseringsflöden och programscenarier.

När programmet har fått en åtkomsttoken skickar SDK och/eller programmet en HTTPS-begäran med följande uppsättning nödvändiga HTTP-huvuden utöver andra REST API HTTP-huvuden:

Här är ett exempel på en Azure Maps-routningsbegäran som använder en OAuth Bearer-token för Microsoft Entra ID:

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

Information om hur du visar ditt klient-ID finns i Visa autentiseringsinformation.

$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

Auktorisering med rollbaserad åtkomstkontroll

Förutsättningar

Om du inte har använt Azure RBAC tidigare ger översikten över rollbaserad åtkomstkontroll i Azure (Azure RBAC) huvudtyper en uppsättning behörigheter, även kallade rolldefinitioner. En rolldefinition ger behörighet till REST API-åtgärder. Azure Maps har stöd för åtkomst till alla huvudtyper för rollbaserad åtkomstkontroll i Azure (Azure RBAC) inklusive: enskilda Microsoft Entra-användare, grupper, program, Azure-resurser och Azure-hanterade identiteter. Att använda åtkomst till ett eller flera Azure Maps-konton kallas för ett omfång. En rolltilldelning skapas när ett huvudnamn, en rolldefinition och ett omfång tillämpas.

Översikt

I nästa avsnitt beskrivs begrepp och komponenter i Azure Maps-integrering med Azure RBAC. Som en del av processen för att konfigurera ditt Azure Maps-konto är en Microsoft Entra-katalog associerad med Azure-prenumerationen, som Azure Maps-kontot finns i.

När du konfigurerar Azure RBAC väljer du ett säkerhetsobjekt och tillämpar det på en rolltilldelning. Information om hur du lägger till rolltilldelningar på Azure Portal finns i Tilldela Azure-roller med hjälp av Azure Portal.

Välja en rolldefinition

Följande rolldefinitionstyper finns som stöd för programscenarier.

Vissa Azure Maps-tjänster kan kräva utökade behörigheter för att utföra skriv- eller borttagningsåtgärder på REST-API:er för Azure Maps. Rollen Azure Maps-datadeltagare krävs för tjänster som tillhandahåller skriv- eller borttagningsåtgärder. I följande tabell beskrivs vilka tjänster Azure Maps Data Contributor är tillämpligt när du använder skriv- eller borttagningsåtgärder. När endast läsåtgärder krävs kan azure maps-dataläsarrollen användas i stället för rollen Azure Maps-datadeltagare.

¹ Azure Maps Creator och dataregistret och spatiala tjänster är nu inaktuella och kommer att dras tillbaka den 30/30/25.

Information om hur du visar dina Azure RBAC-inställningar finns i Så här konfigurerar du Azure RBAC för Azure Maps.

Anpassade rolldefinitioner

En aspekt av programsäkerhet är principen om minsta behörighet, praxis att begränsa åtkomsträttigheterna till de rättigheter som krävs för det aktuella jobbet. Att begränsa åtkomsträttigheterna uppnås genom att skapa anpassade rolldefinitioner som stöder användningsfall som kräver ytterligare kornighet för åtkomstkontroll. Om du vill skapa en anpassad rolldefinition väljer du specifika dataåtgärder som ska inkluderas eller exkluderas för definitionen.

Den anpassade rolldefinitionen kan sedan användas i en rolltilldelning för alla säkerhetsobjekt. Mer information om anpassade rolldefinitioner i Azure finns i Anpassade Azure-roller.

Här följer några exempelscenarier där anpassade roller kan förbättra programsäkerheten.

Förstå omfång

När du skapar en rolltilldelning definieras den i Azure-resurshierarkin. Överst i hierarkin finns en hanteringsgrupp och den lägsta är en Azure-resurs, till exempel ett Azure Maps-konto. Om du tilldelar en rolltilldelning till en resursgrupp kan du ge åtkomst till flera Azure Maps-konton eller resurser i gruppen.

Inaktivera lokal autentisering

Azure Maps-konton stöder azure-standardegenskapen i hanterings-API:et för Microsoft.Maps/accounts namnet disableLocalAuth. När trueinaktiveras all autentisering till Rest-API:et för Azure Maps-dataplanet, förutom Microsoft Entra-autentisering. Detta konfigureras med Azure Policy för att styra distribution och hantering av delade nycklar och SAS-token. Mer information finns i Vad är Azure Policy?.

Inaktivering av lokal autentisering börjar inte gälla omedelbart. Tillåt några minuter för tjänsten att blockera framtida autentiseringsbegäranden. Om du vill återaktivera lokal autentisering anger du egenskapen till false och efter några minuter att den lokala autentiseringen återupptas.

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

Tokenautentisering för signatur för delad åtkomst

SAS-token (Signatur för delad åtkomst) är autentiseringstoken som skapats med JSON-webbtokenformatet (JWT) och är kryptografiskt signerade för att bevisa autentisering för ett program till Azure Maps REST API. En SAS-token som skapats genom att integrera en användartilldelad hanterad identitet med ett Azure Maps-konto i din Azure-prenumeration. Den användartilldelade hanterade identiteten ges auktorisering till Azure Maps-kontot via Azure RBAC med hjälp av antingen inbyggda eller anpassade rolldefinitioner.

Funktionella viktiga skillnader i SAS-token från Microsoft Entra-åtkomsttoken:

• Livslängd för en token för en maximal förfallotid på en dag (24 timmar).
• Åtkomstkontroll för Azure-plats och geografi per token.
• Frekvensgränser per token för cirka 1 till 500 begäranden per sekund.
• Privata nycklar för token är de primära och sekundära nycklarna för en Azure Maps-kontoresurs.
• Objektet Tjänstens huvudnamn för auktorisering tillhandahålls av en användartilldelad hanterad identitet.

SAS-token är oföränderliga. Det innebär att när en token har skapats är SAS-token giltig tills förfallotiden har uppfyllts och konfigurationen av de tillåtna regionerna, hastighetsbegränsningarna och den användartilldelade hanterade identiteten kan inte ändras. Läs mer nedan om att förstå åtkomstkontroll för SAS-tokenåterkallning och ändringar i åtkomstkontroll.

Förstå hastighetsbegränsningar för SAS-token

Högsta hastighetsgräns för SAS-token kan styra faktureringen för en Azure Maps-resurs

När du anger en maximal hastighetsgräns för token (maxRatePerSecond) debiteras inte överskjutande priser till kontot så att du kan ange en övre gräns för fakturerbara transaktioner för kontot när du använder token. Programmet får dock klientfelsvar med 429 (TooManyRequests) för alla transaktioner när den gränsen har nåtts. Det är programmets ansvar att hantera återförsök och distribution av SAS-token. Det finns ingen gräns för hur många SAS-token som kan skapas för ett konto. För att tillåta en ökning eller minskning av en befintlig tokens gräns; en ny SAS-token måste skapas. Den gamla SAS-token är fortfarande giltig tills den upphör att gälla.

Uppskattat exempel:

Faktiska hastighetsgränser varierar beroende på Azure Maps förmåga att framtvinga konsekvens inom en tidsperiod. Detta möjliggör dock förebyggande kontroll av faktureringskostnader.

Hastighetsgränser tillämpas per Azure-plats, inte globalt eller geografiskt

Till exempel kan en enskild SAS-token med värdet maxRatePerSecond 10 användas för att begränsa dataflödet på East US platsen. Om samma token används i West US 2skapas en ny räknare för att begränsa dataflödet till 10 på den East US platsen, oberoende av platsen. Vi rekommenderar att du kontrollerar kostnaderna och förbättrar förutsägbarheten:

1. Skapa SAS-token med angivna tillåtna Azure-platser för målgeografi. Fortsätt läsa för att förstå hur du skapar SAS-token.
2. Använd rest-API-slutpunkter för geografiskt dataplan, https://us.atlas.microsoft.com eller https://eu.atlas.microsoft.com.

Överväg programtopologin där slutpunkten https://us.atlas.microsoft.com dirigeras till samma platser i USA som Azure Maps-tjänsterna finns på, till exempel East US, West Central USeller West US 2. Samma idé gäller för andra geografiska slutpunkter som https://eu.atlas.microsoft.com mellan West Europe och North Europe. Om du vill förhindra oväntade auktoriseringsnekanden använder du en SAS-token som använder samma Azure-platser som programmet använder. Slutpunktsplatsen definieras med hjälp av REST-API:et för Azure Maps Management.

Standardfrekvensgränser tar prejudikat över SAS-tokenhastighetsgränser

Enligt beskrivningen i Prisbegränsningar för Azure Maps har enskilda tjänsterbjudanden varierande hastighetsgränser som tillämpas som en aggregering av kontot.

Tänk på fallet med tjänsten Search – Omvänd från batch med en gräns på 250 frågor per sekund (QPS) för följande tabeller. Varje tabell representerar uppskattad total lyckad transaktion från exempelanvändning.

Den första tabellen visar en token som har en maximal begäran per sekund på 500, och den faktiska användningen av programmet är 500 begäranden per sekund under 60 sekunder. tjänsten Search – Omvänd icke-batch har en hastighetsgräns på 250, vilket innebär att de totalt 30 000 begäranden som görs under 60 sekunder. 15 000 av dessa begäranden är fakturerbara transaktioner. Återstående begäranden resulterar i statuskod 429 (TooManyRequests).

Om till exempel två SAS-token skapas i och använder samma plats som ett Azure Maps-konto, delar varje token nu standardhastighetsgränsen på 250 QPS. Om varje token används samtidigt med samma dataflödestoken 1 och token 2 skulle bevilja 7500 lyckade transaktioner vardera.

Förstå åtkomstkontroll för SAS-token

SAS-token använder RBAC för att styra åtkomsten till REST-API:et. När du skapar en SAS-token tilldelas den nödvändiga hanterade identiteten på kartkontot en Azure RBAC-roll som ger åtkomst till specifika REST API-åtgärder. Se Välja en rolldefinition för att avgöra vilka API:er programmet tillåter.

Om du vill tilldela tillfällig åtkomst och ta bort åtkomst för innan SAS-token upphör att gälla återkallar du token. Andra orsaker till att återkalla åtkomst kan vara om token distribueras oavsiktligt med Azure Maps Data Contributor rolltilldelning och alla med SAS-token kan läsa och skriva data till Rest-API:er för Azure Maps som kan exponera känsliga data eller oväntade ekonomiska kostnader från användningen.

det finns två alternativ för att återkalla åtkomst för SAS-token:er:

1. Återskapa nyckeln som användes av SAS-token eller secondaryKey för kartkontot.
2. Ta bort rolltilldelningen för den hanterade identiteten på det associerade kartkontot.

Skapa SAS-token

Om du vill skapa SAS-token måste du ha Contributor rollåtkomst för att både hantera Azure Maps-konton och användartilldelade identiteter i Azure-prenumerationen.

Först bör du skapa en användartilldelad hanterad identitet på samma plats som Azure Maps-kontot.

När en hanterad identitet har skapats kan du skapa eller uppdatera Azure Maps-kontot och bifoga det. Mer information finns i Hantera ditt Azure Maps-konto.

När kontot har skapats eller uppdaterats med den hanterade identiteten. tilldela rollbaserad åtkomstkontroll för den hanterade identiteten till en Azure Maps-dataroll i kontoomfånget. På så sätt kan den hanterade identiteten ges åtkomst till Azure Maps REST API för ditt kartkonto.

Skapa sedan en SAS-token med hjälp av Azure Management SDK-verktyget, list-SAS-åtgärden i KONTOhanterings-API:et eller sidan Azure Portal signatur för delad åtkomst för map-kontoresursen.

SAS-tokenparametrar:

Konfigurera program med SAS-token

När programmet har fått en SAS-token skickar Azure Maps SDK och/eller program en HTTPS-begäran med följande nödvändiga HTTP-huvud utöver andra REST API HTTP-huvuden:

Resursdelning mellan ursprung (CORS)

CORS är ett HTTP-protokoll som gör att ett webbprogram som körs under en domän kan komma åt resurser i en annan domän. Webbläsare implementerar en säkerhetsbegränsning som kallas samma ursprungsprincip som förhindrar att en webbsida anropar API:er i en annan domän. CORS är ett säkert sätt att tillåta att en domän (ursprungsdomänen) anropar API:er i en annan domän. Med hjälp av Azure Maps-kontoresursen kan du konfigurera vilka ursprung som tillåts komma åt Rest-API:et för Azure Maps från dina program.

Förutsättningar

För att förhindra körning av skadlig kod på klienten blockerar moderna webbläsare begäranden från webbprogram till resurser som körs i en separat domän.

• Om du inte känner till CORS kan du läsa Resursdelning för korsande ursprung (CORS) och låter en Access-Control-Allow-Origin rubrik deklarera vilka ursprung som tillåts anropa slutpunkter för ett Azure Maps-konto. CORS-protokollet är inte specifikt för Azure Maps.

CORS-begäranden

En CORS-begäran från en ursprungsdomän kan bestå av två separata begäranden:

• En preflight-begäran som frågar cors-begränsningarna som införts av tjänsten. Förhandsbegäran krävs om inte begäran är standardmetoden GET, HEAD, POST eller begäranden som innehåller Authorization begärandehuvudet.

• Den faktiska begäran som görs mot den önskade resursen.

Preflight-begäran

Preflight-begäran görs inte bara som en säkerhetsåtgärd för att säkerställa att servern förstår metoden och huvudena som skickas i den faktiska begäran och att servern känner till och litar på källan till begäran, utan även frågar cors-begränsningarna som har upprättats för kartkontot. Webbläsaren (eller annan användaragent) skickar en OPTIONS-begäran som innehåller begärandehuvuden, metod och ursprungsdomän. Kartkontotjänsten försöker hämta eventuella CORS-regler om kontoautentisering är möjligt via CORS-protokollet preflight.

Om autentisering inte är möjligt utvärderar maps-tjänsten en förkonfigurerad uppsättning CORS-regler som anger vilka ursprungsdomäner, begärandemetoder och begärandehuvuden som kan anges för en faktisk begäran mot maps-tjänsten. Som standard konfigureras ett maps-konto så att alla ursprung möjliggör sömlös integrering i webbläsare.

Tjänsten svarar på preflight-begäran med de nödvändiga åtkomstkontrollrubrikerna om följande villkor uppfylls:

1. OPTIONS-begäran innehåller nödvändiga CORS-huvuden (rubrikerna Origin och Access-Control-Request-Method)
2. Autentiseringen lyckades och en CORS-regel är aktiverad för det konto som matchar förhandsbegäran.
3. Autentiseringen hoppades över på grund av nödvändiga Authorization begärandehuvuden som inte kan anges för förhandsbegäran.

När preflight-begäran lyckas svarar tjänsten med statuskoden 200 (OK)och innehåller de nödvändiga åtkomstkontrollrubrikerna i svaret.

Tjänsten avvisar preflight-begäranden om följande villkor inträffar:

1. Om OPTIONS-begäran inte innehåller nödvändiga CORS-huvuden (rubrikerna Origin och Access-Control-Request-Method) svarar tjänsten med statuskoden 400 (Bad request).
2. Om autentiseringen lyckades på begäran före start och ingen CORS-regel matchar förbegäran svarar tjänsten med statuskoden 403 (Forbidden). Detta kan inträffa om CORS-regeln är konfigurerad för att acceptera ett ursprung som inte matchar den aktuella webbläsarklientens begäranderubrik.

Faktisk begäran

När förhandsbegäran har godkänts och svaret returneras skickar webbläsaren den faktiska begäran mot karttjänsten. Webbläsaren nekar den faktiska begäran omedelbart om preflight-begäran avvisas.

Den faktiska begäran behandlas som en vanlig begäran mot karttjänsten. Förekomsten av Origin huvudet anger att begäran är en CORS-begäran och att tjänsten sedan validerar mot CORS-reglerna. Om en matchning hittas läggs åtkomstkontrollhuvudena till i svaret och skickas tillbaka till klienten. Om en matchning inte hittas returnerar svaret ett 403 (Forbidden) som anger ett CORS-ursprungsfel.

Aktivera CORS-princip

När ett kartkonto skapas eller uppdateras anger dess egenskaper vilka tillåtna ursprung som ska konfigureras. Du kan ange en CORS-regel för Azure Maps-kontoegenskaper via Azure Maps Management SDK, Azure Maps Management REST API och portalen. När du har angett CORS-regeln för tjänsten utvärderas en korrekt auktoriserad begäran som görs till tjänsten från en annan domän för att avgöra om den tillåts enligt den regel som du har angett. Till exempel:

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
    "cors": {
      "corsRules": [
        {
          "allowedOrigins": [
            "https://www.azure.com",
            "https://www.microsoft.com"
          ]
        }
      ]
    }
  }
}

Endast en CORS-regel med sin lista över tillåtna ursprung kan anges. Varje ursprung gör att HTTP-begäran kan göras till Azure Maps REST API i webbläsaren för det angivna ursprunget.

Ta bort CORS-princip

Du kan ta bort CORS:

• Manuellt i Azure Portal
• Programmatiskt med hjälp av:
  • The Azure Maps SDK
  • REST API för Azure Maps-hantering
  • En ARM-mall

{
  "location": "eastus",
  "sku": {
    "name": "G2"
  },
  "kind": "Gen2",
  "properties": {
        "cors": {
          "corsRules": []
        }
    }
  }
}

Förstå faktureringstransaktioner

Azure Maps räknar inte faktureringstransaktioner för:

• 5xx HTTP-statuskoder
• 401 (behörighet saknas)
• 403 (Förbjudet)
• 408 (tidsgräns)
• 429 (TooManyRequests)
• CORS-förhandsbegäranden

Mer information om faktureringstransaktioner och annan prisinformation för Azure Maps finns i Priser för Azure Maps.

Nästa steg

Mer information om metodtips för säkerhet finns i:

Mer information om hur du autentiserar ett program med Microsoft Entra-ID och Azure Maps finns i:

Mer information om hur du autentiserar Azure Maps Control med Microsoft Entra-ID finns i: