Condividi tramite

Autenticazione con Mappe di Azure

Mappe di Azure supporta tre metodi di autenticazione: chiave condivisa, ID Microsoft Entra e token di firma di accesso condiviso. Questo articolo illustra questi metodi di autenticazione, inclusi i dettagli sui controlli dell'account, ad esempio la disabilitazione dell'autenticazione locale per Criteri di Azure e la condivisione di risorse tra le origini (CORS).

Nota

Per migliorare la comunicazione sicura con Mappe di Azure, ora è supportato Transport Layer Security (TLS) 1.2 ed è in corso il ritiro del supporto per TLS 1.0 e 1.1. Se attualmente si usa TLS 1, valutare l'idoneità per TLS 1.2 e sviluppare un piano di migrazione con i test illustrati in Risoluzione del problema relativo a TLS 1.0.

Autenticazione con chiave condivisa

Per informazioni sulla visualizzazione delle chiavi nel portale di Azure, vedere Visualizzare i dettagli di autenticazione.

Le chiavi primarie e secondarie vengono generate automaticamente durante la creazione di un account Mappe di Azure. È consigliabile usare la chiave primaria come chiave di sottoscrizione quando si chiama Mappe di Azure mediante l'autenticazione con chiave condivisa. L'autenticazione con chiave condivisa passa una chiave generata da un account Mappe di Azure a un servizio Mappe di Azure. Per ogni richiesta ai servizi di Mappe di Azure, aggiungere la chiave di sottoscrizione all'URL come parametro. La chiave secondaria può essere usata in scenari come le modifiche graduali delle chiavi.

Esempio di uso della chiave di sottoscrizione come parametro nell'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

Importante

Le chiavi primarie e secondarie devono essere considerate dati sensibili. La chiave condivisa viene usata per autenticare tutte le API REST di Mappe di Azure. Gli utenti che usano una chiave condivisa devono astrarre la chiave API, tramite variabili di ambiente o in un'archiviazione privata sicura, in cui può essere gestita centralmente.

Autenticazione di Microsoft Entra

Le sottoscrizioni di Azure dispongono di un tenant di Microsoft Entra, per abilitare il controllo di accesso granulare. Mappe di Azure offre l'autenticazione per i servizi Mappe di Azure mediante Microsoft Entra ID. Microsoft Entra ID fornisce l'autenticazione basata sull'identità per le applicazioni e gli utenti registrati nel tenant di Microsoft Entra.

Mappe di Azure accetta token di accesso OAuth 2.0 per i tenant di Microsoft Entra associati a una sottoscrizione di Azure contenente un account Mappe di Azure. Mappe di Azure accetta token per:

  • Utenti di Microsoft Entra
  • Applicazioni partner che usano autorizzazioni delegate dagli utenti
  • Identità gestite per le risorse di Azure

Mappe di Azure genera un identificatore univoco (ID client) per ogni account Mappe di Azure. È possibile richiedere i token da Microsoft Entra ID quando si combina questo ID client con altri parametri.

Per altre informazioni su come configurare Microsoft Entra ID e richiedere i token per Mappe di Azure, vedere Gestire l'autenticazione in Mappe di Azure.

Per informazioni generali sull'autenticazione con Microsoft Entra ID, vedere Confronto tra autenticazione e autorizzazione.

Identità gestite per risorse di Azure e Mappe di Azure

Le identità gestite per le risorse di Azure forniscono servizi di Azure con un'entità di sicurezza basata su applicazione gestita automaticamente che può eseguire l'autenticazione con l'ID Microsoft Entra. Con il controllo degli accessi in base al ruolo di Azure (Azure RBAC), l'entità di sicurezza dell'identità gestita può essere autorizzata ad accedere ai servizi Mappe di Azure. Alcuni esempi di identità gestite includono: Servizio app di Azure, Funzioni di Azure e Macchine virtuali di Azure. Per un elenco delle identità gestite, vedere Servizi di Azure che possono usare le identità gestite per accedere ad altri servizi. Per altre informazioni sulle identità gestite, vedere Gestire l'autenticazione in Mappe di Azure.

Configurare l'autenticazione di Microsoft Entra per le applicazioni

Le applicazioni eseguono l'autenticazione con il tenant di Microsoft Entra usando uno o più scenari supportati forniti da Microsoft Entra ID. Ogni scenario di applicazione di Microsoft Entra rappresenta requisiti diversi in base alle esigenze aziendali. Alcune applicazioni potrebbero richiedere esperienze di accesso utente e altre applicazioni potrebbero richiedere un'esperienza di accesso dell'applicazione. Per ulteriori informazioni, vedere Flussi di autenticazione e scenari di applicazione.

Dopo che l'applicazione ha ricevuto un token di accesso, l'SDK e/o l'applicazione invia una richiesta HTTPS con il set seguente di intestazioni HTTP necessarie, oltre alle altre intestazioni HTTP dell'API REST:

Nome dell'intestazione Valore
x-ms-client-id 30d7cc….9f55
Autorizzazione Bearer eyJ0e... HNIVN

Nota

Il GUID associato all'account di Mappe di Azure, x-ms-client-id, appare sulla pagina di autenticazione di Mappe di Azure.

Di seguito è riportato un esempio di richiesta di percorso di Azure Maps che utilizza un token Bearer OAuth di Microsoft Entra ID:

GET /route/directions/json?api-version=1.0&query=52.50931,13.42936:52.50274,13.43872
Host: atlas.microsoft.com
x-ms-client-id: 30d7cc….9f55
Authorization: Bearer eyJ0e…HNIVN

Per informazioni sulla visualizzazione dell'ID client, vedere Visualizzare i dettagli di autenticazione.

Suggerimento

Recupero dell'ID client a livello di codice

Quando si usa PowerShell, l'ID client viene archiviato come proprietà UniqueId nell'oggetto IMapsAccount. È possibile recuperare questa proprietà usando Get-AzMapsAccount, ad esempio:

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

Quando si usa l'interfaccia della riga di comando di Azure, usare il comando az maps account show con il parametro --query, ad esempio:

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

Autorizzazione con il controllo degli accessi in base al ruolo

Prerequisiti

Se non si ha familiarità con l'argomento, la panoramica sul Controllo degli accessi in base al ruolo di Azure illustra i tipi principali a cui vengono concessi un insieme di autorizzazioni, noto anche come definizione di ruolo. Una definizione di ruolo fornisce le autorizzazioni per le azioni dell'API REST. Mappe di Azure supporta l'accesso a tutti i tipi di entità per il controllo degli accessi in base al ruolo di Azure, tra cui: singoli utenti di Microsoft Entra, gruppi, applicazioni, risorse di Azure e identità gestite di Azure. L'applicazione dell'accesso a uno o più account Mappe di Azure è nota come ambito. Un'assegnazione di ruolo viene creata quando vengono applicati un principale, una definizione di ruolo e un ambito.

Panoramica

Le sezioni successive illustrano i concetti e i componenti dell'integrazione delle Mappe di Azure con Azure RBAC. Come parte del processo di configurazione dell'account Azure Maps, una directory Microsoft Entra viene associata alla sottoscrizione di Azure in cui si trova l'account Azure Maps.

Quando si configura il controllo degli accessi in base al ruolo di Azure, si sceglie un'entità di sicurezza e la si applica a un'assegnazione di ruolo. Per informazioni su come aggiungere assegnazioni di ruolo nel portale di Azure, vedere Assegnare ruoli di Azure tramite il portale di Azure.

Scelta di una definizione del ruolo

Per supportare gli scenari delle applicazioni, sono disponibili i tipi di definizione di ruolo seguenti.

Definizione del ruolo di Azure Descrizione
Ruolo con autorizzazioni di lettura dei dati di ricerca e rendering di Mappe di Azure Consente di accedere solo alle API REST di Mappe di Azure di ricerca e rendering, per limitare l'accesso ai casi d'uso di base del Web browser.
Lettore di dati per Mappe di Azure Consente di accedere alle API REST di Mappe di Azure non modificabili.
Collaboratore per i dati di Mappe di Azure Consente di accedere alle API REST modificabili di Mappe di Azure. Mutabilità, definita dalle azioni: scrittura ed eliminazione.
Ruolo di lettura dati e batch di Mappe di Azure Questo ruolo può essere usato per assegnare azioni di lettura e batch in Mappe di Azure.
Definizione del ruolo personalizzata Creare un ruolo personalizzato per abilitare l'accesso flessibile con restrizioni alle API REST di Mappe di Azure.

Alcuni servizi Mappe di Azure richiedono privilegi elevati per eseguire azioni di scrittura o eliminazione nelle API REST Mappe di Azure. Il ruolo Collaboratore per i dati di Mappe di Azure è necessario per i servizi che forniscono azioni di scrittura o eliminazione. La tabella seguente descrive i servizi per i quali è applicabile il ruolo di Collaboratore di dati di Azure Maps quando si effettuano azioni di scrittura o eliminazione. Quando sono necessarie solo azioni di lettura, è possibile usare il Ruolo Lettore di Dati di Mappe di Azure al posto del Ruolo Contributore di Dati di Mappe di Azure.

Servizio Mappe di Azure Definizione del ruolo di Azure Maps
Creator (deprecato1) Collaboratore per i dati di Mappe di Azure
Spaziale (deprecato1) Collaboratore per i dati di Mappe di Azure
Ricerca e Route batch Collaboratore per i dati di Mappe di Azure

1 Creator di Mappe di Azure, il Registro dati e i servizi spaziali sono ora deprecati e verranno ritirati il 30/09/25.

Per informazioni su come visualizzare le impostazioni del controllo degli accessi in base al ruolo di Azure, vedere Come configurare il controllo degli accessi in base al ruolo per Mappe di Azure.

Definizioni di ruolo personalizzate

Un aspetto della sicurezza delle applicazioni è il principio dei privilegi minimi, ovvero la prassi di limitare i diritti di accesso a quelli strettamente necessari per il processo corrente. La limitazione dei diritti di accesso si ottiene creando definizioni di ruolo personalizzate che supportano i casi d'uso che richiedono una maggiore granularità per il controllo di accesso. Per creare una definizione di ruolo personalizzata, selezionare azioni sui dati specifiche da includere o escludere per la definizione.

La definizione del ruolo personalizzato può quindi essere utilizzata in un'assegnazione di ruolo per qualsiasi principale di sicurezza. Per altre informazioni sulle definizioni dei ruoli personalizzati di Azure, vedere Ruoli personalizzati di Azure.

Ecco alcuni scenari di esempio in cui i ruoli personalizzati possono migliorare la sicurezza delle applicazioni.

Sceneggiatura Azioni personalizzate per i dati dei ruoli
Una pagina web interattiva o pubblica di accesso con tessere base della mappa e senza altre API REST. Microsoft.Maps/accounts/services/render/read
Un'applicazione che richiede solo la geocodifica inversa e nessun'altra API REST. Microsoft.Maps/accounts/services/search/read
Un ruolo per un'entità di sicurezza che richiede la lettura dei dati di mappe basate su Creator di Mappe di Azure e delle API REST di tessere mappa di base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/read
Un ruolo per un'entità di sicurezza che richiede la lettura, la scrittura e l'eliminazione di dati di mappe basate su Creator. Definito come ruolo di editor di dati della mappa, che non consente l'accesso ad altre API REST, ad esempio tessere mappa di base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/delete

Comprendere l'ambito

Le assegnazioni di ruolo vengono definite all'interno della gerarchia di risorse di Azure, dal gruppo di gestione di primo livello al livello più basso, ad esempio un account di Mappe di Azure. Per altre informazioni, vedere Che cosa sono i gruppi di gestione di Azure?.

Assegnando un ruolo a un gruppo di risorse, è possibile concedere l'accesso a più account o risorse di Mappe di Azure all'interno di tale gruppo.

Suggerimento

Microsoft consiglia in genere di assegnare l'accesso nell'ambito dell'account Mappe di Azure per impedire l'accesso imprevisto ad altri account mappe di Azure all'interno della stessa sottoscrizione di Azure.

Disabilita autenticazione locale

Gli account di Azure Maps supportano la proprietà standard di Azure nell'API di gestione delle mappe per Microsoft.Maps/accounts chiamata disableLocalAuth. Se true, tutte le autenticazioni per l'API REST del piano dati Mappe di Azure sono disabilitate, ad eccezione dell'autenticazione di Microsoft Entra. Si configura usando Criteri di Azure per controllare la distribuzione e la gestione delle chiavi condivise e dei token di firma di accesso condiviso. Per altre informazioni, vedere Informazioni su Criteri di Azure.

La disabilitazione dell'autenticazione locale non ha effetto immediato. Attendere alcuni minuti prima che il servizio blocchi le richieste di autenticazione future. Per riabilitare l'autenticazione locale, impostare la proprietà su false e dopo alcuni minuti viene ripresa l'autenticazione locale.

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

Autenticazione con firma di accesso condiviso

I token di firma di accesso condiviso (SAS), che sono token di autenticazione nel formato JWT (JSON Web Token), sono firmati crittograficamente per autenticare le applicazioni con l'API REST di Mappe di Azure. Questi token vengono generati integrando un'identità gestita assegnata dall'utente con un account Mappe di Azure nella sottoscrizione di Azure. L'identità gestita è autorizzata ad accedere all'account Mappe di Azure tramite Azure RBAC, utilizzando definizioni di ruolo integrate o personalizzate.

Le principali differenze funzionali tra i token SAS e i token di accesso Microsoft Entra:

  • Durata di un token per una scadenza massima di un giorno (24 ore).
  • Controllo di accesso geografico e della località di Azure per token.
  • Limiti di velocità per token per un valore approssimativo che va da 1 a 500 richieste al secondo.
  • Le chiavi private del token sono le chiavi primaria e secondaria di una risorsa dell'account Mappe di Azure.
  • L'oggetto entità servizio per l'autorizzazione viene fornito da un'identità gestita assegnata dall'utente.

I token SAS sono immutabili. Una volta creati, rimangono validi fino alla scadenza e le relative impostazioni, ad esempio aree consentite, limiti di frequenza e identità gestita assegnata dall'utente non possono essere modificate. Per ulteriori informazioni sulla revoca dei token SAS e sulle modifiche al controllo di accesso, vedere Comprensione del controllo di accesso.

Informazioni sui limiti di velocità dei token SAS

Il limite massimo di velocità del token SAS può controllare la fatturazione per una risorsa di Mappe di Azure

Quando si imposta un limite di velocità massimo per il token (maxRatePerSecond), le tariffe che superano questo limite non vengono fatturate all'account, consentendo di limitare le transazioni fatturabili. Tuttavia, l'applicazione riceverà le risposte dell'errore client 429 (TooManyRequests) per tutte le transazioni dopo il raggiungimento del limite. È responsabilità dell'applicazione gestire i tentativi e distribuire i token SAS. Non ci sono restrizioni sul numero di token di firma di accesso condiviso che si possono creare per un account. Per modificare il limite di un token esistente, è necessario generare un nuovo token di firma di accesso condiviso. Il vecchio token SAS rimane valido fino a quando non scade.

Esempio stimato:

Velocità massima approssimativa al secondo Velocità effettiva al secondo Durata della velocità continua in secondi Totale transazioni fatturabili
10 20 600 6.000

I limiti di velocità effettivi variano in base alla capacità di Mappe di Azure di applicare la coerenza in un intervallo di tempo. Tuttavia, questo consente il controllo preventivo dei costi di fatturazione.

I limiti di velocità vengono applicati per località di Azure, non a livello globale o geografico

Ad esempio, è possibile usare un singolo token SAS con un valore maxRatePerSecond pari a 10 per limitare la velocità effettiva nella località East US. Se lo stesso token viene usato in West US 2, viene creato un nuovo contatore per limitare la velocità effettiva a 10 in tale località, indipendente rispetto alla località East US. Suggerimenti per controllare i costi e migliorare la prevedibilità:

  1. Creare token SAS con località di Azure designate per l'area geografica di destinazione.
  2. Usare gli endpoint geografici dell'API REST del piano dati, https://us.atlas.microsoft.com o https://eu.atlas.microsoft.com.

Si consideri la topologia dell'applicazione in cui l'endpoint https://us.atlas.microsoft.com instrada verso le stesse località degli Stati Uniti in cui sono ospitati i servizi di Mappe di Azure, ad esempio East US, West Central USo West US 2. La stessa idea si applica ad altri endpoint geografici, ad esempio https://eu.atlas.microsoft.com tra West Europe e North Europe. Per evitare rifiuti imprevisti dell'autorizzazione, servirsi di un token SAS che usa le stesse località di Azure usate dall'applicazione. La posizione dell'endpoint si definisce usando l'API REST di gestione di Mappe di Azure.

I limiti di velocità predefiniti hanno la precedenza sui limiti di velocità dei token SAS

Come descritto in Limiti di frequenza QPS di Mappe di Azure, i limiti di frequenza per le singole offerte di servizio vengono applicati collettivamente a livello di account.

Si consideri il caso del Servizio di ricerca - Inverso non batch, con il limite di 250 query al secondo (QPS) per le tabelle seguenti. Ogni tabella rappresenta il totale stimato delle transazioni concluse con successo dall'uso di esempio.

La prima tabella mostra un token con massimo di richieste al secondo di 500 e l'utilizzo effettivo dell'applicazione è di 500 richieste al secondo per una durata di 60 secondi. Il Servizio di ricerca - Inverso non batch ha un limite di velocità pari a 250, vale a dire che del totale di 30.000 richieste effettuate nei 60 secondi, 15.000 sono transazioni fatturabili. Le richieste rimanenti generano il codice di stato 429 (TooManyRequests).

Nome Velocità massima approssimativa al secondo Velocità effettiva al secondo Durata della velocità continua in secondi Transazioni totali approssimative riuscite
token 500 500 60 ~15.000

Ad esempio, se vengono creati due token SAS e usano la stessa posizione di un account Mappe di Azure, ogni token condivide il limite di velocità predefinito di 250 QPS. Se entrambi i token vengono usati contemporaneamente con la stessa velocità effettiva, ogni token concederà 7.500 transazioni riuscite.

Nome Velocità massima approssimativa al secondo Velocità effettiva al secondo Durata della velocità continua in secondi Transazioni totali approssimative riuscite
token 1 250 250 60 ~7500
token 2 250 250 60 ~7500

Informazioni sul controllo di accesso con token SAS

I token SAS utilizzano RBAC (controllo degli accessi in base al ruolo) per gestire l'accesso all'API REST. Quando si crea un token SAS, all'identità gestita prevista come prerequisito nell'account mappa viene assegnato un ruolo Controllo degli accessi in base al ruolo di Azure che concede l'accesso a azioni dell'API REST specifiche. Vedere Scelta di una definizione del ruolo per determinare quali sono le API consentite dall'applicazione.

Per assegnare l'accesso temporaneo e rimuoverlo prima della scadenza del token di firma di accesso condiviso, revocare il token. Un altro motivo per revocare l'accesso è se il token è stato distribuito involontariamente con il ruolo Contributor Dati Azure Maps, che può consentire operazioni di lettura/scrittura di dati non autorizzate sulle API REST di Mappe di Azure, portando all'esposizione di dati sensibili o a costi imprevisti.

Sono disponibili due opzioni per revocare l'accesso per i token SAS:

  1. Rigenerare la chiave usata dal token SAS o dalla chiave secondaria dell'account mappa.
  2. Rimuovere l'assegnazione di ruolo per l'identità gestita sull'account associato alla mappa.

Avviso

L'eliminazione di un'identità gestita usata da un token di firma di accesso condiviso o la revoca del controllo di accesso dell'identità gestita può comportare istanze dell'applicazione usando il token di firma di accesso condiviso e l'identità gestita da restituire 401 Unauthorized o 403 Forbidden dalle API REST di Mappe di Azure, causando potenziali interruzioni dell'applicazione.

Per evitare interruzioni:

  1. Aggiungere una seconda identità gestita all'account Mappe di Azure e concedere alla nuova identità gestita l'assegnazione di ruolo corretta.
  2. Creare un token SAS usando secondaryKey o un'identità gestita diversa da quella precedente, come signingKey, e distribuire il nuovo token SAS all'applicazione.
  3. Rigenerare la chiave primaria, rimuovere l'identità gestita dall'account e rimuovere l'assegnazione di ruolo per l'identità gestita.

Creare token di firma di accesso condiviso

Per creare token SAS, è necessario avere accesso con il ruolo Contributor sia per gestire gli account Azure Maps sia le identità assegnate dall'utente nella sottoscrizione di Azure.

Importante

Gli account Mappe di Azure esistenti creati nella località di Azure global non supportano le identità gestite.

Prima di tutto, è necessario creare un'identità gestita assegnata dall'utente nella stessa località dell'account Mappe di Azure.

Suggerimento

È consigliabile usare la stessa località sia per l'identità gestita che per l'account Mappe di Azure.

Dopo aver creato un'identità gestita, è possibile creare o aggiornare l'account Mappe di Azure e collegarlo. Per altre informazioni, vedere Gestire l'account Mappe di Azure.

Dopo aver creato o aggiornato correttamente l'account con l'identità gestita, assegnare il controllo degli accessi in base al ruolo per l'identità gestita a un ruolo dati di Mappe di Azure nell'ambito dell'account. In questo modo l'identità gestita può ottenere l'accesso all'API REST di Azure Maps per il tuo account mappa.

Creare quindi un token SAS usando gli strumenti di Azure Management SDK, l'operazione di elenco SAS nell'API di gestione account oppure la pagina Firma di accesso condiviso del portale di Azure della risorsa account mappa.

Parametri del token SAS:

Il nome del parametro Valore di esempio Descrizione
chiave di firma primaryKey Obbligatorio, il valore di enumerazione stringa per signingKey, primaryKey, secondaryKey o l'identità gestita, viene usato per creare la firma del token SAS.
ID principale <GUID> Obbligatorio, principalId è l'ID oggetto (entità) dell'identità gestita assegnata dall'utente collegata all'account mappa.
regioni [ "eastus", "westus2", "westcentralus" ] Facoltativo, il valore predefinito è null. Le regioni controllano in quali regioni il token SAS può essere utilizzato nell'API REST del piano dati di Azure Maps. L'omissione del parametro regions consente l'uso senza vincoli del token SAS. Se usato in combinazione con un endpoint geografico del piano dati di Mappe di Azure, ad esempio us.atlas.microsoft.com e eu.atlas.microsoft.com, consente all'applicazione di controllare l'utilizzo all'interno dell'area geografica specificata. In questo modo è possibile prevenire l'utilizzo in altre aree geografiche.
maxRatePerSecond 500 Obbligatorio, la richiesta massima approssimativa al secondo specificata a cui viene concesso il token SAS. Una volta raggiunto il limite, la velocità effettiva superiore viene limitata con il codice di stato HTTP 429 (TooManyRequests).
Inizio 2021-05-24T10:42:03.1567373Z Obbligatorio, una data UTC che specifica la data e l'ora in cui il token diventa attivo.
scadenza 2021-05-24T11:42:03.1567373Z Obbligatorio, una data UTC che specifica la data e l'ora di scadenza del token. La durata tra inizio e scadenza non può essere superiore a 24 ore.

Configurazione dell'applicazione con un token SAS

Dopo che l'applicazione ha ricevuto un token SAS, Azure Maps SDK e/o l'applicazione invia una richiesta HTTPS con l'intestazione HTTP necessaria seguente, oltre alle altre intestazioni HTTP dell'API REST:

Nome dell'intestazione Valore
Autorizzazione jwt-sas eyJ0e....HNIVN

Nota

jwt-sas è lo schema di autenticazione per indicare l'uso del token SAS. Non includere x-ms-client-id o altre intestazioni di autorizzazione o parametri di stringa di query subscription-key.

Condivisione delle risorse tra origini diverse (CORS)

CORS è un protocollo HTTP che consente a un'applicazione Web in esecuzione in un dominio di accedere alle risorse in un altro dominio. Nei browser Web è implementata una restrizione di sicurezza nota come criterio della stessa origine che impedisce a una pagina Web di chiamare API in un dominio differente. CORS offre una modalità sicura per consentire a un dominio (quello di origine) di chiamare API in un altro dominio. Usando la risorsa dell'account Mappe di Azure, è possibile configurare le origini autorizzate ad accedere all'API REST di Mappe di Azure dalle applicazioni.

Importante

CORS non è un meccanismo di autorizzazione. Le richieste effettuate a un account di mapping tramite l'API REST, quando CORS è abilitato, richiede anche uno schema di autenticazione dell'account mappa valido, ad esempio chiave condivisa, Microsoft Entra ID o token di firma di accesso condiviso.

CORS è supportato per tutti i piani tariffari dell'account mappa, gli endpoint del piano dati e le località.

Prerequisiti

Per impedire l'esecuzione di codice dannoso nel client, i browser moderni bloccano le richieste da applicazioni Web alle risorse in esecuzione in un dominio separato.

  • Se non si ha familiarità con CORS, vedere Condivisione di risorse tra le origini (CORS). Consente a un'intestazione Access-Control-Allow-Origin di dichiarare quali origini sono autorizzate a chiamare gli endpoint di un account Mappe di Azure. Il protocollo CORS non è specifico di Mappe di Azure.

Richieste CORS

Una richiesta CORS proveniente da un dominio di origine può essere costituita da due richieste distinte:

  • Una richiesta preliminare che verifica le restrizioni CORS imposte dal servizio. La richiesta preliminare è obbligatoria, a meno che la richiesta non sia un metodo standard GET, HEAD, POST o richieste che contengono un'intestazione di richiesta Authorization.

  • La richiesta effettiva, effettuata alla risorsa desiderata.

Richiesta preliminare

La richiesta preliminare è una misura di sicurezza ed inoltre garantisce che il server comprenda il metodo e i header inviati nella richiesta effettiva, verifichi la provenienza della richiesta ed esamini le restrizioni CORS stabilite per l'account mappa. Il Web browser (o un altro agente utente) invia una richiesta OPTIONS che include le intestazioni della richiesta, il metodo e il dominio di origine. Il servizio dell'account mappa tenta di recuperare le regole CORS se l'autenticazione dell'account è possibile tramite il protocollo preliminare CORS.

Se l'autenticazione non è possibile, il servizio Mappe valuta un set preconfigurato di regole CORS che specificano quali domini di origine, metodi di richiesta e intestazioni di richiesta possono essere specificati in una richiesta effettiva al servizio mappe. Per impostazione predefinita, un account Mappe è configurato per consentire tutte le origini, per rendere possibile l'integrazione senza problemi nei Web browser.

Il servizio risponde alla richiesta preliminare con le intestazioni Access-Control obbligatorie se vengono soddisfatti i criteri seguenti:

  1. La richiesta OPTIONS contiene le intestazioni CORS obbligatorie (intestazioni Origin e Access-Control-Request-Method)
  2. L'autenticazione è riuscita e per l'account che corrisponde alla richiesta preliminare è abilitata una regola CORS.
  3. L'autenticazione è stata ignorata a causa di intestazioni della richiesta Authorization obbligatorie che non possono essere specificate nella richiesta preliminare.

Quando la richiesta preliminare ha esito positivo, il servizio risponde con il codice di stato 200 (OK) e include le intestazioni Access-Control obbligatorie nella risposta.

Il servizio rifiuta le richieste preliminari se si verificano le condizioni seguenti:

  1. Se la richiesta OPTIONS non contiene le intestazioni CORS obbligatorie (intestazioni Origin e Access-Control-Request-Method), il servizio risponde con il codice di stato 400 (Bad request).
  2. Se l'autenticazione ha avuto esito positivo nella richiesta preliminare e nessuna regola CORS corrisponde alla richiesta preliminare, il servizio risponde con il codice di stato 403 (Forbidden). Questo problema può verificarsi se la regola CORS è configurata per accettare un'origine che non corrisponde all'intestazione della richiesta di origine client del browser corrente.

Nota

Una richiesta preliminare viene valutata rispetto al servizio e non rispetto alla risorsa richiesta. Affinché la richiesta abbia esito positivo, il proprietario dell'account deve aver abilitato CORS configurando le proprietà dell'account appropriate.

Richiesta effettiva

Una volta accettata la richiesta preliminare e ottenuta la risposta, il browser invia la richiesta effettiva al servizio delle mappe. Se la richiesta preliminare viene rifiutata, il browser rifiuta immediatamente la richiesta effettiva.

La richiesta effettiva viene trattata come una normale richiesta al servizio mappa. La presenza dell'intestazione Origin indica che la richiesta è una richiesta CORS e il servizio convalida quindi rispetto alle regole CORS. Se viene rilevata una corrispondenza, le intestazioni Access-Control vengono aggiunte alla risposta e inviate di nuovo al client. Se non viene trovata una corrispondenza, la risposta restituisce un valore 403 (Forbidden) che indica un errore di origine CORS.

Abilitare i criteri CORS

Quando un account map viene creato o aggiornato, le relative proprietà definiscono le origini consentite. Una regola CORS può essere impostata sulle proprietà dell'account Mappe di Azure tramite il SDK di gestione Mappe di Azure, l'API REST di gestione Mappe di Azure e il portale. Dopo aver impostato la regola CORS per il servizio, le richieste autorizzate provenienti da domini diversi vengono valutate per garantire la conformità con la regola specificata. Ad esempio:

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

È possibile specificare una sola regola CORS con il relativo elenco di origini consentite. Ogni origine consente di effettuare la richiesta HTTP all'API REST di Mappe di Azure nel Web browser dell'origine specificata.

Rimuovere la politica CORS

È possibile rimuovere CORS:

  • Manualmente nel portale di Azure
  • A livello di programmazione, tramite:
    • Azure Maps SDK
    • API REST di gestione di Mappe di Azure
    • Un modello di ARM

Suggerimento

Se si usa l'API REST di gestione Mappe di Azure, usare PUT o PATCH con un elenco vuoto corsRule nel corpo della richiesta.

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

Informazioni sulle transazioni di fatturazione

Le Azure Maps non contabilizzano le transazioni di fatturazione per:

  • Codici di stato HTTP 5xx
  • 401 (Non autorizzato)
  • 403 (accesso negato)
  • 408 (timeout)
  • 429 (TroppiRichieste)
  • Richieste preliminari CORS

Per altre informazioni sulle transazioni di fatturazione e sui prezzi di Mappe di Azure, vedere Prezzi di Mappe di Azure.

Passaggi successivi

Per altre informazioni sulle procedure consigliate per la sicurezza, vedere:

Procedure consigliate per l'autenticazione e l'autorizzazione

Per altre informazioni sull'autenticazione di un'applicazione con Microsoft Entra ID e Mappe di Azure, vedere:

Gestire l'autenticazione in Mappe di Azure

Per altre informazioni sull'autenticazione del controllo di Mappe di Azure con Microsoft Entra ID, vedere:

Usare il controllo mappa di Azure Maps