Autenticazione e autorizzazione per l'API Azure Time Series Insights

Nota

Il servizio Time Series Insights (TSI) non sarà più supportato dopo marzo 2025. Valutare la possibilità di eseguire la migrazione di ambienti Time Series Insights esistenti a soluzioni alternative il prima possibile. Per altre informazioni sulla deprecazione e la migrazione, visitare la documentazione.

A seconda delle esigenze aziendali, la soluzione potrebbe includere una o più applicazioni client usate per interagire con le API dell'ambiente Azure Time Series Insights. Azure Time Series Insights esegue l'autenticazione usando i token di sicurezza di Microsoft Entra basati su OAUTH 2.0. Per autenticare i client, è necessario ottenere un token di connessione con le autorizzazioni appropriate e passarlo insieme alle chiamate API. Questo documento descrive diversi metodi per ottenere le credenziali che è possibile usare per ottenere un token di connessione ed eseguire l'autenticazione, tra cui l'uso dell'identità gestita e la registrazione dell'app Microsoft Entra.

Identità gestite

Le sezioni seguenti descrivono come usare un'identità gestita da Microsoft Entra ID per accedere all'API Azure Time Series Insights. In Azure le identità gestite eliminano la necessità di gestire le credenziali fornendo un'identità per la risorsa di Azure in Microsoft Entra ID che è possibile usare per ottenere i token di Microsoft Entra. Ecco alcuni vantaggi derivanti dall'uso delle identità gestite:

• Non è necessario gestire le credenziali. Le credenziali non sono neanche accessibili.
• È possibile usare le identità gestite per eseguire l'autenticazione a qualsiasi servizio di Azure che supporti l'autenticazione di Microsoft Entra, incluso Azure Key Vault.
• Le identità gestite possono essere usate senza costi aggiuntivi.

Per altre informazioni sui due tipi di identità gestite, vedere Che cosa sono le identità gestite per le risorse di Azure?

È possibile usare le identità gestite dall'utente:

• Macchine virtuali di Azure
• Servizi app di Azure
• Funzioni di Azure
• Istanze di Azure Container
• e altro ancora ...

Per l'elenco completo, vedere Servizi di Azure che supportano le identità gestite per le risorse di Azure.

Registrazione di app Microsoft Entra

È consigliabile usare le identità gestite, quando possibile, in modo che non sia necessario gestire le credenziali. Se l'applicazione client non è ospitata in un servizio di Azure che supporta le identità gestite, è possibile registrare l'applicazione con un tenant di Microsoft Entra. Quando si registra l'applicazione con Microsoft Entra ID, si sta creando una configurazione di identità per l'applicazione che consente l'integrazione con Microsoft Entra ID. Quando si registra un'app nel portale di Azure, si sceglie se si tratta di un singolo tenant (accessibile solo nel tenant) o multi-tenant (accessibile in altri tenant) e facoltativamente impostare un URI di reindirizzamento (in cui viene inviato il token di accesso).

Dopo aver completato la registrazione dell'app, si dispone di un'istanza univoca globale dell'app (l'oggetto applicazione) che si trova all'interno del tenant o della directory principale. È anche disponibile un ID univoco globale per l'app (l'ID app o client). Nel portale è quindi possibile aggiungere segreti o certificati e ambiti per consentire all'app di funzionare, effettuare la personalizzazione dell'app nella finestra di dialogo di accesso e altro ancora.

Se si registra un'applicazione nel portale, un oggetto applicazione e un oggetto entità servizio vengono creati automaticamente nel tenant principale. Se si registra/crea un'applicazione usando le API Microsoft Graph, la creazione dell'oggetto entità servizio è un passaggio separato. Per richiedere i token, è necessario un oggetto entità servizio.

Assicurarsi di esaminare l'elenco di controllo della sicurezza per l'applicazione. Come procedura consigliata, è consigliabile usare le credenziali del certificato, non le credenziali della password (segreti client).

Per altri dettagli, vedere Oggetti applicazione e entità servizio in Microsoft Entra ID .

Passaggio 1: Creare l'identità gestita o la registrazione dell'app

Dopo aver identificato se si userà un'identità gestita o una registrazione dell'app, il passaggio successivo consiste nel effettuarne il provisioning.

Identità gestita

I passaggi che verranno usati per creare un'identità gestita variano a seconda della posizione del codice e se si sta creando o meno un'identità assegnata dal sistema o assegnata dall'utente. Leggere Tipi di identità gestiti per comprendere la differenza. Dopo aver selezionato il tipo di identità, individuare e seguire l'esercitazione corretta nella documentazione sulle identità gestite di Microsoft Entra. Sono disponibili istruzioni per configurare le identità gestite per:

• Macchine virtuali di Azure
• servizio app e Funzioni di Azure
• Istanze di Azure Container
• e altro ancora ...

Registrazione dell'applicazione

Seguire i passaggi elencati in Registrare un'applicazione.

• Dopo aver selezionato la piattaforma appropriata nel passaggio 4 di Configurare le impostazioni della piattaforma , configurare gli URI di reindirizzamento e i token di accesso nel pannello laterale a destra dell'interfaccia utente.

  • È necessario che quanto specificato per URI di reindirizzamento corrisponda all'indirizzo fornito dalla richiesta di autenticazione:

    • Per le app ospitate in un ambiente di sviluppo locale, selezionare Client pubblico (per dispositivi mobili e desktop). Assicurarsi di impostare client pubblico su Sì.
    • Per le app a pagina singola ospitate nel servizio app di Azure, selezionare Web.

  • Determinare se è appropriato impostare un URL di disconnessione.

  • Abilitare il flusso di concessione implicita selezionando Token di accesso o Token ID.

  

  Fare clic su Configura e quindi su Salva.

• Associare l'app Microsoft Entra Azure Time Series Insights. Selezionare Autorizzazioni API>Aggiungi un'autorizzazione>API usate dall'organizzazione.

  

  Digitare Azure Time Series Insights nella barra di ricerca e quindi selezionare Azure Time Series Insights.

• Specificare quindi il tipo di autorizzazione API richiesto dall'app. Per impostazione predefinita sarà evidenziata l'opzione Autorizzazioni delegate. Scegliere un tipo di autorizzazione e quindi selezionare Aggiungi autorizzazioni.

  

• Aggiungere credenziali se l'applicazione chiamerà le API dell'ambiente come se stesso. Le credenziali consentono all'applicazione di eseguire l'autenticazione in modo autonomo, senza richiedere alcuna interazione utente in fase di esecuzione.

Passaggio 2: Concedere l'accesso

Quando l'ambiente Azure Time Series Insights riceve una richiesta, viene convalidato il token di connessione del chiamante. Se la convalida viene superata, il chiamante è stato autenticato e quindi viene effettuato un altro controllo per assicurarsi che il chiamante sia autorizzato a eseguire l'azione richiesta. Per autorizzare qualsiasi utente o entità servizio, è prima necessario concedere loro l'accesso all'ambiente assegnando loro il ruolo Lettore o Collaboratore.

• Per concedere l'accesso tramite l'interfaccia utente di portale di Azure, seguire le istruzioni elencate nell'articolo Concedere l'accesso ai dati a un ambiente. Quando si seleziona l'utente, è possibile cercare l'identità gestita o la registrazione dell'app in base al nome o all'ID.

• Per concedere l'accesso tramite l'interfaccia della riga di comando di Azure, eseguire il comando seguente. Vedere la documentazione qui per l'elenco completo dei comandi disponibili per gestire l'accesso.

  az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"
  

Nota

L'estensione timeseriesinsights per l'interfaccia della riga di comando di Azure richiede la versione 2.11.0 o successiva. L'estensione installerà automaticamente la prima volta che si esegue un comando az tsi access-policy. Altre informazioni sulle estensioni.

Passaggio 3: Richiesta di token

Dopo il provisioning e l'assegnazione di un ruolo all'identità gestita o alla registrazione dell'app, è possibile iniziare a usarla per richiedere token di connessione OAuth 2.0. Il metodo usato per ottenere un token varia a seconda della posizione in cui è ospitato il codice e del linguaggio preferito. Quando si specifica la risorsa (nota anche come "gruppo di destinatari" del token), è possibile identificare Azure Time Series Insights in base al relativo URL o GUID:

• https://api.timeseries.azure.com/
• 120d688d-1518-4cf7-bd38-182f158850b6

Importante

Se si usa l'URL come ID risorsa, il token deve essere emesso esattamente a https://api.timeseries.azure.com/. La barra finale è obbligatoria.

• Se si usa Postman l'AuthURL sarà quindi:https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
• https://api.timeseries.azure.com/ è valido, ma https://api.timeseries.azure.com non lo è.

Identità gestite

Quando si accede da app Azure Servizio o Funzioni, seguire le indicazioni riportate in Ottenere i token per le risorse di Azure.

Per le applicazioni e le funzioni .NET, il modo più semplice per usare un'identità gestita consiste nell'usare la libreria client di Identità di Azure per .NET. Questa libreria client è molto diffusa grazie ai vantaggi di semplicità e sicurezza. Gli sviluppatori possono scrivere codice una sola volta e consentire alla libreria client di determinare come eseguire l'autenticazione in base all'ambiente dell'applicazione, indipendentemente dal fatto che in una workstation per sviluppatori usi l'account di uno sviluppatore o distribuito in Azure usando un'identità del servizio gestito. Per indicazioni sulla migrazione dalla libreria AppAuthentication precedente, vedere AppAuthentication to Azure.Identity Migration Guidance (AppAuthentication to Azure.Identity Migration Guidance).

Richiedere un token per Azure Time Series Insights usando C# e la libreria client di Identità di Azure per .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Registrazione app

• Usare Microsoft Authentication Library (MSAL) per ottenere i token per le registrazioni delle app.

MSAL può essere usato in molti scenari di applicazione, tra cui, ad esempio:

• Applicazioni a pagina singola (JavaScript)
• Applicazione Web per l'accesso di un utente e la chiamata di un'API Web per conto dell'utente
• API Web che chiama un'altra API Web downstream per conto dell'utente che ha eseguito l'accesso
• Applicazione desktop che chiama un'API Web per conto dell'utente che ha eseguito l'accesso
• Applicazione per dispositivi mobili che chiama un'API Web per conto dell'utente che ha eseguito l'accesso in modo interattivo.
• Applicazione daemon di servizio/desktop che chiama un'API Web per proprio conto

Per il codice C# di esempio che illustra come acquisire un token come registrazione dell'app ed eseguire query sui dati da un ambiente Gen2, visualizzare l'app di esempio in GitHub

Importante

Se si usa Azure Active Directory Authentication Library (ADAL), eseguire la migrazione a MSAL.

Intestazioni e parametri comuni

Questa sezione descrive le intestazioni e i parametri di richiesta HTTP comuni usati per eseguire query sulle API di Azure Time Series Insights Gen1 e Gen2. I requisiti specifici dell'API sono trattati in modo più dettagliato nella documentazione di riferimento dell'API REST di Azure Time Series Insights.

Suggerimento

Vedere Informazioni di riferimento sull'API REST di Azure per altre informazioni su come usare le API REST, effettuare richieste HTTP e gestire le risposte HTTP.

Intestazioni HTTP

Di seguito sono descritte le intestazioni della richiesta obbligatorie.

Intestazione della richiesta obbligatoria	Descrizione
Autorizzazione	Per eseguire l'autenticazione con Azure Time Series Insights, è necessario passare un token di connessione OAuth 2.0 valido nell'intestazione authorization.

Suggerimento

Leggere la visualizzazione di esempio dell'SDK client di Azure Time Series Insights ospitata per informazioni su come eseguire l'autenticazione con le API di Azure Time Series Insights a livello di codice usando JavaScript Client SDK insieme a grafici e grafici.

Di seguito sono descritte le intestazioni della richiesta facoltative.

Intestazione di richiesta facoltativa	Descrizione
Tipo di contenuto	È supportato solo application/json.
x-ms-client-request-id	ID della richiesta client. Il servizio registra questo valore. Consente al servizio di tenere traccia dell'operazione nei diversi servizi.
x-ms-client-session-id	ID della sessione client. Il servizio registra questo valore. Consente al servizio di tenere traccia di un gruppo di operazioni correlate nei diversi servizi.
x-ms-client-application-name	Nome dell'applicazione che ha generato questa richiesta. Il servizio registra questo valore.

Di seguito sono descritte le intestazioni della risposta facoltative ma consigliate.

Intestazione risposta	Descrizione
Tipo di contenuto	È supportato solo application/json.
x-ms-request-id	ID della richiesta generato dal server. Può essere usato per contattare Microsoft se dovesse essere necessario esaminare una richiesta.
x-ms-Property-not-found-Behavior	Intestazione della risposta facoltativa dell'API di disponibilità generale. I valori possibili sono ThrowError (impostazione predefinita) o UseNull.

Parametri HTTP

Suggerimento

Per approfondire le informazioni sulle query obbligatorie e facoltative, vedere la documentazione di riferimento.

I parametri della stringa di query dell'URL obbligatori dipendono dalla versione dell'API.

Versione	Valori della versione dell'API
Prima generazione	api-version=2016-12-12
Seconda generazione	api-version=2020-07-31

I parametri della stringa di query dell'URL facoltativi includono l'impostazione di un timeout per i tempi di esecuzione della richiesta HTTP.

Parametro di query facoltativo	Descrizione	Versione
timeout=<timeout>	Timeout lato server per l'esecuzione di una richiesta HTTP. Applicabile solo alle API Get Environment Events e Get Environment Aggregates. Il valore di timeout deve essere nel formato di durata ISO 8601, ad esempio "PT20S", e deve essere compreso nell'intervallo 1-30 s. Il valore predefinito è 30 s.	Prima generazione
storeType=<storeType>	Per gli ambienti Gen2 con archivio ad accesso frequente abilitato, la query può essere eseguita in WarmStore o ColdStore. Questo parametro nella query definisce l'archivio in cui quest'ultima deve essere eseguita. Se non è definito, la query verrà eseguita nell'archivio ad accesso sporadico. Per eseguire la query nell'archivio ad accesso frequente, occorre impostare storeType su WarmStore. Se non è definito, la query verrà eseguita nell'archivio ad accesso sporadico.	Seconda generazione

Passaggi successivi

• Per il codice di esempio che chiama l'API Azure Time Series Insights gen1, leggere Eseguire query sui dati gen1 usando C#.

• Per il codice di esempio che chiama gli esempi di codice dell'API Azure Time Series Insights gen2, leggere Eseguire query sui dati gen2 usando C#.

• Per le informazioni di riferimento sull'API, vedere la documentazione di riferimento sull'API di query.