Verificatierichtlijnen voor Microsoft Fabric Extensibility Toolkit

Dit artikel bevat richtlijnen voor het werken met verificatie bij het bouwen van uitbreidbaarheidstaken van het Microsoft Fabric-extensibilitytoolkit. Het bevat informatie over het werken met tokens, toestemmingen en het openen van verschillende services vanuit uw front-endtoepassing.

Voordat u begint, moet u ervoor zorgen dat u bekend bent met de concepten in het verificatieoverzicht.

Authenticatiemodel uitsluitend voor de frontend

De Extensibility Toolkit maakt gebruik van een alleen frontend architectuur die authenticatie vereenvoudigt in vergelijking met traditionele workloads.

Directe API-aanroepen: uw front-end roept fabric-API's, Azure-services en externe toepassingen rechtstreeks aan
Token hergebruik: één token kan worden gebruikt om te verifiëren bij meerdere entra-beveiligde services
Vereenvoudigde toestemming: Toestemmingsbeheer wordt verwerkt door het platform met automatische prompts

Microsoft Entra-toepassingsconfiguratie

Een API-tabblad beschikbaar maken

Configureer scopes voor uw workload applicatie:

Fabric-integratiebereiken: Microsoft Power BI vooraf autoriseren met toepassings-id 871c010f-5e61-4fb1-83ac-98610a7e9110
Aangepaste API-bereiken: Bereiken toevoegen voor aangepaste API's die uw workload beschikbaar maakt
Gedetailleerde machtigingen: de verschillende toepassingsgebieden gebruiken voor lees- versus schrijfbewerkingen

Als uw workload bijvoorbeeld gegevens-API's beschikbaar maakt:

Bereik voor leesbewerkingen toevoegen data.read
Voeg data.write bereik toe voor schrijfbewerkingen
Valideer de juiste scopes in uw API-handlers

Tabblad API-machtigingen

Configureer machtigingen voor externe services die uw workload nodig heeft voor toegang tot:

Vereist: Fabric.Extend onder Power BI-service (verplicht voor Fabric-integratie)
Azure-services: Scopes voor Azure-services toevoegen, zoals https://storage.azure.com/user_impersonation
Aangepaste toepassingen: Scopes toevoegen voor uw eigen toepassingen die beveiligd zijn met Entra
Services van derden: neem eventuele externe services op die ondersteuning bieden voor Entra-verificatie

Gebruikspatronen voor tokens

Tokens gebruiken voor meerdere services

Het front-endtoken dat is verkregen via de Extensibility Toolkit kan worden gebruikt om te verifiëren bij:

Fabric API's

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

Azure-diensten

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

Aangepaste toepassingen

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

Bereikbeheer

De Extensibility Toolkit abstracteert bereikbeheer voor veelvoorkomende scenario's:

Fabric-clientbibliotheken: automatisch vereiste Fabric-bereiken opnemen
Azure-clientbibliotheken: Azure-servicebereiken transparant verwerken
Aangepaste scopes: specificeer indien nodig extra scopes

Werken met toestemmingen

Initiële tokenverwerving

Begin met het verkrijgen van een token om de verificatiecontext tot stand te brengen:

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

Deze aanroep kan leiden tot:

Toestemmingsprompt: Als de gebruiker geen toestemming heeft gegeven voor uw toepassing
Stille verwerving: Indien eerder toestemming is verleend

Aanvullende servicetoegang verwerken

Wanneer uw workload toegang nodig heeft tot aanvullende services, geeft u de vereiste scopes op:

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);
}

Voorbeeldscenario's

Scenario 1: Toegang tot fabric- en Azure-services

Uw workload moet het volgende doen:

Fabric-werkruimten vermelden
Lezen uit Azure Storage
Schrijven naar Azure Key Vault

Implementatie:

API-machtigingen configureren voor vereiste services
Eerste token verkrijgen
Token gebruiken voor alle serviceoproepen
Toestemmingsprompts verwerken indien nodig

Scenario 2: Integratie van aangepaste toepassingen

Uw workload kan worden geïntegreerd met uw eigen back-endservice:

Uw back-end configureren: zorg ervoor dat deze Entra-tokens accepteert
API-machtigingen toevoegen: Neem de scopes van uw back-end op in de workload-applicatie
Standaardverificatie gebruiken: hetzelfde tokenpatroon werkt voor uw aangepaste services

Scenario 3: Integratie van services van derden

Integreren met externe Entra-geactiveerde services:

Serviceregistratie: Uw workload registreren bij de service van derden
Scopeconfiguratie: Voeg de scopes van de service toe aan de API-machtigingen.
Tokengebruik: hetzelfde verificatiepatroon gebruiken voor externe services

Foutverwerking en het oplossen van problemen

Veelvoorkomende verificatiefouten

Toestemming vereist: de gebruiker heeft geen machtiging verleend voor een specifiek bereik
Voorwaardelijke toegang: Aanvullende verificatievereisten (bijvoorbeeld MFA)
Verloop van token: token is verlopen en moet worden vernieuwd
Ongeldig bereik: aangevraagd bereik is niet geconfigureerd of beschikbaar

Foutafhandelingspatronen

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;
  }
}

Verwerking van omleidings-URI's

De uitbreidbaarheidstoolkit bevat ingebouwde omleidings-URI-verwerking voor pop-ups voor verificatietoestemming. Dit wordt geïmplementeerd in het hoofdbestand index.ts en verwerkt toestemmingsomleidingen automatisch.

De toolkit beheert:

Automatische venstersluiting: pop-ups van toestemming worden automatisch gesloten na interactie van de gebruiker
Foutafhandeling: specifieke foutcodes worden gedetecteerd en op de juiste wijze afgehandeld
Foutweergave: Mislukte toestemmingspogingen geven gebruiksvriendelijke foutberichten weer

Huidige implementatie in de 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();
  }
}

Opmerking

De verwerking van omleidings-URI's wordt automatisch opgenomen in de sjabloon voor de uitbreidbaarheidstoolkit. U hoeft dit niet zelf te implementeren, tenzij u het gedrag voor foutafhandeling wilt aanpassen.

Beste praktijken

Tokenbeheer

Cachetokens: tokens opnieuw gebruiken totdat ze verlopen
Vernieuwen afhandelen: logica voor automatisch vernieuwen van tokens implementeren
Beveiligde opslag: tokens veilig opslaan in browsergeheugen

Minimale machtigingen: vraag alleen de machtigingen aan die u daadwerkelijk nodig hebt
Progressieve toestemming: aanvullende machtigingen aanvragen als functies worden gebruikt
Duidelijke berichten: gebruikers uitleggen waarom machtigingen nodig zijn

Foutafhandeling

Gracieuze degradatie: waar mogelijk terugvalfunctionaliteit bieden
Gebruikersfeedback: Verificatievereisten duidelijk communiceren
Herkansingslogica: Implementeer geschikte herkansingsmechanismen voor tijdelijke mislukkingen

Feedback

Is deze pagina nuttig?

Last updated on 2025-12-15