Verificatie met Azure Maps

Azure Maps ondersteunt drie verificatiemethoden: Shared Key, Microsoft Entra ID en SAS-token (Shared Access Signature). In dit artikel worden deze verificatiemethoden uitgelegd, waaronder details over accountbesturingselementen, zoals het uitschakelen van lokale verificatie voor Azure Policy en Cross-Origin Resource Sharing (CORS).

Verificatie met gedeelde sleutels

Zie Verificatiedetails weergeven voor meer informatie over het weergeven van uw sleutels in Azure Portal.

Primaire en secundaire sleutels worden automatisch gegenereerd bij het maken van een Azure Maps-account. U wordt aangeraden om de primaire sleutel als abonnementssleutel te gebruiken bij het aanroepen van Azure Maps met verificatie met gedeelde sleutels. Verificatie met gedeelde sleutels geeft een sleutel die door een Azure Maps-account wordt gegenereerd door aan een Azure Maps-service. Voor elke aanvraag bij Azure Maps-services voegt u de abonnementssleutel toe als parameter aan de URL. De secundaire sleutel kan worden gebruikt in scenario's zoals het dynamisch wijzigen van sleutels.

Voorbeeld van het gebruik van de abonnementssleutel als een parameter in uw 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

Microsoft Entra-authenticatie

Azure-abonnementen worden geleverd met een Microsoft Entra-tenant om gedetailleerd toegangsbeheer mogelijk te maken. Azure Maps biedt verificatie voor Azure Maps-services met behulp van Microsoft Entra ID. Microsoft Entra ID biedt verificatie op basis van identiteiten voor gebruikers en toepassingen die zijn geregistreerd in de Microsoft Entra-tenant.

Azure Maps accepteert OAuth 2.0-toegangstokens voor Microsoft Entra-tenants die zijn gekoppeld aan een Azure-abonnement dat een Azure Maps-account bevat. Azure Maps accepteert ook tokens voor:

• Microsoft Entra-gebruikers
• Partnertoepassingen die gebruikmaken van machtigingen die zijn gedelegeerd door gebruikers
• Beheerde identiteiten voor Azure-resources

Azure Maps genereert een unieke id (client-id ) voor elk Azure Maps-account. U kunt tokens aanvragen bij Microsoft Entra ID wanneer u deze client-id combineert met andere parameters.

Zie Verificatie beheren in Azure Maps voor meer informatie over het configureren van Microsoft Entra-id en aanvraagtokens voor Azure Maps.

Zie Verificatie versus autorisatie voor algemene informatie over verificatie met Microsoft Entra-id.

Beheerde identiteiten voor Azure-resources en Azure Maps

Beheerde identiteiten voor Azure-resources bieden Azure-services met een automatisch beheerde beveiligingsprincipaal op basis van toepassingen die kunnen worden geverifieerd met Microsoft Entra-id. Met op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) kan de principal voor beveiliging van beheerde identiteiten worden geautoriseerd voor toegang tot Azure Maps-services. Enkele voorbeelden van beheerde identiteiten zijn: Azure-app Service, Azure Functions en Azure Virtual Machines. Zie Azure-services die beheerde identiteiten kunnen gebruiken voor toegang tot andere services voor een lijst met beheerde identiteiten. Zie Verificatie beheren in Azure Maps voor meer informatie over beheerde identiteiten.

Microsoft Entra-verificatie voor toepassingen configureren

Toepassingen worden geverifieerd met de Microsoft Entra-tenant met behulp van een of meer ondersteunde scenario's van Microsoft Entra ID. Elk Microsoft Entra-toepassingsscenario vertegenwoordigt verschillende vereisten op basis van bedrijfsbehoeften. Sommige toepassingen vereisen mogelijk een aanmeldingsproces voor gebruikers en andere applicaties vereisen mogelijk een aanmeldingsproces voor applicaties. Zie Verificatiestromen en toepassingsscenario's voor meer informatie.

Nadat de toepassing een toegangstoken heeft ontvangen, verzendt de SDK en/of toepassing een HTTPS-aanvraag met de volgende set vereiste HTTP-headers, naast andere HTTP-headers van de REST API:

Hier volgt een voorbeeld van een Azure Maps Route-aanvraag die gebruikmaakt van een 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

Zie Verificatiedetails weergeven voor meer informatie over het weergeven van uw client-id.

$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

Autorisatie met op rollen gebaseerd toegangsbeheer

Vereisten

Als u niet bekend bent met Azure RBAC, biedt de overzichtspagina van Azure rolgebaseerde toegangscontrole (Azure RBAC) informatie over principaltypes die een set machtigingen, ook wel een roldefinitie genoemd, verleend krijgen. Een roldefinitie biedt machtigingen voor REST API-acties. Azure Maps ondersteunt toegang tot alle principaltypen voor op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC), waaronder afzonderlijke Microsoft Entra-gebruikers, groepen, toepassingen, Azure-resources en door Azure beheerde identiteiten. Het toepassen van toegang tot een of meer Azure Maps-accounts wordt een scope genoemd. Er wordt een roltoewijzing gemaakt wanneer een principal, roldefinitie en bereik worden toegepast.

Overzicht

In de volgende secties worden concepten en onderdelen van Azure Maps-integratie met Azure RBAC besproken. Als onderdeel van het proces voor het instellen van uw Azure Maps-account wordt een Microsoft Entra-directory gekoppeld aan het Azure-abonnement waarin het Azure Maps-account zich bevindt.

Wanneer u Azure RBAC configureert, kiest u een beveiligingsprincipaal en past u deze toe op een roltoewijzing. Zie Azure-rollen toewijzen met behulp van Azure Portal voor meer informatie over het toevoegen van roltoewijzingen in Azure Portal.

Een roldefinitie kiezen

De volgende roldefinitietypen bestaan ter ondersteuning van toepassingsscenario's.

Voor sommige Azure Maps-services zijn verhoogde bevoegdheden vereist voor het uitvoeren van schrijf- of verwijderacties op Azure Maps REST API's. De rol Azure Maps Data Contributor is vereist voor services die schrijf- of verwijderacties bieden. In de volgende tabel wordt beschreven welke services Azure Maps Data Contributor van toepassing is bij het gebruik van schrijf- of verwijderacties. Wanneer alleen leesacties vereist zijn, kan de rol Gegevenslezer van Azure Maps worden gebruikt in plaats van de rol Inzender voor Azure Maps-gegevens.

Zie Azure RBAC configureren voor Azure Maps voor informatie over het weergeven van uw Azure RBAC-instellingen.

Aangepaste roldefinities

Een aspect van toepassingsbeveiliging is het principe van minimale bevoegdheden, de praktijk van het beperken van toegangsrechten tot de rechten die vereist zijn voor de huidige taak. Het beperken van toegangsrechten wordt bereikt door aangepaste roldefinities te maken die ondersteuning bieden voor use cases waarvoor verdere granulariteit nodig is voor toegangsbeheer. Als u een aangepaste roldefinitie wilt maken, selecteert u specifieke gegevensacties die u wilt opnemen of uitsluiten voor de definitie.

De aangepaste roldefinitie kan vervolgens worden gebruikt in een roltoewijzing voor elke beveiligingsentiteit. Zie aangepaste Azure-rollen voor meer informatie over aangepaste Azure-roldefinities.

Hier volgen enkele voorbeeldscenario's waarin aangepaste rollen de beveiliging van toepassingen kunnen verbeteren.

Begrijp de scope

Roltoewijzingen worden gedefinieerd in de Azure-resourcehiërarchie, van de beheergroep op het hoogste niveau tot het laagste niveau, zoals een Azure Maps-account. Zie Wat zijn Azure-beheergroepen? voor meer informatie.

Door een rol toe te wijzen aan een resourcegroep, kunt u toegang verlenen tot meerdere Azure Maps-accounts of -resources binnen die groep.

Lokale verificatie uitschakelen

Azure Maps-accounts ondersteunen de standaardeigenschap van Azure in de Maps Management-API voor Microsoft.Maps/accounts genaamd disableLocalAuth. Indien waar, wordt alle verificatie voor de REST API voor het gegevensvlak van Azure Maps uitgeschakeld, met uitzondering van Microsoft Entra-verificatie. Dit wordt geconfigureerd met behulp van Azure Policy om distributie en beheer van gedeelde sleutels en SAS-tokens te beheren. Zie Wat is Azure Policy? voor meer informatie.

Het uitschakelen van lokale verificatie wordt niet onmiddellijk van kracht. Wacht enkele minuten voordat de service toekomstige verificatieaanvragen blokkeert. Als u lokale verificatie opnieuw wilt inschakelen, stelt u de eigenschap in op false en na een paar minuten wordt de lokale verificatie hervat.

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

Shared Access Signature-tokenverificatie

SAS-tokens (Shared Access Signature), die authenticatietokens zijn in de JWT-indeling (JSON Web Token), worden cryptografisch ondertekend om toepassingen te verifiëren met de REST API van Azure Maps. Deze tokens worden gegenereerd door een door de gebruiker toegewezen beheerde identiteit te integreren met een Azure Maps-account in uw Azure-abonnement. De beheerde identiteit is gemachtigd voor toegang tot het Azure Maps-account via Azure RBAC, met behulp van ingebouwde of aangepaste roldefinities.

Belangrijke functionele verschillen tussen SAS-tokens en Microsoft Entra-toegangstokens:

• Levensduur van een token voor een maximale vervaldatum van één dag (24 uur).
• Azure-locatie en geografietoegangsbeheer per token.
• Frequentielimieten per token voor ongeveer 1 tot 500 aanvragen per seconde.
• Persoonlijke sleutels van het token zijn de primaire en secundaire sleutels van een Azure Maps-accountresource.
• Service-principalobject voor autorisatie wordt geleverd door een door de gebruiker toegewezen beheerde identiteit.

SAS-tokens zijn onveranderbaar. Zodra ze zijn gemaakt, blijven ze geldig totdat ze verlopen en kunnen hun instellingen, zoals toegestane regio's, frequentielimieten en door de gebruiker toegewezen beheerde identiteit, niet worden gewijzigd. Zie inzicht in toegangsbeheer voor meer informatie over het intrekken van SAS-token en wijzigingen in toegangsbeheer.

Inzicht in frequentielimieten voor SAS-tokens

Maximale frequentielimiet voor SAS-token kan de facturering voor een Azure Maps-resource beheren

Wanneer u een maximale frequentielimiet instelt voor het token (maxRatePerSecond), worden alle tarieven die deze limiet overschrijden niet in rekening gebracht voor het account, zodat u factureerbare transacties kunt beperken. De toepassing ontvangt echter clientfout 429 (TooManyRequests) antwoorden voor alle transacties zodra de limiet is bereikt. Het is de verantwoordelijkheid van de toepassing om nieuwe pogingen te beheren en SAS-tokens te distribueren. Er is geen beperking voor het aantal SAS-tokens dat kan worden gemaakt voor een account. Als u de limiet van een bestaand token wilt wijzigen, moet er een nieuw SAS-token worden gegenereerd. Het oude SAS-token blijft geldig totdat het verloopt.

Geschat voorbeeld:

De werkelijke frequentielimieten variëren op basis van de mogelijkheid van Azure Maps om consistentie binnen een bepaalde tijd af te dwingen. Dit biedt echter preventieve controle over de factureringskosten.

Frequentielimieten worden afgedwongen per Azure-locatie, niet globaal of geografisch

Eén SAS-token met een maxRatePerSecond van de 10 kan bijvoorbeeld worden gebruikt om de doorvoer op de East US locatie te beperken. Als hetzelfde token in West US 2 wordt gebruikt, wordt er een nieuwe teller gemaakt om de doorvoer te beperken tot 10 op die locatie, onafhankelijk van de locatie van East US. Suggesties voor het beheren van kosten en het verbeteren van de voorspelbaarheid:

1. Maak SAS-tokens met toegewezen en toegestane Azure-locaties voor gerichte geografie.
2. Gebruik REST API-eindpunten voor geografische datavlakken, of https://us.atlas.microsoft.comhttps://eu.atlas.microsoft.com.

Houd rekening met de toepassingstopologie waarbij het eindpunt https://us.atlas.microsoft.com wordt gerouteerd naar dezelfde Amerikaanse locaties waarop de Azure Maps-services worden gehost, zoals East US, West Central USof West US 2. Hetzelfde idee is van toepassing op andere geografische eindpunten, zoals https://eu.atlas.microsoft.com tussen West Europe en North Europe. Gebruik om onverwachte autorisatieproblemen te voorkomen een SAS-token dat gebruikmaakt van dezelfde Azure-locaties als de applicatie. De eindpuntlocatie wordt gedefinieerd met behulp van de AZURE Maps Management REST API.

Standaardfrequentielimieten hebben voorrang boven SAS-tokenfrequentielimieten

Zoals beschreven in QPS-frequentielimieten in Azure Maps, worden de frequentielimieten voor afzonderlijke serviceaanbiedingen gezamenlijk afgedwongen op accountniveau.

Houd rekening met het geval van de Search-service: één aanvraag omgekeerd, met de limiet van 250 query's per seconde (QPS) voor de volgende tabellen. Elke tabel vertegenwoordigt geschatte totale geslaagde transacties uit voorbeeldgebruik.

In de eerste tabel ziet u één token met een maximumaanvraag per seconde van 500 en het werkelijke gebruik van de toepassing is 500 aanvraag per seconde voor een duur van 60 seconden. Zoekservice: één aanvraag omgekeerd heeft een snelheidslimiet van 250, wat betekent dat het totaal 30.000 aanvragen in de 60 seconden is gedaan; 15.000 van deze aanvragen zijn factureerbare transacties. De resterende aanvragen resulteren in statuscode 429 (TooManyRequests).

Als bijvoorbeeld twee SAS-tokens worden gemaakt en dezelfde locatie gebruiken als een Azure Maps-account, deelt elk token de standaardfrequentielimiet van 250 QPS. Als beide tokens tegelijkertijd met dezelfde doorvoer worden gebruikt, verleent elk token 7500 geslaagde transacties.

Toegangsbeheer voor SAS-token begrijpen

SAS-tokens gebruiken RBAC om de toegang tot de REST API te beheren. Wanneer u een SAS-token maakt, wordt aan de vereiste beheerde identiteit binnen het Map-account een Azure RBAC-rol toegewezen die toegang biedt tot specifieke REST API-acties. Zie Een roldefinitie kiezen om te bepalen welke API's de toepassing toestaat.

Als u tijdelijke toegang wilt toewijzen en wilt verwijderen voordat het SAS-token verloopt, trekt u het token in. Een andere reden om de toegang in te trekken, is als het token onbedoeld is gedistribueerd met de rol Inzender voor Azure Maps-gegevens, waardoor onbevoegde gegevens kunnen worden gelezen/geschreven in Azure Maps REST API's, wat leidt tot blootstelling aan gevoelige gegevens of onverwachte kosten.

Er zijn twee opties om de toegang voor SAS-tokens in te trekken:

1. Genereer de sleutel die was gebruikt door het SAS-token of de secundaire sleutel van het kaartaccount opnieuw.
2. Verwijder de roltoewijzing voor de beheerde identiteit op het gekoppelde kaartprofiel.

SAS-tokens maken

Als u SAS-tokens wilt maken, moet u roltoegang hebben Contributor voor het beheren van Azure Maps-accounts en door de gebruiker toegewezen identiteiten in het Azure-abonnement.

Eerst moet u een door de gebruiker toegewezen beheerde identiteit maken op dezelfde locatie als het Azure Maps-account.

Zodra een beheerde identiteit is gemaakt, kunt u het Azure Maps-account maken of bijwerken en koppelen. Zie Uw Azure Maps-account beheren voor meer informatie.

Zodra het account met de beheerde identiteit is aangemaakt of bijgewerkt, wijs rolgebaseerde toegangscontrole voor de beheerde identiteit toe aan een Azure Maps-gegevensrol op accountniveau. Hierdoor kan de beheerde identiteit toegang krijgen tot de Rest API van Azure Maps voor uw kaartaccount.

Maak vervolgens een SAS-token aan met behulp van de Azure Management SDK-hulpprogramma's, de List SAS-bewerking van de accountbeheer-API of de Shared Access Signature-pagina van de mapaccountresource in het Azure-portaal.

SAS-tokenparameters:

Toepassing configureren met SAS-token

Nadat de toepassing een SAS-token heeft ontvangen, verzenden de Azure Maps SDK en/of toepassingen een HTTPS-aanvraag met de volgende vereiste HTTP-header naast andere REST API HTTP-headers:

Cors (Cross Origin Resource Sharing)

CORS is een HTTP-protocol waarmee een webtoepassing die onder het ene domein wordt uitgevoerd, toegang heeft tot resources in een ander domein. Webbrowsers implementeren een beveiligingsbeperking die bekend staat als beleid voor dezelfde oorsprong waarmee wordt voorkomen dat een webpagina API's in een ander domein aanroept; CORS biedt een veilige manier om toe te staan dat één domein (het oorspronkelijke domein) API's in een ander domein aanroept. Met behulp van de Azure Maps-accountresource kunt u configureren welke oorsprongen toegang hebben tot de Azure Maps REST API van uw toepassingen.

Vereisten

Om te voorkomen dat schadelijke code wordt uitgevoerd op de client, blokkeren moderne browsers aanvragen van webtoepassingen naar resources die in een afzonderlijk domein worden uitgevoerd.

• Als u niet bekend bent met CORS, raadpleeg dan Cross-origin resource sharing (CORS). Hiermee kan een Access-Control-Allow-Origin-header aangeven welke origins de eindpunten van een Azure Maps-account mogen aanroepen. HET CORS-protocol is niet specifiek voor Azure Maps.

CORS-aanvragen

Een CORS-aanvraag van een oorspronkelijk domein kan bestaan uit twee afzonderlijke aanvragen:

• Een preflight-aanvraag, die de CORS-beperkingen opvraagt die door de service worden opgelegd. De voorbereidende aanvraag is vereist, tenzij de aanvraag een standaardmethode als GET, HEAD, POST is, of als er aanvraagheaders bij de aanvraag zitten Authorization.

• De werkelijke aanvraag, gemaakt op basis van de gewenste resource.

Voorbereidende aanvraag

Het preflightverzoek is een beveiligingsmaatregel, maar zorgt er ook voor dat de server de methode en headers begrijpt die in het daadwerkelijke verzoek worden verzonden, controleert de bron van het verzoek en controleert de CORS-beperkingen die zijn vastgesteld voor het kaartaccount. De webbrowser (of een andere gebruikersagent) verzendt een OPTIONS-aanvraag met de aanvraagheaders, de methode en het oorspronkelijke domein. De kaartaccountservice probeert CORS-regels op te halen als accountverificatie mogelijk is via het preflight-protocol van CORS.

Als verificatie niet mogelijk is, evalueert de maps-service een vooraf geconfigureerde set CORS-regels waarmee wordt opgegeven welke oorspronkelijke domeinen, aanvraagmethoden en aanvraagheaders kunnen worden opgegeven voor een werkelijke aanvraag voor de maps-service. Standaard is een maps-account zo geconfigureerd dat alle origins naadloze integratie in webbrowsers mogelijk maken.

De service reageert op de preflight-aanvraag met de vereiste Access-Control headers als aan de volgende criteria wordt voldaan.

1. De OPTIONS-aanvraag bevat de vereiste CORS-headers (de headers Origin en Access-Control-Request-Method)
2. Authenticatie is geslaagd en een CORS-regel is ingeschakeld voor het account dat overeenkomt met het preflight-verzoek.
3. Verificatie is overgeslagen vanwege vereiste Authorization aanvraagheaders die niet kunnen worden opgegeven bij de voorbereidende aanvraag.

Wanneer de voorbereidende aanvraag is geslaagd, reageert de service met statuscode 200 (OK), en bevat het antwoord de vereiste Access-Control-headers.

De service weigert voorbereidende aanvragen als de volgende voorwaarden optreden:

1. Als de OPTIONS-aanvraag niet de vereiste CORS-headers bevat (de headers Origin en Access-Control-Request-Method), reageert de service met statuscode 400 (Bad request).
2. Als de verificatie is geslaagd bij de voorbereidende aanvraag en er geen CORS-regel overeenkomt met de voorbereidende aanvraag, reageert de service met statuscode 403 (Forbidden). Dit kan gebeuren als de CORS-regel is geconfigureerd voor het accepteren van een oorsprong die niet overeenkomt met de aanvraagheader van de huidige browserclient.

Werkelijke aanvraag

Zodra de voorbereidende aanvraag is geaccepteerd en het antwoord wordt geretourneerd, verzendt de browser de daadwerkelijke aanvraag naar de kaartservice. De browser weigert het echte verzoek onmiddellijk als de voorafgaande aanvraag wordt geweigerd.

De werkelijke aanvraag wordt behandeld als een normale aanvraag voor de kaartendienst. De aanwezigheid van de Origin header geeft aan dat de aanvraag een CORS-aanvraag is en dat de service vervolgens wordt gevalideerd op basis van de CORS-regels. Als er een overeenkomst wordt gevonden, worden de access-control-headers toegevoegd aan het antwoord en teruggestuurd naar de client. Als er geen overeenkomst wordt gevonden, retourneert het antwoord een 403 (Forbidden) CORS-oorsprongsfout.

CORS-beleid inschakelen

Wanneer een Map-account wordt aangemaakt of bijgewerkt, bepalen de eigenschappen ervan de toegestane origines. Een CORS-regel kan worden ingesteld op de eigenschappen van het Azure Maps-account via de Azure Maps Management SDK, Azure Maps Management REST API en portal. Nadat u de CORS-regel voor de service hebt ingesteld, worden geautoriseerde aanvragen van verschillende domeinen geëvalueerd om ervoor te zorgen dat de opgegeven regel wordt nageleefd. Voorbeeld:

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

Er kan slechts één CORS-regel met de lijst met toegestane oorsprongen worden opgegeven. Met elke oorsprong kan de HTTP-aanvraag worden gedaan naar azure Maps REST API in de webbrowser van de opgegeven oorsprong.

CORS-beleid verwijderen

U kunt CORS verwijderen:

• Handmatig in de Azure-portal
• Programmatisch met behulp van:
  • De Azure Maps SDK
  • REST API voor Azure Maps-beheer
  • Een ARM-sjabloon

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

Begrijp factureringstransacties

Azure Maps telt geen factureringstransacties voor:

• HTTP-statuscodes uit de 5xx-serie
• 401 (Niet geautoriseerd)
• 403 (verboden)
• 408 (time-out)
• 429 (Te veel aanvragen)
• Voorafgaande CORS-aanvragen

Zie Prijzen van Azure Maps voor meer informatie over factureringstransacties en andere prijzen van Azure Maps.

Volgende stappen

Zie voor meer informatie over aanbevolen beveiligingsprocedures:

Zie voor meer informatie over het verifiëren van een toepassing met Microsoft Entra ID en Azure Maps:

Zie voor meer informatie over het verifiëren van Azure Maps Control met Microsoft Entra ID: