Autenticazione con Mappe di Azure

Mappe di Azure supporta tre modi per autenticare le richieste: autenticazione con chiave condivisa, autenticazione di Microsoft Entra ID e autenticazione con token di firma di accesso condiviso (SAS). Questo articolo illustra i metodi di autenticazione per guidare il processo di implementazione dei servizi Mappe di Azure. L'articolo descrive anche altri controlli dell'account, ad esempio la disabilitazione dell'autenticazione locale per Criteri di Azure e la condivisione di risorse tra origini (CORS).

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 dopo la creazione dell'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

Autenticazione 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, 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 possono richiedere esperienze di accesso utente, altre possono richiedere un'esperienza di accesso dell'applicazione. 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:

Di seguito è riportato un esempio di richiesta di route di Mappe di Azure che usa un token di connessione 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.

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

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

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 tipi di entità a cui viene concesso un set 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'entità di sicurezza, una definizione di ruolo e un ambito.

Panoramica

Le sezioni successive illustrano i concetti e i componenti dell'integrazione di Mappe di Azure con il controllo degli accessi in base al ruolo di Azure. Come parte del processo per configurare l'account Mappe di Azure, una directory di Microsoft Entra viene associata alla sottoscrizione di Azure in cui risiede l'account Mappe di Azure.

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.

Alcuni servizi di Mappe di Azure possono richiedere privilegi elevati per eseguire azioni di scrittura o eliminazione nelle API REST di 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 a cui è applicabile il ruolo Collaboratore per i dati di Mappe di Azure quando si usano azioni di scrittura o eliminazione. Quando sono necessarie solo azioni di lettura, è possibile usare il Ruolo con autorizzazioni di lettura per i dati di Mappe di Azure al posto del ruolo Collaboratore per i dati di Mappe di Azure.

¹ Creator di Mappe di Azure, il Registro dati e i servizi spaziali sono ora deprecati e verranno ritirati il 30/9/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.

Sarà quindi possibile usare la definizione del ruolo personalizzata in un'assegnazione di ruolo per qualsiasi entità 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.

Informazioni sull'ambito

Quando si crea un'assegnazione di ruolo, viene definita all'interno della gerarchia di risorse di Azure. In cima alla gerarchia c'è un gruppo di gestione e in fondo c'è una risorsa di Azure, ad esempio un account Mappe di Azure. Concedere un'assegnazione di ruolo a un gruppo di risorse può consentire l'accesso a più account o risorse di Mappe di Azure nel gruppo.

Disabilita autenticazione locale

Gli account Mappe di Azure supportano la proprietà di Azure standard nell'API Gestione per Microsoft.Maps/accounts denominata disableLocalAuth. Quando è true, l'autenticazione per l'API REST del piano dati di Mappe di Azure è disabilitata, 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. Dopo qualche minuto riprenderà 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) sono token di autenticazione creati usando il formato token JSON Web (JWT) e sono firmati a livello di crittografia per dimostrare l'autenticazione di un'applicazione all'API REST di Mappe di Azure. Un token SAS viene creato integrando un'identità gestita assegnata dall'utente con un account Mappe di Azure della sottoscrizione di Azure. L'identità gestita assegnata dall'utente riceve l'autorizzazione all'account Mappe di Azure tramite il controllo degli accessi in base al ruolo di Azure, mediante definizioni del ruolo predefinite o personalizzate.

Differenze di funzionamento principali tra token SAS e token di accesso di 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 di firma di accesso condiviso non sono modificabili. Di conseguenza, una volta che ne è stato creato uno, il token sarà valido fino alla scadenza e la configurazione delle aree consentite, dei limiti di velocità e dell'identità gestita assegnata dall'utente non possono subire modifiche. Leggere la sezione sul controllo di accesso per informazioni sulla revoca dei token SAS e sulle modifiche al 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 specifica un limite di velocità massimo per il token (maxRatePerSecond), le tariffe in eccesso non vengono fatturate all'account. Questo consente di impostare un limite massimo di transazioni fatturabili per l'account quando si usa il token. Una volta raggiunto tale limite, tuttavia, l'applicazione riceve risposte di errore client con 429 (TooManyRequests) per tutte le transazioni. È responsabilità dell'applicazione gestire i nuovi tentativi e la distribuzione dei token SAS. Non esistono limiti al numero di token SAS che è possibile creare per un account. Per poter apportare un aumento o una diminuzione al limite di un token esistente, è necessario creare un nuovo token SAS. Il token SAS precedente resta fino alla scadenza.

Esempio stimato:

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. Per controllare i costi e migliorare la prevedibilità, è consigliabile:

1. Creare token SAS con località di Azure designate per l'area geografica di destinazione. Continuare a leggere per comprendere la creazione dei token SAS.
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 velocità di Mappe di Azure, le singole offerte di servizio hanno limiti di velocità variabili, che vengono applicati come aggregazione dell'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 riuscite dall'utilizzo 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).

Ad esempio, se due token SAS vengano creati e usati nella stessa località di un account Mappe di Azure, ogni token condivide ora il limite di velocità predefinito di 250 QPS. Se ogni token viene usato contemporaneamente con la stessa velocità effettiva, token 1 e token 2 concedono correttamente 7500 transazioni riuscite ciascuno.

Informazioni sul controllo di accesso con token SAS

I token SAS usano il controllo degli accessi in base al ruolo per controllare 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.

Se si vuole assegnare un accesso temporaneo e rimuovere l'accesso prima della scadenza del token SAS, revocare il token. Un altro motivo per revocare l'accesso può essere se il token SAS viene involontariamente distribuito con l'assegnazione di ruolo Azure Maps Data Contributor e chiunque disponga del token può leggere e scrivere dati nelle API REST di Mappe di Azure, che potrebbero esporre dati sensibili o comportare costi finanziari imprevisti derivanti dall'utilizzo.

Esistono due possibilità 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 nell'account mappa associato.

Creare token di firma di accesso condiviso

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

Prima di tutto, è necessario creare un'identità gestita assegnata dall'utente nella stessa località dell'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 è possibile assegnare all'identità gestita l'accesso all'API REST di Mappe di Azure per l'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:

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:

Condivisione di risorse tra le origini (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.

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 esegue query sulle restrizioni di CORS imposte dal servizio. La richiesta preliminare è obbligatoria, a meno che la richiesta non sia un metodo standard GET, HEAD, POST o contenga l'intestazione della richiesta Authorization.

• La richiesta effettiva, effettuata alla risorsa desiderata.

Richiesta preliminare

La richiesta preliminare viene eseguita come misura di sicurezza per garantire che il server comprenda il metodo e le intestazioni inviate nella richiesta effettiva e che il server conosca e consideri attendibile l'origine della richiesta. Inoltre, esegue anche una query sulle restrizioni CORS stabilite per l'account mappa. Dal Web browser (o da altro agente utente) viene inviata 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.

Richiesta effettiva

Una volta accettata la richiesta preliminare e restituita la risposta, il browser invia la richiesta effettiva al servizio mappa. 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 viene creato o aggiornato un account mappa, le relative proprietà specificano le origini consentite da configurare. È possibile impostare una regola CORS nelle proprietà dell'account Mappe di Azure tramite l'SDK di gestione di Mappe di Azure, l'API REST di gestione di Mappe di Azure e il portale. Una volta impostata la regola CORS per il servizio, una richiesta correttamente autorizzata, eseguita al servizio da un dominio diverso, viene valutata per determinare se è consentita in base alle regole specificate. 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 i criteri 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

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

Informazioni sulle transazioni di fatturazione

Mappe di Azure non conta le transazioni di fatturazione per:

• Codici di stato HTTP 5xx
• 401 (Non autorizzato)
• 403 (accesso negato)
• 408 (Timeout)
• 429 (TooManyRequests)
• 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:

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

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