Panoramica delle linee guida per l'autenticazione dei carichi di lavoro in Microsoft Fabric

Questo articolo fornisce linee guida su come usare l'autenticazione quando si creano carichi di lavoro di Microsoft Fabric. Include informazioni sull'uso di token e consenso.

Prima di iniziare, assicurarsi di avere familiarità con i concetti descritti in Panoramica sull'autenticazione e Configurazione dell'autenticazione.

API del piano dati e del piano di controllo

• API del piano dati sono API esposte dal back-end del carico di lavoro. Il front-end del workload può chiamarli direttamente. Per le API del piano dati, il back-end del carico di lavoro può decidere quali API esporre.

• Le API del piano di controllo sono quelle che passano attraverso Fabric. Il processo inizia con il front-end del carico di lavoro che chiama un'API JavaScript e termina con Fabric che chiama il back-end del carico di lavoro. Un esempio di tale API è Creare un elemento.

  Per le API del piano di controllo, il carico di lavoro deve seguire i contratti definiti nel back-end del carico di lavoro e implementare tali API.

Esporre una scheda API nell'applicazione associata al carico di lavoro in Microsoft Entra ID

Nella scheda Esporre un'API, è necessario aggiungere ambiti per le API del piano di controllo e del piano dati.

• Gli ambiti aggiunti per le API del piano di controllo devono preautorizzare l'applicazione Fabric Client for Workloads con ID applicazione d2450708-699c-41e3-8077-b0c8341509aa. Questi ambiti sono inclusi nel token ricevuto dal back-end del carico di lavoro quando viene chiamato da Fabric.

  È necessario aggiungere almeno un ambito per l'API del control plane affinché il flusso funzioni.

• Gli ambiti aggiunti per le API del piano dati devono preautorizzare Microsoft Power BI con ID applicazione 871c010f-5e61-4fb1-83ac-98610a7e9110. Sono inclusi nel token restituito dall'API JavaScript acquireAccessToken.

  Per le API del piano dati, è possibile usare questa scheda per gestire autorizzazioni granulari per ogni API esposta dal carico di lavoro. Idealmente, è consigliabile aggiungere un set di ambiti per ogni API esposta dal back-end del carico di lavoro e verificare che il token ricevuto includa tali ambiti quando tali API vengono chiamate dal client. Per esempio:

  • Il carico di lavoro espone due API al client, ReadData e WriteData.
  • Il carico di lavoro espone due ambiti del piano dati, data.read e data.write.
  • Nell'API ReadData il carico di lavoro verifica che l'ambito data.read sia incluso nel token prima che continui con il flusso. Lo stesso vale per WriteData.

Scheda Autorizzazioni API nell'applicazione del carico di lavoro in Microsoft Entra ID

Nella scheda autorizzazioni API è necessario aggiungere tutti gli ambiti per cui il carico di lavoro deve scambiare un token. Un ambito di applicazione obbligatorio da aggiungere è Fabric.Extend sotto il servizio Power BI. Le richieste a Fabric potrebbero non riuscire senza questo ambito.

Uso di token e consenso

Quando si lavora con le API del piano dati, il frontend del carico di lavoro deve acquisire un token per le chiamate al backend del carico di lavoro.

Le sezioni seguenti descrivono come il front-end del carico di lavoro deve usare il api JavaScript e flussi OBO (On-Behalf-of) per acquisire token per il carico di lavoro e i servizi esterni e per lavorare con i consenso.

Passaggio 1: Acquisire un token

Il carico di lavoro inizia con la richiesta di un token usando l'API JavaScript senza fornire parametri. Questa chiamata può comportare due scenari:

• L'utente visualizza una finestra di consenso di tutte le dipendenze statiche (configurate nella scheda autorizzazioni API) configurate dal carico di lavoro. Questo scenario si verifica se l'utente non fa parte del tenant principale dell'applicazione e l'utente non ha concesso il consenso a Microsoft Graph per questa applicazione in precedenza.

• L'utente non visualizza una finestra di consenso. Questo scenario si verifica se l'utente ha già acconsentito almeno una volta a Microsoft Graph per questa applicazione o se l'utente fa parte del tenant principale dell'applicazione.

In entrambi gli scenari, il carico di lavoro non deve preoccuparsi se l'utente ha fornito o meno il consenso completo per tutte le dipendenze (e non può sapere a questo punto). Il token ricevuto ha l'audience del backend di workload e può essere usato per chiamare direttamente il backend di workload dal frontend di workload.

Passaggio 2: Provare ad accedere ai servizi esterni

Il carico di lavoro potrebbe dover accedere ai servizi che richiedono l'autenticazione. Per tale accesso, deve eseguire il flusso OBO , in cui scambia il token ricevuto dal client o da Fabric verso un altro servizio. Lo scambio di token potrebbe non riuscire a causa della mancanza di consenso o di alcuni criteri di accesso condizionale di Microsoft Entra configurati nella risorsa per cui il carico di lavoro sta tentando di scambiare il token.

Per risolvere questo problema, è responsabilità del carico di lavoro propagare l'errore al client quando si lavora con chiamate dirette tra il front-end e il back-end. È anche responsabilità del carico di lavoro propagare l'errore al client quando si usano chiamate da Fabric usando la propagazione degli errori descritta in Comunicazione del carico di lavoro.

Dopo che il carico di lavoro propaga l'errore, può chiamare l'API JavaScript acquireAccessToken per risolvere il problema relativo al consenso o ai criteri di accesso condizionale e ripetere l'operazione.

Per gli errori dell'API del piano dati, vedere Gestione dell'autenticazione a più fattori, dell'accesso condizionale e del consenso incrementale. Per gli errori dell'API del piano di controllo, vedere Comunicazione del carico di lavoro.

Scenari di esempio

Diamo un'occhiata a un carico di lavoro che deve accedere a tre API di Fabric.

• Elencare le aree di lavoro: GET https://api.fabric.microsoft.com/v1/workspaces

• Creare un magazzino: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Scrivere su un file di tipo lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Per poter usare queste API, il back-end del carico di lavoro deve scambiare token per gli ambiti seguenti:

• Per elencare le aree di lavoro: https://analysis.windows.net/powerbi/api/Workspace.Read.All o https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Per la creazione di un magazzino: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All o https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Per scrivere in un file lakehouse: https://storage.azure.com/user_impersonation

Gli ambiti indicati in precedenza devono essere configurati nell'applicazione sotto autorizzazioni API.

Di seguito vengono esaminati alcuni esempi di scenari che il carico di lavoro potrebbe riscontrare.

Esempio 1

Supponiamo che il backend del carico di lavoro abbia un'API del piano dati che recupera le aree di lavoro dell'utente e le restituisce al client.

1. Il front-end del carico di lavoro richiede un token usando l'API JavaScript.

2. Il front-end del carico di lavoro chiama l'API back-end del carico di lavoro per ottenere le aree di lavoro dell'utente e allega il token nella richiesta.

3. Il back-end del carico di lavoro convalida il token e tenta di scambiarlo per l'ambito richiesto ( ad esempio https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Il carico di lavoro non riesce a scambiare il token per la risorsa specificata perché l'utente non ha fornito il consenso all'applicazione per accedere a questa risorsa. Vedere i codici di errore AADSTS e.

5. Il back-end del carico di lavoro propaga l'errore al front-end del carico di lavoro specificando che è necessario il consenso per tale risorsa. Il front-end del carico di lavoro chiama l'API JavaScript acquireAccessToken e fornisce additionalScopesToConsent:

   workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

   In alternativa, il carico di lavoro può decidere di richiedere il consenso per tutte le dipendenze statiche configurate nell'applicazione, quindi chiama l'API JavaScript e fornisce promptFullConsent:

   workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Questa chiamata apre una finestra di consenso indipendentemente dal fatto che l'utente abbia acconsentito ad alcune delle dipendenze. Successivamente, l'interfaccia del carico di lavoro può riprovare l'operazione.

Esempio 2

Si supponga che il back-end del carico di lavoro debba accedere a OneLake nell'API Crea Elemento (chiamata da Fabric al back-end del carico di lavoro):

1. Il front-end del carico di lavoro chiama l'API JavaScript "Create Item".

2. Il back-end del carico di lavoro riceve una chiamata da Fabric ed estrae il token delegato e lo convalida.

3. Il carico di lavoro tenta di scambiare il token con https://storage.azure.com/user_impersonation, ma fallisce perché l'autenticazione a più fattori configurata dall'utente, necessaria per l'accesso all'Archivio di Azure, richiede l'approvazione dell'amministratore del tenant (vedere codici di errore AADSTS).

4. Il workload propaga l'errore insieme alle asserzioni restituite nell'errore da Microsoft Entra ID al client usando la propagazione degli errori descritta in Comunicazione del Workload.

5. Il front-end del carico di lavoro chiama l'API JavaScript acquireAccessToken e fornisce attestazioni come claimsForConditionalAccessPolicy, dove claims fa riferimento alle attestazioni propagate dal back-end del carico di lavoro:

   workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

Successivamente, il carico di lavoro può ritentare l'operazione.

Gestione degli errori durante la richiesta di consenso

A volte l'utente non può concedere il consenso a causa di vari errori. Dopo una richiesta di consenso, la risposta viene restituita all'URI di reindirizzamento. In questo esempio, questo codice è responsabile della gestione della risposta. È possibile trovarlo nel file index.ts.

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
} 

Il front-end del carico di lavoro può estrarre il codice di errore dall'URL e gestirlo di conseguenza.