Uwierzytelnianie w usłudze Azure Maps

Artykuł
09/25/2024

Usługa Azure Maps 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 Maps. 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 Maps, 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 Maps. Zachęcamy do używania klucza podstawowego jako klucza subskrypcji podczas wywoływania usługi Azure Maps z uwierzytelnianiem klucza współużytkowanego. Uwierzytelnianie klucza współdzielonego przekazuje klucz wygenerowany przez konto usługi Azure Maps do usługi Azure Maps. Dla każdego żądania do usług Azure Maps 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/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

Ważne

Klucze podstawowe i pomocnicze powinny być traktowane jako poufne dane. Klucz wspólny służy do uwierzytelniania całego interfejsu API REST usługi Azure Maps. 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 Maps oferuje uwierzytelnianie usług Azure Maps 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 Maps akceptuje tokeny dostępu OAuth 2.0 dla dzierżaw firmy Microsoft Entra skojarzonych z subskrypcją platformy Azure zawierającą konto usługi Azure Maps. Usługa Azure Maps 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 Maps generuje unikatowy identyfikator (identyfikator klienta) dla każdego konta usługi Azure Maps. 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 Maps, zobacz Zarządzanie uwierzytelnianiem w usłudze Azure Maps.

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 Maps

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 Maps. 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 Maps.

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-id to identyfikator GUID oparty na koncie usługi Azure Maps wyświetlany na stronie uwierzytelniania usługi Azure Maps.

Oto przykład żądania trasy usługi Azure Maps, które używa tokenu elementu nośnego OAuth 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 Maps 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 Maps 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 Maps z kontrolą dostępu opartą na rolach platformy Azure. W ramach procesu konfigurowania konta usługi Azure Maps katalog Microsoft Entra jest skojarzony z subskrypcją platformy Azure, którą znajduje się konto usługi Azure Maps.

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
Wyszukiwanie i renderowanie czytnika danych w usłudze Azure Maps	Zapewnia dostęp tylko do wyszukiwania i renderowania interfejsów API REST usługi Azure Maps w celu ograniczenia dostępu do podstawowych przypadków użycia przeglądarki internetowej.
Czytelnik danych usługi Azure Maps	Zapewnia dostęp do niezmiennych interfejsów API REST usługi Azure Maps.
Współautor danych usługi Azure Maps	Zapewnia dostęp do modyfikowalnego interfejsu API REST usługi Azure Maps. Niezmienność zdefiniowana przez akcje: zapis i usuwanie.
Rola odczytu i usługi Batch w usłudze Azure Maps	Ta rola może służyć do przypisywania akcji odczytu i wsadowych w usłudze Azure Maps.
Definicja roli niestandardowej	Utwórz utworzoną rolę, aby umożliwić elastyczny ograniczony dostęp do interfejsów API REST usługi Azure Maps.

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

Usługa Azure Maps	Definicja roli usługi Azure Maps
Twórca (przestarzałe¹)	Współautor danych usługi Azure Maps
Spatial (przestarzałe¹)	Współautor danych usługi Azure Maps
Wyszukiwanie wsadowe i kierowanie	Współautor danych usługi Azure Maps

¹ Twórca usługi Azure Maps, a rejestr danych i usługi przestrzenne są teraz przestarzałe i zostaną wycofane w dniu 30.09.25.

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

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 Maps dla twórców 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 Maps. Przypisanie roli do grupy zasobów może umożliwić dostęp do wielu kont lub zasobów usługi Azure Maps w grupie.

Napiwek

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

Wyłączanie uwierzytelniania lokalnego

Konta usługi Azure Maps obsługują standardową właściwość platformy Azure w interfejsie API zarządzania dla Microsoft.Maps/accounts wywołań disableLocalAuth. Gdy truewszystkie uwierzytelnianie w interfejsie API REST płaszczyzny danych usługi Azure Maps 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 Maps. Token SAS utworzony przez zintegrowanie tożsamości zarządzanej przypisanej przez użytkownika z kontem usługi Azure Maps w ramach subskrypcji platformy Azure. Tożsamość zarządzana przypisana przez użytkownika jest udzielana autoryzacji do konta usługi Azure Maps 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 Maps.
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 dla zasobu usługi Azure Maps

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 wymuszania spójności w usłudze Azure Maps 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:

Utwórz tokeny SAS z wyznaczonymi dozwolonymi lokalizacjami platformy Azure dla docelowej lokalizacji geograficznej. Kontynuuj czytanie, aby zrozumieć tworzenie tokenów SAS.
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 Maps, takich 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 Maps Management.

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

Zgodnie z opisem w temacie Limity szybkości usługi Azure Maps 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 w usłudze Azure Maps są tworzone dwa tokeny SAS i używać tej samej lokalizacji co konto usługi Azure Maps, 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 mająca token SAS może odczytywać i zapisywać dane w interfejsach API REST usługi Azure Maps, które mogą uwidaczniać poufne dane lub nieoczekiwany koszt finansowy z użycia.

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

Wygeneruj ponownie klucz używany przez token SAS lub secondaryKey konta mapy.
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 usługi Azure Maps, co spowoduje zakłócenia aplikacji.

Aby uniknąć zakłóceń:

Dodaj drugą tożsamość zarządzaną do konta mapy i przyznaj nowej tożsamości zarządzanej prawidłowe przypisanie roli.
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.
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 Maps, jak i tożsamościami przypisanymi przez użytkownika w subskrypcji platformy Azure.

Ważne

Istniejące konta usługi Azure Maps 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 Maps.

Napiwek

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

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

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 Maps w zakresie konta. Dzięki temu tożsamość zarządzana może mieć dostęp do interfejsu API REST usługi Azure Maps 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 Maps. Pominięcie parametru regionów umożliwia używanie tokenu SAS bez żadnych ograniczeń. W połączeniu z punktem końcowym geograficznym płaszczyzny danych usługi Azure Maps, na przykład `us.atlas.microsoft.com` i `eu.atlas.microsoft.com` umożliwia aplikacji kontrolowanie użycia w określonej lokalizacji geograficznej. 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 Maps 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.

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. Za pomocą zasobu konta usługi Azure Maps można skonfigurować źródła, które mogą uzyskiwać dostęp do interfejsu API REST usługi Azure Maps 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 umożliwia Access-Control-Allow-Origin deklarowanie źródeł, które źródła mogą wywoływać punkty końcowe konta usługi Azure Maps. Protokół CORS nie jest specyficzny dla usługi Azure Maps.

Żą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:

Żądanie OPTIONS zawiera wymagane nagłówki CORS (nagłówki Origin and Access-Control-Request-Method)
Uwierzytelnianie zakończyło się pomyślnie, a reguła CORS jest włączona dla konta zgodnego z żądaniem wstępnym.
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:

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).
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 Maps za pomocą zestawu AZURE Maps Management SDK, interfejsu API REST usługi Azure Maps 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 Maps 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 Maps
- Interfejs API REST zarządzania usługą Azure Maps
- Szablon usługi ARM

Napiwek

Jeśli używasz interfejsu API REST zarządzania usługą Azure Maps, 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 Maps 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 Maps, zobacz Cennik usługi Azure Maps.

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 Maps, zobacz:

Zarządzanie uwierzytelnianiem w usłudze Azure Maps

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

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

Udostępnij za pośrednictwem

Uwierzytelnianie w usłudze Azure Maps

Uwierzytelnianie za pomocą klucza współużytkowanego

Uwierzytelnianie Microsoft Entra

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

Konfigurowanie uwierzytelniania aplikacji Microsoft Entra

Autoryzacja z kontrolą dostępu opartą na rolach

Wymagania wstępne

Omówienie

Wybieranie definicji roli

Definicje ról niestandardowych

Objaśnienie zakresu

Wyłączanie uwierzytelniania lokalnego

Uwierzytelnianie tokenu sygnatury dostępu współdzielonego

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

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

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

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

Omówienie kontroli dostępu do tokenu SAS

Tworzenie tokenów SAS

Konfigurowanie aplikacji przy użyciu tokenu SAS

Wymagania wstępne

Żądania CORS

Żądanie wstępne

Rzeczywiste żądanie

Włączanie zasad MECHANIZMU CORS

Usuwanie zasad CORS

Omówienie transakcji rozliczeniowych

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Uwierzytelnianie w usłudze Azure Maps

Uwierzytelnianie za pomocą klucza współużytkowanego

Uwierzytelnianie Microsoft Entra

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

Konfigurowanie uwierzytelniania aplikacji Microsoft Entra

Autoryzacja z kontrolą dostępu opartą na rolach

Wymagania wstępne

Omówienie

Wybieranie definicji roli

Definicje ról niestandardowych

Objaśnienie zakresu

Wyłączanie uwierzytelniania lokalnego

Uwierzytelnianie tokenu sygnatury dostępu współdzielonego

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

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

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

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

Omówienie kontroli dostępu do tokenu SAS

Tworzenie tokenów SAS

Konfigurowanie aplikacji przy użyciu tokenu SAS

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

Wymagania wstępne

Żądania CORS

Żądanie wstępne

Rzeczywiste żądanie

Włączanie zasad MECHANIZMU CORS

Usuwanie zasad CORS

Omówienie transakcji rozliczeniowych

Następne kroki

Opinia

Dodatkowe zasoby