Condividi tramite

Linee guida per l'autenticazione per Microsoft Fabric Extensibility Toolkit

Questo articolo fornisce linee guida su come usare l'autenticazione durante la compilazione di carichi di lavoro del toolkit di estendibilità di Microsoft Fabric. Include informazioni sull'uso di token, consenso e accesso a vari servizi dall'applicazione front-end.

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

Modello di autenticazione solo front-end

Extensibility Toolkit usa un'architettura solo front-end che semplifica l'autenticazione rispetto ai carichi di lavoro tradizionali:

  • Chiamate API dirette: il front-end chiama direttamente le API fabric, i servizi di Azure e le applicazioni esterne
  • Riutilizzo dei token: un singolo token può essere usato per l'autenticazione in più servizi protetti da Entra
  • Consenso semplificato: la gestione del consenso viene gestita dalla piattaforma con richiesta automatica

Configurazione dell'applicazione Microsoft Entra

Esporre una scheda API

Configurare gli ambiti per l'applicazione del carico di lavoro:

  • Ambiti di integrazione dell'infrastruttura: preautenticare Microsoft Power BI con l'ID applicazione 871c010f-5e61-4fb1-83ac-98610a7e9110
  • Ambiti DELL'API personalizzati: aggiungere ambiti per qualsiasi API personalizzata esposta dal carico di lavoro
  • Autorizzazioni granulari: usare ambiti diversi per le operazioni di lettura e scrittura

Ad esempio, se il carico di lavoro espone le API dati:

  • Aggiungi l'ambito data.read per le operazioni di lettura
  • Aggiungi l'ambito data.write per le operazioni di scrittura
  • Convalidare gli ambiti appropriati nei gestori API

Scheda Autorizzazioni API

Configurare le autorizzazioni per i servizi esterni a cui il carico di lavoro deve accedere:

  • Obbligatorio: Fabric.Extend nel Servizio Power BI (obbligatorio per l'integrazione con Fabric)
  • Servizi di Azure: aggiungere ambiti per i servizi di Azure, ad esempio https://storage.azure.com/user_impersonation
  • Applicazioni personalizzate: aggiungere ambiti per le proprie applicazioni protette da Entra
  • Servizi di terze parti: includere tutti i servizi esterni che supportano l'autenticazione Entra

Modelli di utilizzo dei token

Uso di token per più servizi

Il token front-end acquisito tramite Extensibility Toolkit può essere usato per eseguire l'autenticazione con:

API di Fabric

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Servizi di Azure

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Applicazioni personalizzate

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Gestione dell'ambito

Il toolkit di estensibilità astrae la gestione degli ambiti per scenari comuni.

  • Librerie client di Fabric: includono automaticamente gli ambiti di Fabric necessari
  • Librerie client di Azure: gestire gli ambiti del servizio di Azure in modo trasparente
  • Ambiti personalizzati: specificare ambiti aggiuntivi quando necessario

Gestione dei consensi

Acquisizione iniziale del token

Per iniziare, acquisire un token per stabilire il contesto di autenticazione:

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

Questa chiamata può comportare:

  • Richiesta di consenso: se l'utente non ha acconsentito all'applicazione
  • Acquisizione invisibile all'utente: se il consenso è stato precedentemente concesso

Gestione dell'accesso al servizio aggiuntivo

Quando il carico di lavoro deve accedere a servizi aggiuntivi, specificare gli ambiti necessari:

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

Scenari di esempio

Scenario 1: Accesso ai servizi Fabric e Azure

Il carico di lavoro deve:

  • Elencare le aree di lavoro di Fabric
  • Leggere da Azure Storage
  • Scrivere in Azure Key Vault

Implementazione:

  1. Configurare le autorizzazioni API per i servizi necessari
  2. Acquisire il token iniziale
  3. Usare il token per tutte le chiamate al servizio
  4. Gestire le richieste di consenso in base alle esigenze

Scenario 2: Integrazione di applicazioni personalizzate

Il carico di lavoro si integra con il proprio servizio back-end:

  1. Configurare il back-end: assicurarsi che accetti i token Entra
  2. Aggiungere autorizzazioni API: includere gli ambiti del back-end nell'applicazione del carico di lavoro
  3. Usare l'autenticazione standard: lo stesso modello di token funziona per i servizi personalizzati

Scenario 3: Integrazione di servizi di terze parti

Integrazione con i servizi abilitati per Entra esterni:

  1. Registrazione del servizio: registrare il carico di lavoro con il servizio di terze parti
  2. Configurazione dell'ambito: aggiungere gli ambiti del servizio alle autorizzazioni API
  3. Utilizzo dei token: usare lo stesso modello di autenticazione per i servizi esterni

Gestione degli errori e risoluzione dei problemi

Errori di autenticazione comuni

  • Consenso richiesto: l'utente non ha concesso l'autorizzazione per un ambito specifico
  • Accesso condizionale: requisiti di autenticazione aggiuntivi (ad esempio, MFA)
  • Scadenza del token: il token è scaduto e richiede l'aggiornamento
  • Ambito non valido: l'ambito richiesto non è configurato o disponibile

Modelli di gestione degli errori

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

Gestione dell'URI di reindirizzamento

Il toolkit di estensibilità include la gestione predefinita degli URI di reindirizzamento per i popup di consenso dell'autenticazione. Questa operazione viene implementata nel file principale index.ts e gestisce automaticamente i reindirizzamenti del consenso.

Il toolkit gestisce:

  • Chiusura automatica della finestra: i popup di consenso si chiudono automaticamente dopo l'interazione dell'utente
  • Gestione degli errori: vengono rilevati codici di errore specifici e gestiti in modo appropriato
  • Visualizzazione degli errori: i tentativi di consenso non riusciti mostrano messaggi di errore descrittivi

Implementazione corrente nel toolkit:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

Annotazioni

La gestione dell'URI di reindirizzamento viene inclusa automaticamente nel modello del toolkit di estendibilità. Non è necessario implementare questa operazione manualmente, a meno che non si voglia personalizzare il comportamento di gestione degli errori.

Procedure consigliate

Gestione di token

  • Token della cache: riutilizzare i token fino alla scadenza
  • Gestire l'aggiornamento: implementare la logica di aggiornamento automatico dei token
  • Archiviazione sicura: archiviare i token in modo sicuro nella memoria del browser
  • Autorizzazioni minime: richiedere solo gli ambiti effettivamente necessari
  • Consenso progressivo: richiedere autorizzazioni aggiuntive come funzionalità usate
  • Cancellare la messaggistica: spiegare agli utenti perché sono necessarie le autorizzazioni

Gestione degli errori

  • Degradazione graduale: fornire funzionalità di fallback quando possibile
  • Feedback degli utenti: comunicare chiaramente i requisiti di autenticazione
  • Logica dei ritenti: Implementare meccanismi di ritentazione appropriati per i fallimenti transitori.

Contenuti correlati

  • Last updated on