Uwierzytelnianie w usłudze Azure Maps

Usługa Azure Mapy obsługuje trzy sposoby uwierzytelniania żądań: uwierzytelnianie klucza współdzielonego, uwierzytelnianie identyfikatora Entra firmy Microsoft i uwierzytelnianie tokenu sygnatury dostępu współdzielonego (SAS). W tym artykule opisano metody uwierzytelniania, które ułatwiają wdrażanie usług Azure Mapy. W tym artykule opisano również inne mechanizmy kontroli kont, takie jak wyłączanie uwierzytelniania lokalnego dla usługi Azure Policy i współużytkowania zasobów między źródłami (CORS).

Uwaga

Aby poprawić bezpieczną komunikację z usługą Azure Mapy, obsługujemy teraz protokół Transport Layer Security (TLS) 1.2 i wycofaliśmy obsługę protokołów TLS 1.0 i 1.1. Jeśli obecnie używasz protokołu TLS 1.x, oceń gotowość protokołu TLS 1.2 i opracuj plan migracji z testami opisanymi w artykule Rozwiązywanie problemu z protokołem TLS 1.0.

Uwierzytelnianie za pomocą klucza współużytkowanego

Aby uzyskać informacje na temat wyświetlania kluczy w witrynie Azure Portal, zobacz Wyświetlanie szczegółów uwierzytelniania.

Klucze podstawowe i pomocnicze są generowane po utworzeniu konta usługi Azure Mapy. Zachęcamy do używania klucza podstawowego jako klucza subskrypcji podczas wywoływania usługi Azure Mapy z uwierzytelnianiem klucza współużytkowanego. Uwierzytelnianie klucza współdzielonego przekazuje klucz wygenerowany przez konto usługi Azure Mapy do usługi Azure Mapy. Dla każdego żądania do usług Azure Mapy dodaj klucz subskrypcji jako parametr do adresu URL. Klucz pomocniczy może być używany w scenariuszach, takich jak wprowadzanie zmian klucza.

Przykład użycia klucza subskrypcji jako parametru w adresie URL:

https://atlas.microsoft.com/mapData/upload?api-version=1.0&dataFormat=zip&subscription-key={Your-Azure-Maps-Subscription-key}

Ważne

Klucze podstawowe i pomocnicze powinny być traktowane jako poufne dane. Klucz wspólny służy do uwierzytelniania wszystkich interfejsów API REST usługi Azure Mapy. Użytkownicy, którzy korzystają z klucza współużytkowanego, powinni wyodrębnić klucz interfejsu API za pośrednictwem zmiennych środowiskowych lub bezpiecznego magazynu wpisów tajnych, gdzie można nim zarządzać centralnie.

Uwierzytelnianie Microsoft Entra

Subskrypcje platformy Azure są dostarczane z dzierżawą firmy Microsoft Entra, aby umożliwić szczegółową kontrolę dostępu. Usługa Azure Mapy oferuje uwierzytelnianie usług Azure Mapy przy użyciu identyfikatora Entra firmy Microsoft. Identyfikator Entra firmy Microsoft zapewnia uwierzytelnianie oparte na tożsamościach dla użytkowników i aplikacji zarejestrowanych w dzierżawie firmy Microsoft Entra.

Usługa Azure Mapy akceptuje tokeny dostępu OAuth 2.0 dla dzierżaw firmy Microsoft entra skojarzonych z subskrypcją platformy Azure zawierającą konto usługi Azure Mapy. Usługa Azure Mapy akceptuje również tokeny dla:

• Użytkownicy firmy Microsoft Entra
• Aplikacje partnerskie korzystające z uprawnień delegowanych przez użytkowników
• Tożsamości zarządzane dla zasobów platformy Azure

Usługa Azure Mapy generuje unikatowy identyfikator (identyfikator klienta) dla każdego konta usługi Azure Mapy. Tokeny z identyfikatora Entra firmy Microsoft można zażądać podczas łączenia tego identyfikatora klienta z innymi parametrami.

Aby uzyskać więcej informacji na temat konfigurowania identyfikatora entra firmy Microsoft i tokenów żądań dla usługi Azure Mapy, zobacz Zarządzanie uwierzytelnianiem w usłudze Azure Mapy.

Aby uzyskać ogólne informacje na temat uwierzytelniania za pomocą identyfikatora Entra firmy Microsoft, zobacz Uwierzytelnianie a autoryzacja.

Tożsamości zarządzane dla zasobów platformy Azure i usługi Azure Mapy

Tożsamości zarządzane dla zasobów platformy Azure zapewniają usługom platformy Azure automatyczne zarządzane jednostki zabezpieczeń opartej na aplikacji, która może uwierzytelniać się za pomocą identyfikatora Entra firmy Microsoft. Za pomocą kontroli dostępu opartej na rolach platformy Azure (RBAC) podmiot zabezpieczeń tożsamości zarządzanej może być autoryzowany do uzyskiwania dostępu do usług Azure Mapy. Oto kilka przykładów tożsamości zarządzanych: aplikacja systemu Azure Service, Azure Functions i Azure Virtual Machines. Aby uzyskać listę tożsamości zarządzanych, zobacz Usługi platformy Azure, które mogą używać tożsamości zarządzanych do uzyskiwania dostępu do innych usług. Aby uzyskać więcej informacji na temat tożsamości zarządzanych, zobacz Zarządzanie uwierzytelnianiem w usłudze Azure Mapy.

Konfigurowanie uwierzytelniania aplikacji Microsoft Entra

Aplikacje uwierzytelniają się w dzierżawie firmy Microsoft Entra przy użyciu co najmniej jednego obsługiwanego scenariusza dostarczonego przez identyfikator Entra firmy Microsoft. Każdy scenariusz aplikacji Firmy Microsoft Entra reprezentuje różne wymagania na podstawie potrzeb biznesowych. Niektóre aplikacje mogą wymagać środowisk logowania użytkownika, a inne aplikacje mogą wymagać środowiska logowania aplikacji. Aby uzyskać więcej informacji, zobacz Przepływy uwierzytelniania i scenariusze aplikacji.

Gdy aplikacja otrzyma token dostępu, zestaw SDK i/lub aplikacja wysyła żądanie HTTPS z następującym zestawem wymaganych nagłówków HTTP oprócz innych nagłówków HTTP interfejsu API REST:

Nazwa nagłówka	Wartość
x-ms-client-id	30d7cc... 9f55
Autoryzacja	Bearer eyJ0e... HNIVN

Uwaga

x-ms-client-idto identyfikator GUID oparty na koncie platformy Azure Mapy wyświetlany na stronie uwierzytelniania usługi Azure Mapy.

Oto przykład żądania trasy usługi Azure Mapy, które używa tokenu elementu nośnego OAuth identyfikatora OAuth firmy Microsoft:

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

Aby uzyskać informacje na temat wyświetlania identyfikatora klienta, zobacz Wyświetlanie szczegółów uwierzytelniania.

Napiwek

Programowe pobieranie identyfikatora klienta

W przypadku korzystania z programu PowerShell identyfikator klienta jest przechowywany jako UniqueId właściwość w IMapsAccount obiekcie . Ta właściwość jest pobierana przy użyciu metody Get-AzMapsAccount, na przykład:

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

W przypadku korzystania z interfejsu wiersza polecenia platformy Azure użyj az maps account show polecenia z parametrem --query , na przykład:

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

Autoryzacja z kontrolą dostępu opartą na rolach

Wymagania wstępne

Jeśli dopiero zaczynasz korzystać z kontroli dostępu opartej na rolach platformy Azure, omówienie kontroli dostępu opartej na rolach (RBAC ) platformy Azure zawiera typy podmiotów zabezpieczeń, które są przyznawane zestawowi uprawnień, nazywanym również definicją roli. Definicja roli zapewnia uprawnienia do akcji interfejsu API REST. Usługa Azure Mapy obsługuje dostęp do wszystkich typów podmiotów zabezpieczeń dla kontroli dostępu opartej na rolach (RBAC) platformy Azure, w tym: poszczególnych użytkowników firmy Microsoft Entra, grup, aplikacji, zasobów platformy Azure i tożsamości zarządzanych platformy Azure. Stosowanie dostępu do co najmniej jednego konta usługi Azure Mapy jest nazywane zakresem. Przypisanie roli jest tworzone podczas stosowania podmiotu zabezpieczeń, definicji roli i zakresu.

Omówienie

W następnych sekcjach omówiono pojęcia i składniki integracji usługi Azure Mapy z kontrolą dostępu opartą na rolach platformy Azure. W ramach procesu konfigurowania konta usługi Azure Mapy katalog Microsoft Entra jest skojarzony z subskrypcją platformy Azure, którą znajduje się konto usługi Azure Mapy.

Podczas konfigurowania kontroli dostępu opartej na rolach platformy Azure należy wybrać podmiot zabezpieczeń i zastosować go do przypisania roli. Aby dowiedzieć się, jak dodawać przypisania ról w witrynie Azure Portal, zobacz Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal.

Wybieranie definicji roli

Następujące typy definicji ról istnieją do obsługi scenariuszy aplikacji.

Definicja roli platformy Azure	opis
Czytnik danych usługi Azure Mapy Search and Render Data Reader	Zapewnia dostęp tylko do wyszukiwania i renderowania interfejsów API REST usługi Azure Mapy w celu ograniczenia dostępu do podstawowych przypadków użycia przeglądarki internetowej.
Czytelnik danych usługi Azure Mapy	Zapewnia dostęp do niezmiennych interfejsów API REST usługi Azure Mapy.
Współautor danych usługi Azure Mapy	Zapewnia dostęp do modyfikowalnego interfejsu API REST usługi Azure Mapy. Niezmienność zdefiniowana przez akcje: zapis i usuwanie.
Rola odczytu i usługi Batch na platformie Azure Mapy	Ta rola może służyć do przypisywania akcji odczytu i wsadowych na platformie Azure Mapy.
Definicja roli niestandardowej	Utwórz utworzoną rolę, aby umożliwić elastyczny ograniczony dostęp do interfejsów API REST platformy Azure Mapy.

Niektóre usługi azure Mapy mogą wymagać podniesionych uprawnień do wykonywania akcji zapisu lub usuwania w interfejsach API REST usługi Azure Mapy. Rola Współautor danych platformy Azure Mapy jest wymagana dla usług, które zapewniają akcje zapisu lub usuwania. W poniższej tabeli opisano usługi platformy Azure Mapy Współautor danych, które mają zastosowanie podczas korzystania z akcji zapisu lub usuwania. Gdy wymagane są tylko akcje odczytu, rolę Czytelnik danych usługi Azure Mapy można użyć zamiast roli Współautor danych usługi Azure Mapy.

Usługa Azure Mapy	Definicja roli usługi Azure Mapy
Data	Współautor danych usługi Azure Mapy
Twórca	Współautor danych usługi Azure Mapy
Spatial	Współautor danych usługi Azure Mapy
Wyszukiwanie wsadowe i kierowanie	Współautor danych usługi Azure Mapy

Aby uzyskać informacje na temat wyświetlania ustawień kontroli dostępu opartej na rolach platformy Azure, zobacz How to configure Azure RBAC for Azure Mapy (Jak skonfigurować kontrolę dostępu opartą na rolach platformy Azure dla platformy Azure Mapy).

Definicje ról niestandardowych

Jednym z aspektów zabezpieczeń aplikacji jest zasada najniższych uprawnień, czyli ograniczenie praw dostępu do praw wymaganych do bieżącego zadania. Ograniczenie praw dostępu jest realizowane przez utworzenie niestandardowych definicji ról, które obsługują przypadki użycia wymagające dalszego szczegółowości kontroli dostępu. Aby utworzyć definicję roli niestandardowej, wybierz określone akcje danych do uwzględnienia lub wykluczenia dla definicji.

Definicję roli niestandardowej można następnie użyć w przypisaniu roli dla dowolnego podmiotu zabezpieczeń. Aby dowiedzieć się więcej na temat niestandardowych definicji ról platformy Azure, zobacz Role niestandardowe platformy Azure.

Oto kilka przykładowych scenariuszy, w których role niestandardowe mogą poprawić bezpieczeństwo aplikacji.

Scenariusz	Niestandardowe akcje danych roli
Publiczna strona internetowa logowania lub interaktywna z kafelkami mapy podstawowej i bez innych interfejsów API REST.	Microsoft.Maps/accounts/services/render/read
Aplikacja, która wymaga tylko odwrotnego geokodowania i żadnych innych interfejsów API REST.	Microsoft.Maps/accounts/services/search/read
Rola podmiotu zabezpieczeń, która żąda odczytu danych mapy opartej na usłudze Azure Mapy Creator i podstawowych interfejsów API REST kafelków mapy.	Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/read
Rola podmiotu zabezpieczeń, która wymaga odczytywania, zapisywania i usuwania danych mapy opartej na twórcy. Zdefiniowana jako rola edytora danych mapy, która nie zezwala na dostęp do innego interfejsu API REST, takiego jak kafelki mapy podstawowej.	Microsoft.Maps/accounts/services/data/read, , Microsoft.Maps/accounts/services/data/writeMicrosoft.Maps/accounts/services/data/delete

Objaśnienie zakresu

Podczas tworzenia przypisania roli jest ona zdefiniowana w hierarchii zasobów platformy Azure. Górna część hierarchii to grupa zarządzania, a najniższa to zasób platformy Azure, taki jak konto usługi Azure Mapy. Przypisanie roli do grupy zasobów może umożliwić dostęp do wielu kont lub zasobów platformy Azure Mapy w grupie.

Napiwek

Ogólne zalecenie firmy Microsoft polega na przypisaniu dostępu do zakresu konta usługi Azure Mapy, ponieważ uniemożliwia niezamierzony dostęp do innych kont usługi Azure Mapy istniejących w tej samej subskrypcji platformy Azure.

Wyłączanie uwierzytelniania lokalnego

Konta usługi Azure Mapy obsługują standardową właściwość platformy Azure w interfejsie API zarządzania dla Microsoft.Maps/accounts nazwy disableLocalAuth. Gdy truewszystkie uwierzytelnianie w interfejsie API REST płaszczyzny danych platformy Azure Mapy jest wyłączone, z wyjątkiem uwierzytelniania firmy Microsoft Entra. Jest to skonfigurowane przy użyciu usługi Azure Policy do kontrolowania dystrybucji i zarządzania kluczami udostępnionymi i tokenami SAS. Aby uzyskać więcej informacji, zobacz artykuł Co to jest usługa Azure Policy?.

Wyłączenie uwierzytelniania lokalnego nie powoduje natychmiastowego zastosowania. Poczekaj kilka minut na zablokowanie przyszłych żądań uwierzytelniania przez usługę. Aby ponownie włączyć uwierzytelnianie lokalne, ustaw właściwość na false i po kilku minutach wznawiania uwierzytelniania lokalnego.

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

Uwierzytelnianie tokenu sygnatury dostępu współdzielonego

Tokeny sygnatury dostępu współdzielonego (SAS) to tokeny uwierzytelniania utworzone przy użyciu formatu tokenu internetowego JSON (JWT) i są podpisywane kryptograficznie w celu potwierdzenia uwierzytelniania aplikacji w interfejsie API REST usługi Azure Mapy. Token SAS utworzony przez zintegrowanie tożsamości zarządzanej przypisanej przez użytkownika z kontem usługi Azure Mapy w ramach subskrypcji platformy Azure. Tożsamość zarządzana przypisana przez użytkownika ma autoryzację do konta usługi Azure Mapy za pośrednictwem kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych definicji ról.

Różnice kluczy funkcjonalnych tokenu SAS z tokenów dostępu firmy Microsoft Entra:

• Okres istnienia tokenu dla maksymalnego wygaśnięcia jednego dnia (24 godziny).
• Lokalizacja platformy Azure i kontrola dostępu geografii na token.
• Limity szybkości na token dla około 1 do 500 żądań na sekundę.
• Klucze prywatne tokenu są kluczami podstawowymi i pomocniczymi zasobu konta usługi Azure Mapy.
• Obiekt jednostki usługi na potrzeby autoryzacji jest dostarczany przez tożsamość zarządzaną przypisaną przez użytkownika.

Tokeny SAS są niezmienne. Oznacza to, że po utworzeniu tokenu token SYGNATURy dostępu współdzielonego jest ważny do momentu spełnienia terminu wygaśnięcia, a konfiguracja dozwolonych regionów, limitów szybkości i tożsamości zarządzanej przypisanej przez użytkownika nie może zostać zmieniona. Przeczytaj więcej poniżej, aby zrozumieć kontrolę dostępu do odwołania tokenów SAS i zmiany kontroli dostępu.

Omówienie limitów szybkości tokenów sygnatury dostępu współdzielonego

Maksymalny limit szybkości tokenu SAS może kontrolować rozliczenia zasobu usługi Azure Mapy

Podczas określania maksymalnego limitu szybkości tokenu (maxRatePerSecond) nadwyżka stawek nie jest rozliczana na koncie, co umożliwia ustawienie górnego limitu rozliczanych transakcji dla konta podczas korzystania z tokenu. Jednak aplikacja odbiera odpowiedzi o błędach 429 (TooManyRequests) klienta dla wszystkich transakcji po osiągnięciu tego limitu. Jest to odpowiedzialność aplikacji za zarządzanie ponawiania próbami i dystrybucją tokenów SAS. Nie ma limitu liczby tokenów SAS, które można utworzyć dla konta. Aby umożliwić zwiększenie lub zmniejszenie limitu istniejącego tokenu; należy utworzyć nowy token SAS. Stary token SAS jest nadal ważny do momentu jego wygaśnięcia.

Szacowany przykład:

Przybliżona maksymalna szybkość na sekundę	Rzeczywista szybkość na sekundę	Czas trwania trwałego wskaźnika w sekundach	Łączna liczba rozliczanych transakcji
10	20	600	6000

Rzeczywiste limity szybkości różnią się w zależności od możliwości platformy Azure Mapy wymuszania spójności w określonym przedziale czasu. Pozwala to jednak na zapobieganie kontroli kosztów rozliczeniowych.

Limity szybkości są wymuszane na lokalizację platformy Azure, a nie globalnie ani geograficznie

Na przykład pojedynczy token SAS z wartością maxRatePerSecond 10 może służyć do ograniczania przepływności w East US lokalizacji. Jeśli ten sam token jest używany w West US 2programie , zostanie utworzony nowy licznik, aby ograniczyć przepływność do 10 w tej lokalizacji, niezależnie od East US lokalizacji. Aby kontrolować koszty i zwiększyć przewidywalność, zalecamy:

1. Utwórz tokeny SAS z wyznaczonymi dozwolonymi lokalizacjami platformy Azure dla docelowej lokalizacji geograficznej. Kontynuuj czytanie, aby zrozumieć tworzenie tokenów SAS.
2. Użyj geograficznych punktów końcowych interfejsu API REST płaszczyzny https://us.atlas.microsoft.com danych lub https://eu.atlas.microsoft.com.

Rozważ topologię aplikacji, w której punkt końcowy https://us.atlas.microsoft.com kieruje się do tych samych lokalizacji amerykańskich, które są hostowane przez usługi Azure Mapy, takie jak East US, West Central USlub West US 2. Ten sam pomysł dotyczy innych geograficznych punktów końcowych, takich jak https://eu.atlas.microsoft.com między West Europe i North Europe. Aby zapobiec nieoczekiwanym odmowie autoryzacji, użyj tokenu SAS korzystającego z tych samych lokalizacji platformy Azure, z których korzysta aplikacja. Lokalizacja punktu końcowego jest definiowana przy użyciu interfejsu API REST usługi Azure Mapy Management.

Domyślne limity szybkości mają pierwszeństwo przed limitami szybkości tokenu SAS

Zgodnie z opisem w temacie Azure Mapy limity szybkości, poszczególne oferty usług mają różne limity szybkości, które są wymuszane jako agregacja konta.

Rozważmy przypadek usługa wyszukiwania — odwrócenie od usługi Batch z limitem 250 zapytań na sekundę (QPS) dla poniższych tabel. Każda tabela reprezentuje szacowaną łączną liczbę pomyślnych transakcji na podstawie przykładowego użycia.

Pierwsza tabela przedstawia jeden token, który ma maksymalne żądanie na sekundę 500, a rzeczywiste użycie aplikacji wynosi 500 żądań na sekundę przez czas trwania 60 sekund. usługa wyszukiwania — Odwrócenie w usłudze Non-Batch ma limit szybkości wynoszący 250, co oznacza, że łączna liczba żądań 30 000 wykonanych w ciągu 60 sekund; 15 000 z tych żądań to transakcje rozliczane. Pozostałe żądania powodują kod stanu 429 (TooManyRequests).

Nazwisko	Przybliżona maksymalna szybkość na sekundę	Rzeczywista szybkość na sekundę	Czas trwania trwałego wskaźnika w sekundach	Przybliżona suma zakończonych powodzeniem transakcji
token	500	500	60	~15 000

Jeśli na przykład dwa tokeny SAS są tworzone i używają tej samej lokalizacji co konto usługi Azure Mapy, każdy token teraz współudzieli domyślny limit szybkości wynoszący 250 QPS. Jeśli każdy token jest używany w tym samym czasie z tym samym tokenem przepływności 1 i tokenem 2, pomyślnie przyzna 7500 pomyślnych transakcji.

Nazwisko	Przybliżona maksymalna szybkość na sekundę	Rzeczywista szybkość na sekundę	Czas trwania trwałego wskaźnika w sekundach	Przybliżona suma zakończonych powodzeniem transakcji
token 1	250	250	60	~7500
token 2	250	250	60	~7500

Omówienie kontroli dostępu do tokenu SAS

Tokeny sas używają kontroli dostępu opartej na rolach w celu kontrolowania dostępu do interfejsu API REST. Podczas tworzenia tokenu SAS przypisano wstępnie wymaganą tożsamość zarządzaną na koncie mapy rolę RBAC platformy Azure, która udziela dostępu do określonych akcji interfejsu API REST. Zobacz Wybieranie definicji roli, aby określić, które interfejsy API zezwala aplikacja.

Jeśli chcesz przypisać dostęp tymczasowy i usunąć dostęp przed wygaśnięciem tokenu SAS, odwołaj token. Inne przyczyny odwołania dostępu mogą być, jeśli token jest dystrybuowany Azure Maps Data Contributor z przypisaniem roli przypadkowo, a każda osoba z tokenem SAS może mieć możliwość odczytywania i zapisywania danych w interfejsach API REST platformy Azure Mapy, które mogą uwidaczniać poufne dane lub nieoczekiwane koszty finansowe z użycia.

Istnieją dwie opcje odwoływanie dostępu dla tokenów SAS:

1. Wygeneruj ponownie klucz używany przez token SAS lub secondaryKey konta mapy.
2. Usuń przypisanie roli dla tożsamości zarządzanej na skojarzonym koncie mapy.

Ostrzeżenie

Usunięcie tożsamości zarządzanej używanej przez token SAS lub cofnięcie kontroli dostępu tożsamości zarządzanej spowoduje, że wystąpienia aplikacji przy użyciu tokenu SAS i tożsamości zarządzanej celowo zwracają 401 Unauthorized lub 403 Forbidden z interfejsów API REST platformy Azure Mapy, co spowoduje zakłócenia aplikacji.

Aby uniknąć zakłóceń:

1. Dodaj drugą tożsamość zarządzaną do konta mapy i przyznaj nowej tożsamości zarządzanej prawidłowe przypisanie roli.
2. Utwórz token SAS przy użyciu secondaryKeymetody lub innej tożsamości zarządzanej niż poprzedni, jako signingKey i rozpowszechnij nowy token SAS do aplikacji.
3. Wygeneruj ponownie klucz podstawowy, usuń tożsamość zarządzaną z konta i usuń przypisanie roli dla tożsamości zarządzanej.

Tworzenie tokenów SAS

Aby utworzyć tokeny SAS, musisz mieć Contributor dostęp do roli zarówno do zarządzania kontami usługi Azure Mapy, jak i tożsamościami przypisanymi przez użytkownika w subskrypcji platformy Azure.

Ważne

Istniejące konta usługi Azure Mapy utworzone w lokalizacji global platformy Azure nie obsługują tożsamości zarządzanych.

Najpierw należy utworzyć tożsamość zarządzaną przypisaną przez użytkownika w tej samej lokalizacji co konto usługi Azure Mapy.

Napiwek

Należy użyć tej samej lokalizacji zarówno dla tożsamości zarządzanej, jak i konta usługi Azure Mapy.

Po utworzeniu tożsamości zarządzanej możesz utworzyć lub zaktualizować konto usługi Azure Mapy i dołączyć je. Aby uzyskać więcej informacji, zobacz Zarządzanie kontem usługi Azure Mapy.

Po pomyślnym utworzeniu lub zaktualizowaniu konta przy użyciu tożsamości zarządzanej; przypisz kontrolę dostępu opartą na rolach dla tożsamości zarządzanej do roli danych usługi Azure Mapy w zakresie konta. Dzięki temu tożsamość zarządzana może mieć dostęp do interfejsu API REST usługi Azure Mapy dla konta mapy.

Następnie utwórz token SYGNATURY dostępu współdzielonego przy użyciu narzędzi zestawu AZURE Management SDK, operacji List SAS w interfejsie API zarządzania kontami lub strony Sygnatura dostępu współdzielonego witryny Azure Portal zasobu konta mapy.

Parametry tokenu sygnatury dostępu współdzielonego:

Nazwa parametru	Przykładowa wartość	opis
Signingkey	primaryKey	Wymagana jest wartość wyliczenia ciągu dla klucza podpisywania primaryKeysecondaryKey lub tożsamości zarządzanej do utworzenia podpisu sygnatury dostępu współdzielonego.
principalId	<GUID>	Wymagany, principalId jest identyfikatorem obiektu (podmiotu zabezpieczeń) tożsamości zarządzanej przypisanej przez użytkownika dołączonej do konta mapy.
— regiony	[ "eastus", "westus2", "westcentralus" ]	Opcjonalnie wartość domyślna to null. Regiony kontrolują regiony, w których można używać tokenu SAS w interfejsie API płaszczyzny danych REST usługi Azure Mapy. Pominięcie parametru regionów umożliwia używanie tokenu SAS bez żadnych ograniczeń. W przypadku użycia w połączeniu z punktem końcowym geograficznym płaszczyzny danych platformy Azure Mapy, na przykład us.atlas.microsoft.com i eu.atlas.microsoft.com umożliwia aplikacji kontrolowanie użycia z określonym obszarem geograficznym. Umożliwia to zapobieganie użyciu w innych lokalizacjach geograficznych.
maxRatePerSecond	500	Wymagane, określone przybliżone maksymalne żądanie na sekundę, które jest udzielany token SAS. Po osiągnięciu limitu większa przepływność jest ograniczona przy użyciu kodu 429 (TooManyRequests)stanu HTTP.
start	2021-05-24T10:42:03.1567373Z	Wymagana data UTC określająca datę i godzinę, o których token staje się aktywny.
expiry	2021-05-24T11:42:03.1567373Z	Wymagana data UTC określająca datę i godzinę wygaśnięcia tokenu. Czas trwania między rozpoczęciem a wygaśnięciem nie może przekraczać 24 godzin.

Konfigurowanie aplikacji przy użyciu tokenu SAS

Gdy aplikacja otrzyma token SAS, zestaw SDK usługi Azure Mapy i/lub aplikacje wysyłają żądanie HTTPS z następującym wymaganym nagłówkiem HTTP oprócz innych nagłówków HTTP interfejsu API REST:

Nazwa nagłówka	Wartość
Autoryzacja	jwt-sas eyJ0e....HNIVN

Uwaga

jwt-sas to schemat uwierzytelniania oznaczany przy użyciu tokenu SAS. Nie dołączaj x-ms-client-id ani innych nagłówków autoryzacji ani subscription-key parametru ciągu zapytania.

Współużytkowanie zasobów między źródłami (CORS)

CORS to protokół HTTP, który umożliwia aplikacji internetowej działającej w jednej domenie dostęp do zasobów w innej domenie. Przeglądarki sieci Web implementują ograniczenie zabezpieczeń znane jako zasady tego samego źródła, które uniemożliwia stronie internetowej wywoływanie interfejsów API w innej domenie; Mechanizm CORS zapewnia bezpieczny sposób zezwalania jednej domenie (domenie pochodzenia) na wywoływanie interfejsów API w innej domenie. Korzystając z zasobu konta usługi Azure Mapy, możesz skonfigurować źródła, które mogą uzyskiwać dostęp do interfejsu API REST usługi Azure Mapy z poziomu aplikacji.

Ważne

MECHANIZM CORS nie jest mechanizmem autoryzacji. Każde żądanie skierowane do konta mapy przy użyciu interfejsu API REST, gdy mechanizm CORS jest włączony, wymaga również prawidłowego schematu uwierzytelniania konta mapy, takiego jak klucz współużytkowany, identyfikator Firmy Microsoft Entra lub token SAS.

Mechanizm CORS jest obsługiwany dla wszystkich warstw cenowych konta mapy, punktów końcowych płaszczyzny danych i lokalizacji.

Wymagania wstępne

Aby zapobiec złośliwemu wykonywaniu kodu na kliencie, nowoczesne przeglądarki blokują żądania z aplikacji internetowych do zasobów uruchomionych w oddzielnej domenie.

• Jeśli nie znasz mechanizmu CORS, zobacz Współużytkowanie zasobów między źródłami (CORS), dzięki czemu nagłówek może Access-Control-Allow-Origin zadeklarować, które źródła mogą wywoływać punkty końcowe konta usługi Azure Mapy. Protokół CORS nie jest specyficzny dla usługi Azure Mapy.

Żądania CORS

Żądanie CORS z domeny pochodzenia może składać się z dwóch oddzielnych żądań:

• Żądanie wstępne, które wysyła zapytanie do ograniczeń CORS narzuconych przez usługę. Żądanie wstępne jest wymagane, chyba że żądanie jest standardową metodą GET, HEAD, POST lub żądaniami zawierającymi Authorization nagłówek żądania.

• Rzeczywiste żądanie wykonane względem żądanego zasobu.

Żądanie wstępne

Żądanie wstępne jest wykonywane nie tylko jako środek zabezpieczeń, aby upewnić się, że serwer rozumie metodę i nagłówki, które są wysyłane w rzeczywistym żądaniu, oraz że serwer zna i ufa źródle żądania, ale również wysyła zapytania do ograniczeń CORS, które zostały ustanowione dla konta mapy. Przeglądarka internetowa (lub inny agent użytkownika) wysyła żądanie OPTIONS, które zawiera nagłówki żądania, metodę i domenę źródła. Usługa konta mapy próbuje pobrać wszystkie reguły CORS, jeśli uwierzytelnianie konta jest możliwe za pośrednictwem protokołu wstępnego CORS.

Jeśli uwierzytelnianie nie jest możliwe, usługa mapuje wstępnie skonfigurowany zestaw reguł CORS określających, które domeny pochodzenia, metody żądań i nagłówki żądań mogą być określone na rzeczywistym żądaniu względem usługi map. Domyślnie konto map jest skonfigurowane tak, aby zezwalało wszystkim źródłom na bezproblemową integrację z przeglądarkami internetowymi.

Usługa odpowiada na żądanie wstępne z wymaganymi nagłówkami kontroli dostępu, jeśli spełnione są następujące kryteria:

1. Żądanie OPTIONS zawiera wymagane nagłówki CORS (nagłówki Origin and Access-Control-Request-Method)
2. Uwierzytelnianie zakończyło się pomyślnie, a reguła CORS jest włączona dla konta zgodnego z żądaniem wstępnym.
3. Uwierzytelnianie zostało pominięte z powodu wymaganych Authorization nagłówków żądań, których nie można określić w żądaniu wstępnym.

Gdy żądanie wstępne zakończy się pomyślnie, usługa odpowiada za pomocą kodu 200 (OK)stanu i zawiera wymagane nagłówki kontroli dostępu w odpowiedzi.

Usługa odrzuca żądania wstępne, jeśli wystąpią następujące warunki:

1. Jeśli żądanie OPTIONS nie zawiera wymaganych nagłówków CORS (nagłówki Origin i Access-Control-Request-Method), usługa odpowiada kodem stanu 400 (Bad request).
2. Jeśli uwierzytelnianie powiodło się w żądaniu wstępnym i żadna reguła CORS nie pasuje do żądania wstępnego, usługa odpowiada kodem stanu 403 (Forbidden). Taka sytuacja może wystąpić, jeśli reguła CORS jest skonfigurowana do akceptowania źródła, które nie jest zgodne z nagłówkiem bieżącego żądania pochodzenia klienta przeglądarki.

Uwaga

Żądanie wstępne jest oceniane względem usługi, a nie względem żądanego zasobu. Właściciel konta musi włączyć mechanizm CORS, ustawiając odpowiednie właściwości konta w celu pomyślnego wykonania żądania.

Rzeczywiste żądanie

Gdy żądanie wstępne zostanie zaakceptowane i zostanie zwrócona odpowiedź, przeglądarka wysyła rzeczywiste żądanie względem usługi mapy. Przeglądarka odrzuca rzeczywiste żądanie natychmiast, jeśli żądanie wstępne zostanie odrzucone.

Rzeczywiste żądanie jest traktowane jako normalne żądanie względem usługi mapy. Obecność nagłówka Origin wskazuje, że żądanie jest żądaniem CORS, a następnie usługa sprawdza poprawność względem reguł CORS. Jeśli zostanie znalezione dopasowanie, nagłówki kontroli dostępu są dodawane do odpowiedzi i wysyłane z powrotem do klienta. Jeśli dopasowanie nie zostanie znalezione, odpowiedź zwróci 403 (Forbidden) błąd wskazujący błąd źródła MECHANIZMU CORS.

Włączanie zasad MECHANIZMU CORS

Po utworzeniu lub zaktualizowaniu konta mapy jego właściwości określają dozwolone źródła do skonfigurowania. Regułę CORS można ustawić we właściwościach konta usługi Azure Mapy za pomocą zestawu AZURE Mapy Management SDK, interfejsu API REST usługi Azure Mapy Management i portalu. Po ustawieniu reguły CORS dla usługi zostanie ocenione prawidłowo autoryzowane żądanie do usługi z innej domeny w celu określenia, czy jest to dozwolone zgodnie z określoną regułą. Na przykład:

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

Można określić tylko jedną regułę CORS z listą dozwolonych źródeł. Każde źródło umożliwia wysyłanie żądania HTTP do interfejsu API REST usługi Azure Mapy w przeglądarce internetowej określonego źródła.

Usuwanie zasad CORS

Mechanizm CORS można usunąć:

• Ręcznie w witrynie Azure Portal
• Programowe używanie:
  • Zestaw SDK usługi Azure Mapy
  • Interfejs API REST zarządzania usługą Azure Mapy
  • Szablon usługi ARM

Napiwek

Jeśli używasz interfejsu API REST zarządzania usługą Azure Mapy , użyj polecenia PUT lub PATCH z pustą corsRule listą w treści żądania.

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

Omówienie transakcji rozliczeniowych

Usługa Azure Mapy nie liczy transakcji rozliczeniowych dla:

• Kody stanu HTTP 5xx
• 401 (Brak autoryzacji)
• 403 (Zabronione)
• 408 (limit czasu)
• 429 (TooManyRequests)
• Żądania wstępne CORS

Aby uzyskać więcej informacji na temat transakcji rozliczeniowych i innych informacji o cenach usługi Azure Mapy, zobacz Cennik usługi Azure Mapy.

Następne kroki

Aby dowiedzieć się więcej na temat najlepszych rozwiązań w zakresie zabezpieczeń, zobacz:

Najlepsze rozwiązania dotyczące uwierzytelniania i autoryzacji

Aby dowiedzieć się więcej na temat uwierzytelniania aplikacji przy użyciu identyfikatora Entra firmy Microsoft i usługi Azure Mapy, zobacz:

Zarządzanie uwierzytelnianiem w usłudze Azure Mapy

Aby dowiedzieć się więcej na temat uwierzytelniania kontrolki usługi Azure Mapy za pomocą identyfikatora Entra firmy Microsoft, zobacz:

How to use Azure Maps map control (Jak używać kontrolki mapy usługi Azure Maps)