Autenticazione con Mappe di Azure

  • Articolo

Mappe di Azure supporta tre modi per autenticare le richieste: autenticazione con chiave condivisa, autenticazione dell'ID di Accesso condiviso e autenticazione del token di firma di accesso condiviso. Questo articolo illustra i metodi di autenticazione per facilitare l'implementazione dei servizi di Mappe di Azure. L'articolo descrive anche altri controlli 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 supportiamo Transport Layer Security (TLS) 1.2 e stiamo ritirando il supporto per TLS 1.0 e 1.1. Se attualmente si usa TLS 1.x, valutare l'idoneità di TLS 1.2 e sviluppare un piano di migrazione con i test descritti in Risoluzione del problema di TLS 1.0.

Autenticazione con chiave condivisa

Per informazioni sulla visualizzazione delle chiavi nella portale di Azure, vedere Visualizzare i dettagli dell'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 con 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 di Mappe di Azure servizi, aggiungere la chiave di sottoscrizione come parametro all'URL. La chiave secondaria può essere usata in scenari come modifiche delle chiavi in sequenza.

Esempio di uso della chiave di sottoscrizione come parametro nell'URL:

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

Importante

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

Autenticazione Microsoft Entra

Le sottoscrizioni di Azure vengono fornite con un tenant di Microsoft Entra per abilitare un controllo di accesso granulare. Mappe di Azure offre l'autenticazione per i servizi di Mappe di Azure tramite Microsoft Entra ID. Microsoft Entra ID fornisce l'autenticazione basata sull'identità per utenti e applicazioni 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 che contiene un account Mappe di Azure. Mappe di Azure accetta anche i 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 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 token per Mappe di Azure, vedere Gestire l'autenticazione in Mappe di Azure.For more information about how to configure Microsoft Entra ID and request tokens for Mappe di Azure, see Manage authentication in Mappe di Azure.

Per informazioni generali sull'autenticazione con Microsoft Entra ID, vedere 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 applicazioni gestite 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 delle identità gestite può essere autorizzata ad accedere ai servizi Mappe di Azure. Alcuni esempi di identità gestite includono: servizio app Azure, Funzioni di Azure e Azure Macchine virtuali. 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 microsoft Entra dell'applicazione

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

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

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

Nota

x-ms-client-id è il GUID basato sull'account di Mappe di Azure che compare nella pagina di autenticazione di Mappe di Azure.

Di seguito è riportato un esempio di richiesta di route Mappe di Azure che usa un token di connessione OAuth OAuth ID Microsoft Entra:

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 UniqueId Proprietà 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 az maps account show comando con il --query parametro , 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 il controllo degli accessi in base al ruolo di Azure, alla panoramica del controllo degli accessi in base al ruolo di Azure 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 Controllo degli accessi in base al ruolo di Azure, tra cui: singoli utenti, gruppi, applicazioni, risorse di Azure e identità gestite di Azure. L'applicazione dell'accesso a uno o più account Mappe di Azure è noto come ambito. Un'assegnazione di ruolo viene creata quando viene applicata un'entità, una definizione di ruolo e un ambito.

Panoramica

Le sezioni successive illustrano concetti e 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 Microsoft Entra è associata alla sottoscrizione di Azure, che 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 nella portale di Azure, vedere Assegnare ruoli di Azure usando il portale di Azure.

Selezione di una definizione di ruolo

Esistono i tipi di definizione di ruolo seguenti per supportare gli scenari dell'applicazione.

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

Alcuni servizi Mappe di Azure possono richiedere privilegi elevati per eseguire azioni di scrittura o eliminazione nelle API REST Mappe di Azure. Mappe di Azure ruolo Collaboratore dati è necessario per i servizi, che forniscono azioni di scrittura o eliminazione. La tabella seguente descrive quali servizi Mappe di Azure Collaboratore dati è applicabile quando si usano azioni di scrittura o eliminazione. Quando sono necessarie solo azioni di lettura, è possibile usare il ruolo lettore dati Mappe di Azure al posto del ruolo Collaboratore dati Mappe di Azure.

servizio Mappe di Azure definizione del ruolo Mappe di Azure
Dati Collaboratore dati Mappe di Azure
Creator Collaboratore dati Mappe di Azure
Spatial Collaboratore dati Mappe di Azure
Ricerca batch e route Collaboratore dati Mappe di Azure

Per informazioni sulla visualizzazione delle impostazioni del controllo degli accessi in base al ruolo di Azure, vedere Come configurare il controllo degli accessi in base al ruolo di Azure per Mappe di Azure.

Definizioni di ruolo personalizzate

Un aspetto della sicurezza delle applicazioni è il principio dei privilegi minimi, la pratica di limitare i diritti di accesso ai diritti necessari per il processo corrente. La limitazione dei diritti di accesso viene eseguita creando definizioni di ruolo personalizzate che supportano i casi d'uso che richiedono un'ulteriore granularità per il controllo di accesso. Per creare una definizione di ruolo personalizzata, selezionare azioni di dati specifiche da includere o escludere per la definizione.

La definizione di ruolo personalizzata può quindi essere usata 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.

Scenario Azioni personalizzate per i dati dei ruoli
Pagina Web di accesso pubblica o interattiva con riquadri della mappa di base e nessun'altra 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
Ruolo per un'entità di sicurezza, che richiede una lettura di Mappe di Azure api REST per i dati delle mappe basate su Creator e le API REST del riquadro della mappa di base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/render/read
Ruolo per un'entità di sicurezza, che richiede la lettura, la scrittura e l'eliminazione dei dati della mappa basata su Creator. Definito come ruolo dell'editor di dati della mappa che non consente l'accesso ad altre API REST, ad esempio riquadri della mappa di base. Microsoft.Maps/accounts/services/data/read, Microsoft.Maps/accounts/services/data/write, Microsoft.Maps/accounts/services/data/delete

Informazioni sull'ambito

Quando si crea un'assegnazione di ruolo, viene definita all'interno della gerarchia di risorse di Azure. La parte superiore della gerarchia è un gruppo di gestione e la più bassa è una risorsa di Azure, ad esempio un account Mappe di Azure. L'assegnazione di un'assegnazione di ruolo a un gruppo di risorse può consentire l'accesso a più account o risorse Mappe di Azure nel gruppo.

Suggerimento

La raccomandazione generale di Microsoft consiste nell'assegnare l'accesso all'ambito dell'account Mappe di Azure perché impedisce l'accesso non intenzionale ad altri account Mappe di Azure esistenti nella stessa sottoscrizione di Azure.

Disabilitare l'autenticazione locale

Mappe di Azure account supportano la proprietà standard di Azure in API di gestione per Microsoft.Maps/accounts denominata disableLocalAuth. Quando true, l'autenticazione per l'API REST del piano dati Mappe di Azure è disabilitata, ad eccezione dell'autenticazione di Microsoft Entra. Viene configurato usando Criteri di Azure per controllare la distribuzione e la gestione di chiavi condivise e 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 del token di firma di accesso condiviso

I token di firma di accesso condiviso (SAS) sono token di autenticazione creati usando il formato JWT (JSON Web Token) e sono firmati crittograficamente per dimostrare l'autenticazione per un'applicazione all'API REST Mappe di Azure. Un token di firma di accesso condiviso, creato integrando un'identità gestita assegnata dall'utente con un account Mappe di Azure nella sottoscrizione di Azure. All'identità gestita assegnata dall'utente viene concessa l'autorizzazione per l'account Mappe di Azure tramite il controllo degli accessi in base al ruolo di Azure usando definizioni di ruolo predefinite o personalizzate.

Differenze di chiave funzionale del token di firma di accesso condiviso dai token di accesso Microsoft Entra:

  • Durata di un token per una scadenza massima di un giorno (24 ore).
  • Posizione di Azure e controllo di accesso geografico per token.
  • Limiti di frequenza per token per un valore approssimativo da 1 a 500 richieste al secondo.
  • Le chiavi private del token sono le chiavi primarie e secondarie di una risorsa 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. Ciò significa che una volta creato un token, il token di firma di accesso condiviso è valido fino a quando non viene soddisfatta la scadenza e non è possibile modificare la configurazione delle aree consentite, dei limiti di frequenza e dell'identità gestita assegnata dall'utente. Per altre informazioni sul controllo di accesso per la revoca dei token di firma di accesso condiviso e sulle modifiche apportate al controllo di accesso, vedere di seguito.

Informazioni sui limiti di frequenza dei token di firma di accesso condiviso

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

Quando si specifica un limite di velocità massimo per il token (maxRatePerSecond), le tariffe in eccesso non vengono fatturate all'account che consente di impostare un limite massimo di transazioni fatturabili per l'account, quando si usa il token. Tuttavia, l'applicazione riceve risposte di errore client con 429 (TooManyRequests) per tutte le transazioni una volta raggiunto tale limite. È responsabilità dell'applicazione gestire i tentativi e la distribuzione dei token di firma di accesso condiviso. Non esiste alcun limite al numero di token di firma di accesso condiviso che è possibile creare per un account. Per consentire un aumento o una diminuzione del limite di un token esistente; è necessario creare un nuovo token di firma di accesso condiviso. Il token di firma di accesso condiviso precedente è ancora valido fino alla scadenza.

Esempio stimato:

Frequenza massima approssimativa al secondo Velocità effettiva al secondo Durata della velocità sostenuta 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 entro un intervallo di tempo. Tuttavia, ciò consente il controllo preventivo dei costi di fatturazione.

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

Ad esempio, è possibile usare un singolo token di firma di accesso condiviso con un maxRatePerSecond valore pari a 10 per limitare la velocità effettiva nella East US posizione. Se lo stesso token viene usato in West US 2, viene creato un nuovo contatore per limitare la velocità effettiva a 10 in tale posizione, indipendentemente dalla East US posizione. Per controllare i costi e migliorare la prevedibilità, è consigliabile:

  1. Creare token di firma di accesso condiviso con località di Azure designate per l'area geografica di destinazione. Continuare a leggere per comprendere la creazione di token di firma di accesso condiviso.
  2. Usare gli endpoint dell'API REST del piano dati geografico 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 le stesse posizioni degli Stati Uniti ospitate dai servizi Mappe di Azure, ad esempio East US, West Central USo West US 2. La stessa idea si applica ad altri endpoint geografici, ad https://eu.atlas.microsoft.com esempio tra West Europe e North Europe. Per evitare denial di autorizzazione imprevisti, usare un token di firma di accesso condiviso che usa le stesse posizioni di Azure usate dall'applicazione. Il percorso dell'endpoint viene definito usando l'API REST di gestione Mappe di Azure.

I limiti di frequenza predefiniti accettano precedenti rispetto ai limiti di frequenza dei token di firma di accesso condiviso

Come descritto in Mappe di Azure limiti di frequenza, le singole offerte di servizi hanno limiti di frequenza variabili applicati come aggregazione dell'account.

Si consideri il caso di servizio di ricerca - Inverso non batch, con un 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 una richiesta massima al secondo di 500 e l'utilizzo effettivo dell'applicazione è di 500 richieste al secondo per una durata di 60 secondi. servizio di ricerca - Il reverse non batch ha un limite di velocità pari a 250, ovvero del totale di 30.000 richieste effettuate nei 60 secondi; 15.000 di tali richieste sono transazioni fatturabili. Le richieste rimanenti comportano il codice 429 (TooManyRequests)di stato .

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

Ad esempio, se vengono creati due token di firma di accesso condiviso in e si usa la stessa posizione di un account Mappe di Azure, ogni token condivide ora il limite di frequenza predefinito di 250 QPS. Se ogni token viene usato contemporaneamente con lo stesso token di velocità effettiva 1 e il token 2 concedono correttamente 7500 transazioni riuscite.

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

Informazioni sul controllo di accesso ai token di firma di accesso condiviso

I token di firma di accesso condiviso usano il controllo degli accessi in base al ruolo per controllare l'accesso all'API REST. Quando si crea un token di firma di accesso condiviso, all'identità gestita dei prerequisiti nell'account mappa viene assegnato un ruolo controllo degli accessi in base al ruolo di Azure che concede l'accesso a azioni API REST specifiche. Vedere Selezione di una definizione di ruolo per determinare le API consentite dall'applicazione.

Se si vuole assegnare l'accesso temporaneo e rimuovere l'accesso per prima della scadenza del token di firma di accesso condiviso, revocare il token. Altri motivi per revocare l'accesso possono essere se il token viene distribuito con Azure Maps Data Contributor l'assegnazione di ruolo in modo involontario e chiunque abbia il token di firma di accesso condiviso può essere in grado di leggere e scrivere dati in Mappe di Azure API REST che potrebbero esporre dati sensibili o costi finanziari imprevisti dall'utilizzo.

sono disponibili due opzioni per revocare l'accesso per i token di firma di accesso condiviso:

  1. Rigenerare la chiave usata dal token di firma di accesso condiviso o dalla chiave secondaria dell'account della mappa.
  2. Rimuovere l'assegnazione di ruolo per l'identità gestita nell'account mappa associato.

Avviso

Eliminando un'identità gestita usata da un token di firma di accesso condiviso o revocando il controllo di accesso dell'identità gestita, le istanze dell'applicazione usano il token di firma di accesso condiviso e l'identità gestita per restituire 401 Unauthorized intenzionalmente o 403 Forbidden da Mappe di Azure API REST che creeranno interruzioni dell'applicazione.

Per evitare interruzioni:

  1. Aggiungere una seconda identità gestita all'account mappa e concedere alla nuova identità gestita l'assegnazione di ruolo corretta.
  2. Creare un token di firma di accesso condiviso usando secondaryKeyo un'identità gestita diversa da quella precedente, come signingKey e distribuire il nuovo token di firma di accesso condiviso 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 di firma di accesso condiviso, è necessario avere Contributor accesso al ruolo sia per gestire gli account Mappe di Azure che per le identità assegnate dall'utente nella sottoscrizione di Azure.

Importante

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

In primo luogo, è necessario creare un'identità gestita assegnata dall'utente nella stessa posizione dell'account Mappe di Azure.

Suggerimento

È consigliabile usare la stessa posizione 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 Mappe di Azure nell'ambito dell'account. Ciò consente di assegnare all'identità gestita l'accesso all'API REST Mappe di Azure per l'account della mappa.

Creare quindi un token di firma di accesso condiviso usando gli strumenti di Azure Management SDK, elencare l'operazione di firma di accesso condiviso nell'API di gestione account o la pagina portale di Azure firma di accesso condiviso della risorsa dell'account mappa.

Parametri del token di firma di accesso condiviso:

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

Dopo che l'applicazione riceve un token di firma di accesso condiviso, l'SDK di Mappe di Azure e/o le applicazioni inviano una richiesta HTTPS con l'intestazione HTTP necessaria seguente, oltre ad altre intestazioni HTTP dell'API REST:

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

Nota

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

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 Mappe di Azure dalle applicazioni.

Importante

CORS non è un meccanismo di autorizzazione. Qualsiasi richiesta inviata a un account mappa usando l'API REST, quando CORS è abilitata, richiede anche uno schema di autenticazione dell'account mappa valido, ad esempio chiave condivisa, ID Microsoft Entra o token di firma di accesso condiviso.

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

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 per 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 richieste che contengono Authorization l'intestazione della richiesta.

  • La richiesta effettiva, effettuata alla risorsa desiderata.

Richiesta preliminare

La richiesta preliminare viene eseguita non solo 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, ma 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 account map 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 sul servizio mappe. Per impostazione predefinita, un account mappe è configurato per consentire a tutte le origini di abilitare l'integrazione senza problemi nei Web browser.

Il servizio risponde alla richiesta preliminare con le intestazioni di Controllo di accesso necessarie se vengono soddisfatti i criteri seguenti:

  1. La richiesta OPTIONS contiene le intestazioni CORS necessarie (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 di richiesta obbligatorie Authorization che non possono essere specificate nella richiesta preliminare.

Quando la richiesta preliminare ha esito positivo, il servizio risponde con il codice 200 (OK)di stato e include le intestazioni di Controllo di accesso necessarie nella risposta.

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

  1. Se la richiesta OPTIONS non contiene le intestazioni CORS necessarie (intestazioni Origin e Access-Control-Request-Method), il servizio risponde con il codice 400 (Bad request)di stato .
  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 403 (Forbidden)di stato . 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 alla risorsa richiesta. Il proprietario dell'account deve avere abilitato CORS impostando le proprietà dell'account appropriate affinché la richiesta abbia esito positivo.

Richiesta effettiva

Dopo che la richiesta preliminare viene accettata e la risposta viene restituita, il browser invia la richiesta effettiva al servizio mappe. Il browser nega immediatamente la richiesta effettiva se la richiesta preliminare viene rifiutata.

La richiesta effettiva viene considerata come una normale richiesta per il servizio map. 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 403 (Forbidden) valore che indica un errore di origine CORS.

Abilitare i criteri CORS

Quando viene creato o aggiornato un account map, le relative proprietà specificano le origini consentite da configurare. È possibile impostare una regola CORS sulle proprietà dell'account Mappe di Azure tramite Mappe di Azure Management SDK, l'API REST di gestione Mappe di Azure e il portale. Dopo aver impostato la regola CORS per il servizio, viene valutata una richiesta autorizzata correttamente al servizio da un dominio diverso per determinare se è consentita in base alla 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 per Mappe di Azure'API REST nel Web browser dell'origine specificata.

Rimuovere i criteri CORS

È possibile rimuovere CORS:

  • Manualmente nel portale di Azure
  • A livello di codice tramite:
    • SDK di Mappe di Azure
    • API REST di gestione Mappe di Azure
    • Un modello di Resource Manager

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

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 altre informazioni sui prezzi di Mappe di Azure, vedere Mappe di Azure prezzi.

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 Mappe di Azure con Microsoft Entra ID, vedere:

Usare il controllo mappa di Mappe di Azure