Freigeben über

Authentifizierung mit Azure Maps

  • Artikel

Azure Maps unterstützt drei Möglichkeiten zur Authentifizierung von Anforderungen: Freigegebene Schlüssel-Authentifizierung, Microsoft Entra ID-Authentifizierung und Gemeinsame Zugriffssignatur (SAS) Token-Authentifizierung. Dieser Artikel erklärt die Authentifizierungsmethoden, um Sie bei der Implementierung von Azure Maps-Diensten zu unterstützen. Der Artikel beschreibt auch andere Kontosteuerungen wie das Deaktivieren der lokalen Authentifizierung für Azure Policy und Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS).

Hinweis

Um die sichere Kommunikation mit Azure Maps zu verbessern, unterstützen wir nun TLS 1.2 (Transport Layer Security), und wir stellen die Unterstützung für TLS 1.0 und 1.1 ein. Wenn Sie derzeit TLS 1.x verwenden, evaluieren Sie Ihre TLS 1.2-Bereitschaft, und entwickeln Sie einen Migrationsplan mit den in Lösen des TLS 1.0-Problems beschriebenen Tests.

Authentifizierung mit gemeinsam verwendetem Schlüssel

Informationen zum Anzeigen Ihrer Schlüssel im Azure-Portal finden Sie unter Anzeigen der Authentifizierungsdetails.

Nach dem Erstellen des Azure Maps-Kontos werden der Primär- und der Sekundärschlüssel generiert. Sie sollten den Primärschlüssel als Abonnementschlüssel verwenden, wenn Sie Azure Maps mithilfe der Authentifizierung mit gemeinsam verwendetem Schlüssel aufrufen. Bei der Authentifizierung mit einem gemeinsam verwendeten Schlüssel wird ein von einem Azure Maps-Konto generierter Schlüssel an einen Azure Maps-Dienst übergeben. Fügen Sie für jede Anforderung, die an Azure Maps-Dienste gesendet wird, der URL den Abonnementschlüssel als Parameter hinzu. Der Sekundärschlüssel kann in Szenarien wie Änderungen beim Schlüsselrollover verwendet werden.

Beispiel für die Verwendung des Abonnementschlüssels als Parameter in Ihrer 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

Wichtig

Primär- und Sekundärschlüssel sollten als vertrauliche Daten behandelt werden. Der freigegebene Schlüssel wird verwendet, um jede Azure Maps REST-API zu authentifizieren. Benutzer, die einen gemeinsam verwendeten Schlüssel verwenden, sollten den API-Schlüssel wegabstrahieren, entweder über Umgebungsvariablen oder den sicheren Geheimspeicher, wo er zentral verwaltet werden kann.

Microsoft Entra-Authentifizierung

Azure-Abonnements werden mit einem Microsoft Entra-Mandanten bereitgestellt, um eine differenzierte Zugriffssteuerung zu ermöglichen. Azure Maps bietet Authentifizierung für Azure Maps-Dienste unter Verwendung von Microsoft Entra ID. Microsoft Entra ID bietet identitätsbasierte Authentifizierung für Benutzer und Anwendungen, die im Microsoft Entra-Mandanten registriert sind.

Azure Maps akzeptiert OAuth 2.0-Zugriffstoken für Microsoft Entra-Mandanten, die einem Azure-Abonnement zugeordnet sind, in dem ein Azure Maps-Konto enthalten ist. Azure Maps akzeptiert auch Token für:

  • Microsoft Entra-Benutzer
  • Partneranwendungen, für die von Benutzern delegierte Berechtigungen verwendet werden
  • Verwaltete Identitäten für Azure-Ressourcen

Azure Maps generiert einen eindeutigen Bezeichner (Client-ID) für jedes Azure Maps-Konto. Sie können Token von Microsoft Entra ID anfordern, wenn Sie diese Client-ID mit anderen Parametern kombinieren.

Weitere Informationen zum Konfigurieren von Microsoft Entra ID und Anforderungstoken für Azure Maps finden Sie unter Verwalten der Authentifizierung in Azure Maps.

Allgemeine Informationen zur Authentifizierung mit Microsoft Entra ID finden Sie unter Authentifizierung im Vergleich mit Autorisierung.

Verwaltete Identitäten für Azure-Ressourcen und Azure Maps

Verwaltete Identitäten für Azure-Ressourcen stellen Azure-Diensten einen automatisch verwalteten anwendungsbasierten Sicherheitsprinzipal bereit, der sich bei Microsoft Entra ID authentifizieren kann. Mit der rollenbasierten Zugriffssteuerung von Azure (Azure Role-Based Access Control, Azure RBAC) kann der Sicherheitsprinzipal der verwalteten Identität für den Zugriff auf Azure Maps-Dienste autorisiert werden. Beispiele für verwaltete Identitäten sind: Azure App Service, Azure Functions und Azure Virtual Machines. Dine Liste der verwalteten Identitäten finden Sie unter Azure-Dienste, die verwaltete Identitäten für den Zugriff auf andere Dienste verwenden können. Weitere Informationen zu verwalteten Identitäten finden Sie unter Verwalten der Authentifizierung in Azure Maps.

Konfigurieren der Microsoft Entra-Authentifizierung der Anwendung

Anwendungen authentifizieren sich beim Microsoft Entra-Mandanten mithilfe eines oder mehrerer unterstützter Szenarien, die von Microsoft Entra ID bereitgestellt werden. Jedes Microsoft Entra-Anwendungsszenario repräsentiert verschiedene Anforderungen auf der Grundlage der geschäftlichen Anforderungen. Für einige Anwendungen ist möglicherweise eine Benutzeranmeldungserfahrung erforderlich, während für andere Anwendungen eventuell eine Anwendungsanmeldungserfahrung erforderlich ist. Weitere Informationen finden Sie unter Authentifizierungsflows und Anwendungsszenarien.

Nachdem die Anwendung ein Zugriffstoken erhalten hat, sendet das SDK und/oder die Anwendung eine HTTPS-Anforderung mit den folgenden erforderlichen HTTP-Headern zusätzlich zu anderen REST-API-HTTP-Headern:

Headername Wert
x-ms-client-id 30d7cc…9f55
Autorisierung Bearer eyJ0e…HNIVN

Hinweis

x-ms-client-id ist die auf dem Azure Maps-Konto basierende GUID, die auf der Azure Maps-Authentifizierungsseite angezeigt wird.

Hier ist ein Beispiel für eine Azure Maps-Routenanforderung, die ein Microsoft Entra ID-OAuth-Bearertoken verwendet:

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

Weitere Informationen zum Anzeigen Ihrer Client-ID finden Sie unter Anzeigen von Authentifizierungsdetails.

Tipp

Client-ID programmgesteuert abrufen

Bei Verwendung von PowerShell wird die Client-ID als UniqueIdEigenschaft im IMapsAccountObjekt gespeichert. Sie rufen diese Eigenschaft mit Get-AzMapsAccount ab, zum Beispiel:

$maps = Get-AzMapsAccount -Name {Azure-Maps_Account-Name} -ResourceGroupName {Resource-Group-Name} -SubscriptionId {SubscriptionId}
$ClientId = $maps.UniqueId

Verwenden Sie bei Verwendung der Azure-Befehlszeilenschnittstelle den Befehl az maps account show mit dem Parameter --query, zum Beispiel:

$ClientId = az maps account show --name {Azure-Maps_Account-Name} --resource-group {Resource-Group-Name} --subscription {SubscriptionId} --query properties.uniqueId

Autorisierung mit rollenbasierter Zugriffssteuerung

Voraussetzungen

Wenn Sie neu bei Azure RBAC sind, finden Sie unter Was ist die rollenbasierte Zugriffssteuerung in Azure (Azure Role-Based Access Control, Azure RBAC)? eine Übersicht. Prinzipaltypen wird eine Reihe von Berechtigungen erteilt, die auch als Rollendefinition bezeichnet werden. Eine Rollendefinition bietet Berechtigungen für REST-API-Aktionen. Azure Maps unterstützt den Zugriff auf alle Prinzipaltypen für die rollenbasierte Zugriffssteuerung in Azure (Azure RBAC), einschließlich einzelner Microsoft Entra-Benutzer, -Gruppen und -Anwendungen, Azure-Ressourcen sowie verwalteter Azure-Identitäten. Das Anwenden des Zugriffs auf ein oder mehrere Azure Maps-Konten wird als Bereich bezeichnet. Eine Rollenzuweisung wird durch das Anwenden eines Prinzipals, einer Rollendefinition und eines Bereichs erstellt.

Übersicht

In den nächsten Abschnitten werden die Konzepte und Komponenten der Azure Maps-Integration mit Azure RBAC diskutiert. Im Rahmen des Prozesses zum Einrichten Ihres Azure Maps-Kontos wird ein Microsoft Entra-Verzeichnis dem Azure-Abonnement zugeordnet, in dem sich das Azure Maps-Konto befindet.

Wenn Sie Azure RBAC konfigurieren, wählen Sie einen Sicherheitsprinzipal aus und wenden ihn auf eine Rollenzuweisung an. Informationen zum Hinzufügen von Rollenzuweisungen im Azure-Portal finden Sie unter Zuweisen von Azure-Rollen mit dem Azure-Portal.

Auswählen einer Rollendefinition

Die folgenden Rollendefinitionstypen sind für die Unterstützung von Anwendungsszenarien vorhanden.

Azure-Rollendefinition BESCHREIBUNG
Datenleser für Azure Maps Such- und Renderdaten Bietet nur Zugriff zum Suchen und Rendern von Azure Maps-REST-APIs, um den Zugriff auf grundlegende Webbrowser-Anwendungsfälle zu beschränken.
Azure Maps-Datenleser Bietet Zugriff auf unveränderliche Azure Maps-REST-APIs.
Azure Maps-Datenmitwirkender Bietet Zugriff auf veränderliche Azure Maps-REST-APIs. Veränderlichkeit, definiert durch die Aktionen: schreiben und löschen.
Azure Maps-Rolle für Datenlese- und Batchaktionen Diese Rolle kann verwendet werden, um Lese- und Batchaktionen für Azure Maps zuzuweisen.
Benutzerdefinierte Rollendefinition Erstellen Sie eine gefertigte Rolle, um flexiblen eingeschränkten Zugriff auf Azure Maps-REST-APIs zu ermöglichen.

Einige Azure Maps-Dienste benötigen möglicherweise erhöhte Berechtigungen, um Schreib- oder Löschaktionen an Azure Maps-REST-APIs auszuführen. Die Rolle „Azure Maps-Datenmitwirkender“ ist für Dienste erforderlich, die Schreib- oder Löschaktionen bereitstellen. In der folgenden Tabelle wird beschrieben, für welche Dienste „Azure Maps-Datenmitwirkender“ gilt, wenn Schreib- oder Lösch Aktionen verwendet werden. Wenn nur Leseaktionen erforderlich sind, kann die Rolle „Azure Maps-Datenleser“ anstelle der Rolle „Azure Maps-Datenmitwirkender“ verwendet werden.

Azure Maps-Dienst Azure Maps-Rollendefinition
Creator (veraltet1) Azure Maps-Datenmitwirkender
Spatial (veraltet1) Azure Maps-Datenmitwirkender
Batch Suche und Route Azure Maps-Datenmitwirkender

1 Azure Maps Creator, die Datenregistrierung und Spatial sind veraltet und werden am 30. September 2025 eingestellt.

Informationen zum Anzeigen Ihrer Azure RBAC-Einstellungen finden Sie im Artikel zum Thema Konfigurieren von Azure RBAC für Azure Maps.

Benutzerdefinierte Rollendefinitionen

Ein Aspekt der Anwendungssicherheit ist das Prinzip der geringsten Rechte, d. h. die Beschränkung der Zugriffsrechte auf die für die aktuelle Aufgabe erforderlichen Rechte. Das Einschränken der Zugriffsrechte wird erreicht durch das Erstellen benutzerdefinierter Rollendefinitionen, die Anwendungsfälle unterstützen, die eine weitere Granularität für die Zugriffssteuerung erfordern. Um eine benutzerdefinierte Rollendefinition zu erstellen, wählen Sie bestimmte Datenaktionen aus, die in die Definition aufgenommen oder daraus ausgeschlossen werden sollen.

Die benutzerdefinierte Rollendefinition kann dann für jeden Sicherheitsprinzipal in einer Rollenzuweisung verwendet werden. Weitere Informationen zu benutzerdefinierten Azure-Rollendefinitionen finden Sie unter Benutzerdefinierte Azure-Rollen.

Hier finden Sie einige Beispielszenarien, in denen benutzerdefinierte Rollen die Anwendungssicherheit verbessern können.

Szenario Datenaktion(en) für benutzerdefinierte Rollen
Eine öffentliche oder interaktive Anmeldewebseite mit Basiskartenkacheln und keinen anderen REST-APIs. Microsoft.Maps/accounts/services/render/read
Eine Anwendung, die nur umgekehrte Geocodierung und keine anderen REST-APIs erfordert Microsoft.Maps/accounts/services/search/read
Eine Rolle für einen Sicherheitsprinzipal, der das Lesen von Azure Maps Creator-basierten Kartendaten und REST-APIs von Basiskartenkacheln anfordert. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/read
Eine Rolle für einen Sicherheitsprinzipal, der das Lesen, Schreiben und Löschen von Creator-basierten Kartendaten erfordert. Definiert als Rolle „Kartendateneditor“, die keinen Zugriff auf andere REST-APIs wie Basiskartenkacheln erlaubt. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/delete

Der Bereich

Beim Erstellen einer Rollenzuweisung wird sie in der Azure-Ressourcenhierarchie definiert. Die oberste Ebene der Hierarchie ist eine Verwaltungsgruppe, und die niedrigste Ebene ist eine Azure-Ressource wie ein Azure Maps-Konto. Wenn Sie einer Ressourcengruppe eine Rollenzuweisung zuweisen, kann dies den Zugriff auf mehrere Azure Maps-Konten oder -Ressourcen in der Gruppe aktivieren.

Tipp

Die generelle Empfehlung von Microsoft besteht darin, den Zugriff auf den Bereich des Azure Maps-Kontos zuzuweisen, weil dadurch unbeabsichtigter Zugriff auf andere Azure Maps-Konten, die sich im selben Azure-Abonnement befinden, verhindert wird.

Deaktivieren der lokalen Authentifizierung

Azure Maps-Konten unterstützen die Azure-Standardeigenschaft in der Management-API für Microsoft.Maps/accounts mit Namen disableLocalAuth. Bei true wird die gesamte Authentifizierung mit der REST-API für die Azure Maps-Datenebene deaktiviert, mit Ausnahme von Microsoft Entra-Authentifizierung. Dies wird mithilfe von Azure Policy konfiguriert, um die Verteilung und Verwaltung von freigegebenen Schlüsseln und SAS-Token zu steuern. Weitere Informationen finden Sie unter Was ist Azure Policy?.

Das Deaktivieren der lokalen Authentifizierung tritt nicht sofort in Kraft. Warten Sie einige Minuten, bis der Dienst zukünftige Authentifizierungsanforderungen blockiert. Um die lokale Authentifizierung wieder zu aktivieren, setzen Sie die Eigenschaft auf false, und nach einigen Minuten wird die lokale Authentifizierung fortgesetzt.

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

SAS-Token-Authentifizierung

Shared Access Signature (SAS)-Token sind Authentifizierungstoken, die mit dem JSON-Webtoken-Format (JWT) erstellt und kryptografisch signiert werden, um die Authentifizierung für eine Anwendung gegenüber der Azure Maps-REST-API nachzuweisen. Ein SAS-Token, erstellt durch Integration einer benutzerseitig zugewiesenen verwalteten Identität mit einem Azure Maps-Konto in Ihr Azure-Abonnement. Die benutzerseitig zugewiesene verwaltete Identität erhält über Azure RBAC mithilfe entweder der integrierten oder der benutzerdefinierten Rollendefinitionen eine Autorisierung für das Azure Maps-Konto.

Funktionale Schlüsselunterschiede des SAS-Tokens von Microsoft Entra-Zugriffstoken:

  • Lebensdauer eines Tokens für eine maximale Gültigkeit von einem Tag (24 Stunden).
  • Zugriffssteuerung pro Token für Azure-Standorte- und Geografie.
  • Geschwindigkeitsbegrenzungen pro Token für ungefähr 1 bis 500 Anfragen pro Sekunde.
  • Private Schlüssel des Tokens sind die Primär- und Sekundärschlüssel einer Azure Maps-Kontoressource.
  • Das Dienstprinzipalobjekt für die Autorisierung wird von einer vom Benutzer zugewiesenen verwalteten Identität bereitgestellt.

SAS-Token sind unveränderbar. Das bedeutet, dass ein SAS-Token nach seiner Erstellung bis zum Ablauf gültig ist und die Konfiguration der zulässigen Regionen, Ratenbegrenzungen und der benutzerseitig zugewiesenen verwalteten Identität nicht geändert werden kann. Lesen Sie unten mehr über Zugriffssteuerung verstehen für den Widerruf von SAS-Token und Änderungen an der Zugriffssteuerung.

Geschwindigkeitsbegrenzungen für SAS-Token verstehen

Die maximale Geschwindigkeitsbegrenzung für SAS-Token kann die Abrechnung für eine Azure Maps-Ressource steuern.

Wenn Sie eine maximale Ratenbegrenzung für das Token (maxRatePerSecond) angeben, wird die überschüssige Rate nicht dem Konto in Rechnung gestellt, sodass Sie bei Verwendung des Tokens eine Obergrenze für abrechenbare Transaktionen für das Konto festlegen können. Die Anwendung erhält jedoch Client-Fehlerantworten mit 429 (TooManyRequests) für alle Transaktionen, sobald dieser Grenzwert erreicht ist. Es liegt in der Verantwortung der Anwendung, die Wiederholung und Verteilung von SAS-Token zu verwalten. Es können unbegrenzte SAS-Token für ein Konto erstellt werden. Um eine Erhöhung oder Verringerung der Begrenzung eines bestehenden Tokens zu ermöglichen, muss ein neues SAS-Token erstellt werden. Das alte SAS-Token ist bis zu seinem Ablauf weiterhin gültig.

Abgeschätztes Beispiel:

Ungefähre Höchstgeschwindigkeit pro Sekunde Tatsächliche Geschwindigkeit pro Sekunde Dauer der anhaltenden Geschwindigkeit in Sekunden Gesamtzahl der abrechenbaren Transaktionen
10 20 600 6\.000

Die tatsächlichen Ratenbegrenzungen variieren, basierend auf der Fähigkeit von Azure Maps, Konsistenz innerhalb einer bestimmten Zeitspanne zu erzwingen. Dies erlaubt jedoch eine vorbeugende Kontrolle der Abrechnungskosten.

Geschwindigkeitsbegrenzungen werden pro Azure-Standort durchgeführt, nicht global oder geografisch

Beispielsweise kann ein einzelnes SAS-Token mit einem maxRatePerSecond von 10 verwendet werden, um den Durchsatz am Standort East US zu begrenzen. Wenn dasselbe Token in West US 2 verwendet wird, wird ein neuer Zähler erstellt, um den Durchsatz an diesem Standort auf 10 zu begrenzen, unabhängig vom Standort East US. Um die Kosten zu kontrollieren und die Berechenbarkeit zu verbessern, empfehlen wir:

  1. Erstellen Sie SAS-Token mit vorgesehenen zulässigen Azure-Standorten für die Zielregion. Lesen Sie weiter, um mehr über das Erstellen von SAS-Token zu erfahren.
  2. Verwenden Sie die REST-API-Endpunkte der geografischen Datenebene, https://us.atlas.microsoft.com oder https://eu.atlas.microsoft.com.

Berücksichtigen Sie die Anwendungstopologie, in der der Endpunkt https://us.atlas.microsoft.com zu denselben US-Standorten weiterleitet, an denen die Azure Maps-Dienste gehostet werden, z. B. East US, West Central US oder West US 2. Dasselbe gilt für andere geografische Endpunkte wie https://eu.atlas.microsoft.com zwischen West Europe und North Europe. Um unerwartete Autorisierungsverweigerungen zu verhindern, nutzen Sie ein SAS-Token, das dieselben Azure-Standorte verwendet, die die Anwendung verwendet. Der Endpunktstandort wird mithilfe der Azure Maps Management-REST-API definiert.

Standardgeschwindigkeitslimits haben Vorrang vor SAS-Token-Geschwindigkeitslimits

Wie unter QPS-Ratenbegrenzung für Azure Maps beschrieben, gelten für einzelne Dienstangebote unterschiedliche Ratenbegrenzungen, die als Aggregat des Kontos durchgesetzt werden.

Betrachten Sie den Fall von Suchdienst – Inverser Nicht-Batch mit der Begrenzung von 250 Abfragen pro Sekunde (Queries per Second, QPS) für die folgenden Tabellen. Jede Tabelle stellt die geschätzte Gesamtzahl erfolgreicher Transaktionen aus der Beispielnutzung dar.

Die erste Tabelle zeigt ein Token mit einer maximalen Anforderung von 500 pro Sekunde, und der tatsächliche Verbrauch der Anwendung ist 500 Anforderungen pro Sekunde für eine Dauer von 60 Sekunden. Für Suchdienst – Inverser Nicht-Batch gilt eine Ratenbegrenzung von 250, d. h. von den insgesamt 30 000 Anforderungen, die in den 60 Sekunden gestellt werden, sind 15 000 dieser Anforderungen verrechenbare Transaktionen. Die verbleibenden Anforderungen ergeben einen Statuscode 429 (TooManyRequests).

Name Ungefähre Höchstgeschwindigkeit pro Sekunde Tatsächliche Geschwindigkeit pro Sekunde Dauer der anhaltenden Geschwindigkeit in Sekunden Ungefähre Gesamtanzahl erfolgreicher Transaktionen
token 500 500 60 ~15.000

Wenn beispielsweise zwei SAS-Token in denselben Standort erstellt und verwendet werden wie ein Azure Maps-Konto, teilen sich jetzt beide Token die Standardgeschwindigkeitsbegrenzung von 250 QPS. Wenn jeder Token gleichzeitig mit demselben Durchsatz verwendet wird, würden Token 1 und Token 2 erfolgreich jeweils 7.500 erfolgreiche Transaktionen gewähren.

Name Ungefähre Höchstgeschwindigkeit pro Sekunde Tatsächliche Geschwindigkeit pro Sekunde Dauer der anhaltenden Geschwindigkeit in Sekunden Ungefähre Gesamtanzahl erfolgreicher Transaktionen
Token 1 250 250 60 Ungefähr 7500
Token 2 250 250 60 Ungefähr 7500

SAS-Token-Zugriffssteuerung verstehen

SAS-Token verwenden RBAC zur Zugriffssteuerung auf die REST-API. Wenn Sie ein SAS-Token erstellen, wird der vorausgesetzten verwalteten Identität im Zuordnungskonto eine Azure RBAC-Rolle zugewiesen, die Zugriff auf bestimmte REST-API-Aktionen gewährt. Siehe Rollendefinition auswählen, um zu bestimmen, welche APIs die Anwendung zulässt.

Wenn Sie temporären Zugriff zuweisen und entfernen möchten, bevor das SAS-Token abläuft, widerrufen Sie das Token. Andere Gründe für den Widerruf des Zugriffs können sein, wenn das Token unbeabsichtigt mit der Rollenzuweisung Azure Maps Data Contributor verteilt wird und jeder mit dem SAS-Token Daten in Azure Maps-REST-APIs lesen und schreiben kann, wodurch vertrauliche Daten offengelegt oder unerwartete finanzielle Kosten durch die Nutzung verursacht werden können.

Es gibt zwei Möglichkeiten, den Zugriff für SAS-Token zu widerrufen:

  1. Generieren Sie den vom SAS-Token verwendeten Schlüssel oder secondaryKey des Zuordnungskontos erneut.
  2. Entfernen Sie die Rollenzuweisung für die verwaltete Identität im zugehörigen Zuordnungskonto.

Warnung

Das Löschen einer verwalteten Identität, die von einem SAS-Token verwendet wird, oder das Widerrufen der Zugriffssteuerung der verwalteten Identität führt dazu, dass Instanzen Ihrer Anwendung, die das SAS-Token und die verwaltete Identität verwenden, absichtlich 401 Unauthorized oder 403 Forbidden von Azure Maps-REST-APIs zurückgeben, was zu einer Störung der Anwendung führt.

Um Störungen zu vermeiden:

  1. Fügen Sie dem Zuordnungskonto eine zweite verwaltete Identität hinzu und weisen Sie der neuen verwalteten Identität die richtige Rollenzuweisung zu.
  2. Erstellen Sie ein SAS-Token mithilfe von secondaryKey oder einer anderen verwalteten Identität als der vorherigen, als signingKey und verteilen Sie das neue SAS-Token an die Anwendung.
  3. Generieren Sie den Primärschlüssel neu, entfernen Sie die verwaltete Identität aus dem Konto und entfernen Sie die Rollenzuweisung für die verwaltete Identität.

Erstellen von SAS-Token

Um SAS-Token zu erstellen, müssen Sie über Rollenzugriff vom Typ Contributor verfügen, um sowohl Azure Maps-Konten als auch benutzerseitig zugewiesene Identitäten im Azure-Abonnement verwalten zu können.

Wichtig

Bestehende Azure Maps-Konten, die am Azure-Standort global erstellt wurden, unterstützen keine verwalteten Identitäten.

Zuerst sollten Sie eine benutzerseitig zugewiesene verwaltete Identität am selben Speicherort wie das Azure Maps-Konto erstellen.

Tipp

Sie sollten denselben Speicherort sowohl für die verwaltete Identität als auch für das Azure Maps-Konto verwenden.

Nachdem eine verwaltete Identität erstellt wurde, können Sie das Azure Maps-Konto erstellen oder aktualisieren und es anfügen. Weitere Informationen finden Sie unter Verwalten Ihres Azure Maps-Kontos.

Sobald das Konto erfolgreich erstellt oder mit der verwalteten Identität aktualisiert ist: Weisen Sie einer Azure Maps-Datenrolle auf Kontoebene rollenbasierte Zugriffssteuerung für die verwaltete Identität zu. Dadurch kann der verwalteten Identität Zugriff auf die Azure Maps-REST-API für Ihr Zuordnungskonto gewährt werden.

Als Nächstes erstellen Sie ein SAS-Token mit den Azure Management SDK-Tools, dem Vorgang „List SAS“ in der Kontoverwaltungs-API oder der Shared Access Signature-Seite im Azure-Portal der Map-Kontoressource.

SAS-Tokenparameter:

Parametername Beispielwert BESCHREIBUNG
signingKey primaryKey Der aufgelistete Zeichenfolgenwert für den Signaturschlüssel ist notwendig, entweder primaryKey, secondaryKey oder die verwaltete Identität wird verwendet, um die Signatur der SAS zu erstellen.
principalId <GUID> Erforderlich. Die Prinzipal-ID ist die Objekt-ID (Prinzipal-ID) der vom benutzerseitig zugewiesenen verwalteten Identität, die dem Zuordnungskonto zugewiesen ist.
regions [ "eastus", "westus2", "westcentralus" ] Optional, der Standardwert ist null. Die Regionen steuern, in welchen Regionen das SAS-Token in der Azure Maps-REST-API für die Datenebene verwendet werden darf. Das Weglassen des Parameters „Regionen“ ermöglicht die Verwendung des SAS-Tokens ohne Einschränkungen. Bei Verwendung in Kombination mit einem geografischen Endpunkt der Azure Maps-Datenebene wie us.atlas.microsoft.com und eu.atlas.microsoft.com kann die Anwendung den Verbrauch innerhalb der angegebenen geografischen Region steuern. Dadurch kann die Verwendung in anderen Regionen verhindert werden.
Maximale Geschwindigkeit pro Sekunde 500 Die angegebene ungefähre maximale Anforderung pro Sekunde, die dem SAS-Token gewährt wird, ist notwendig. Sobald der Grenzwert erreicht ist, wird weiterer Durchsatz mit dem HTTP-Statuscode 429 (TooManyRequests) ratenbegrenzt.
start 2021-05-24T10:42:03.1567373Z Ein UTC-Datum, das das Datum und die Uhrzeit angibt, zu der das Token aktiv wird, ist notwendig.
expiry 2021-05-24T11:42:03.1567373Z Ein UTC-Datum, das das Datum und die Uhrzeit angibt, zu denen das Token abläuft, ist notwendig. Die Dauer zwischen Beginn und Ablauf darf 24 Stunden nicht überschreiten.

Anwendung mit SAS-Token konfigurieren

Nachdem die Anwendung ein SAS-Token erhalten hat, senden das Azure Maps SDK und/oder die Anwendungen eine HTTPS-Anforderung mit dem folgenden notwendigen HTTP-Header zusätzlich zu anderen REST-API-HTTP-Headern:

Headername Wert
Authorization jwt-sas eyJ0e….HNIVN

Hinweis

jwt-sas ist das Authentifizierungsschema für die Verwendung von SAS-Token. Bitte x-ms-client-id oder andere Autorisierungsheader oder subscription-key Abfragezeichenfolgenparameter nicht einschließen.

Ursprungsübergreifende Ressourcenfreigabe (CORS)

CORS ist ein HTTP-Protokoll, das es einer unter einer Domäne ausgeführten Webanwendung ermöglicht, auf Ressourcen in einer anderen Domäne zuzugreifen. Webbrowser implementieren eine Sicherheitseinschränkung, die als Same-Origin-Richtlinie (Richtlinie desselben Ursprungs) bezeichnet wird und verhindert, dass eine Webseite APIs in einer anderen Domäne aufruft. CORS bietet eine sichere Methode, einer Domäne (der Ursprungsdomäne) das Aufrufen von APIs in einer anderen Domäne zu ermöglichen. Mithilfe der Azure Maps-Kontoressource können Sie konfigurieren, welche Ursprünge von Ihren Anwendungen aus auf die Azure Maps-REST-API zugreifen dürfen.

Wichtig

CORS ist kein Autorisierungsmechanismus. Jede Anforderung an ein Zuordnungskonto, welche die REST-API mit aktivierten CORS verwendet, erfordert auch ein gültiges Zuordnungskonto-Authentifizierungsschema wie freigegebene Schlüssel, Microsoft Entra ID oder SAS-Token.

CORS wird für alle Zuordnungskonto-Tarife, Endpunkte auf Datenebene und Standorte unterstützt.

Voraussetzungen

Um die Ausführung von schädlichem Code auf dem Client zu verhindern, blockieren moderne Browser Anforderungen, die von Webanwendungen an Ressourcen in einer separaten Domäne gerichtet werden.

  • Wenn Sie mit CORS nicht vertraut sind, sehen Sie sich die Informationen unter Cross-Origin Resource Sharing (CORS) an. Damit kann ein Access-Control-Allow-Origin-Header deklarieren, welche Ursprünge Endpunkte eines Azure Maps-Kontos aufrufen dürfen. Das CORS-Protokoll ist nicht spezifisch für Azure Maps.

CORS-Anforderungen

Eine CORS-Anforderung von einer Ursprungsdomäne kann aus zwei separaten Anforderungen bestehen:

  • Einer Preflight-Anforderung, durch die die vom Dienst auferlegten CORS-Einschränkungen abgefragt werden. Die Preflight-Anforderung ist notwendig, es sei denn, die Anforderung ist die Standardmethode GET, HEAD, POST, oder die Anforderung enthält den Anforderungsheader Authorization.

  • Die für die gewünschte Ressource ausgeführte tatsächliche Anforderung.

Preflight-Anforderung

Die Preflight-Anforderung dient nicht nur als Sicherheitsmaßnahme, um sicherzustellen, dass der Server die Methode und die Header versteht, die in der eigentlichen Anforderung gesendet werden, und dass der Server die Quelle der Anforderung kennt und ihr vertraut, sondern sie fragt auch die CORS-Einschränkungen ab, die für das Kartenkonto eingerichtet wurden. Der Webbrowser (oder ein anderer Benutzer-Agent) übermittelt eine OPTIONS-Anforderung, die die Anforderungsheader, die Methode und die Ursprungsdomäne enthält. Der Zuordnungskontodienst versucht, alle CORS-Regeln abzurufen, wenn die Kontoauthentifizierung über das CORS-Preflight-Protokoll möglich ist.

Wenn eine Authentifizierung nicht möglich ist, wertet der Maps-Dienst einen vorkonfigurierten Satz von CORS-Regeln aus, die angeben, welche Ursprungsdomänen, Anforderungsmethoden und Anforderungsheader bei einer tatsächlichen Anforderung an den Maps-Dienst angegeben werden können. Standardmäßig ist ein Zuordnungskonto so konfiguriert, dass alle Ursprünge eine nahtlose Integration in Webbrowsers ermöglichen.

Der Dienst antwortet auf die Preflight-Anforderung mit den erforderlichen Headern der Zugriffssteuerung, wenn die folgenden Kriterien erfüllt sind:

  1. Die OPTIONS-Anfrage enthält die erforderlichen CORS-Header (die Ursprungs- und Zugriffssteuerungs-Anforderungsmethode-Header)
  2. Die Authentifizierung war erfolgreich, und eine CORS-Regel ist für das Konto aktiviert, das der Preflight-Anforderung entspricht.
  3. Die Authentifizierung wurde aufgrund erforderlicher Authorization-Anforderungsheader übersprungen, die in der Preflight-Anforderung nicht angegeben werden können.

Wenn die Preflight-Anforderung erfolgreich ist, antwortet der Dienst mit dem Statuscode 200 (OK) und schließt die erforderlichen Zugriffssteuerungs-Header in die Antwort ein.

Der Dienst lehnt Preflight-Anfragen ab, wenn die folgenden Bedingungen eintreten:

  1. Wenn die OPTIONS-Anforderung die erforderlichen CORS-Header (die Header für den Ursprung und die Anforderungsmethode für die Zugriffssteuerung) nicht enthält, antwortet der Dienst mit dem Statuscode 400 (Bad request).
  2. Wenn die Authentifizierung bei der Preflight-Anforderung erfolgreich war und keine CORS-Regel mit der Preflight-Anforderung übereinstimmt, antwortet der Dienst mit dem Statuscode 403 (Forbidden). Dies kann der Fall sein, wenn die CORS-Regel so konfiguriert ist, dass sie einen Ursprung akzeptiert, der nicht mit dem aktuellen Origin-Anforderungsheader des Browserclients übereinstimmt.

Hinweis

Eine Preflight-Anforderung wird gegen den Dienst und nicht gegen die angeforderte Ressource ausgewertet. Der Kontobesitzer muss CORS aktiviert haben, indem er die entsprechenden Kontoeigenschaften festlegt, damit die Anforderung erfolgreich sein kann.

Tatsächliche Anforderung

Sobald die Preflight-Anforderung akzeptiert und die Antwort zurückgegeben wird, sendet der Browser die eigentliche Anforderung an den Kartendienst. Der Browser lehnt die tatsächliche Anforderung sofort ab, wenn die Preflight-Anforderung zurückgewiesen wird.

Die eigentliche Anforderung wird als normale Anforderung an den Zuordnungsdienst behandelt. Das Vorhandensein des Origin-Headers zeigt an, dass es sich bei der Anforderung um eine CORS-Anforderung handelt, und der Dienst validiert dann gegen die CORS-Regeln. Wenn eine Übereinstimmung gefunden wird, werden die Access-Control-Header der Antwort hinzugefügt und an den Client zurückgesendet. Wenn keine Übereinstimmung gefunden wird, gibt die Antwort ein 403 (Forbidden) zurück, was auf einen CORS-Ursprungsfehler hinweist.

CORS-Richtlinie aktivieren

Wenn ein Kartenkonto erstellt oder aktualisiert wird, geben seine Eigenschaften die zulässigen Ursprünge an, die konfiguriert werden sollen. Sie können eine CORS-Regel für die Azure Maps-Kontoeigenschaften über das Azure Maps Management SDK, die Azure Maps Management-REST-API und das Portal festlegen. Nachdem Sie die CORS-Regel für den Dienst festgelegt haben, wird eine ordnungsgemäß autorisierte Anforderung an den Dienst von einer anderen Domäne ausgewertet, um festzustellen, ob sie gemäß der von Ihnen angegebenen Regel zulässig ist. Beispiel:

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

Es kann nur eine CORS-Regel mit ihrer Liste zulässiger Ursprünge angegeben werden. Jeder Ursprung ermöglicht, die HTTP-Anforderung an die Azure Maps-REST-API im Webbrowser des angegebenen Ursprungs zu stellen.

CORS-Richtlinie entfernen

Sie können CORS entfernen:

  • Manuell im Azure-Portal
  • Programmgesteuert mittels:
    • Dem Azure Maps-SDK
    • REST-API für Azure Maps-Verwaltung
    • eine ARM-Vorlage

Tipp

Wenn Sie die Azure Maps-Verwaltungs-REST-API verwenden, verwenden Sie PUT oder PATCH mit einer leeren corsRule Liste im Anforderungstext.

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

Abrechnungstransaktionen verstehen

Azure Maps zählt keine Abrechnungstransaktionen für:

  • 5xx HTTP-Statuscodes
  • 401 (Nicht autorisiert)
  • 403 (Unzulässig)
  • 408 (Timeout)
  • 429 (Zu viele Anfragen)
  • CORS-Preflightanforderungen

Weitere Informationen zu Abrechnungstransaktionen sowie andere Preisinformationen zu Azure Maps finden Sie unter Azure Maps-Preisgestaltung.

Nächste Schritte

Hier finden Sie weitere Informationen zu bewährten Sicherheitsmethoden:

Best Practices für Authentifizierung und Autorisierung

Weitere Informationen zur Authentifizierung einer Anwendung mit Microsoft Entra ID und Azure Maps finden Sie unter:

Verwalten der Authentifizierung in Azure Maps.

Weitere Informationen zur Authentifizierung des Azure Maps Control mit Microsoft Entra ID finden Sie unter:

Verwenden des Azure Maps-Kartensteuerelements