Riktlinjer för autentisering för Microsoft Fabric Extensibility Toolkit

Den här artikeln innehåller riktlinjer för hur du arbetar med autentisering när du skapar arbetsbelastningar med Microsoft Fabric Extensibility Toolkit. Den innehåller information om hur du arbetar med tokens, medgivanden och åtkomst till olika tjänster från din frontend-applikation.

Kontrollera att du är bekant med begreppen i översikten över autentisering innan du börjar.

Endast klientdelsautentiseringsmodell

Utökningsverktyget använder en klientdelsarkitektur som förenklar autentiseringen jämfört med traditionella arbetsbelastningar:

Direkt-API-anrop: Klientdelen anropar direkt Infrastruktur-API:er, Azure-tjänster och externa program
Återanvändning av token: En enskild token kan användas för att autentisera mot flera Entra-skyddade tjänster
Förenklat medgivande: Medgivandehantering hanteras av plattformen med automatisk uppmaning

Microsoft Entra-programkonfiguration

Gör en API-flik synlig

Konfigurera räckvidd för din arbetsbelastningsapplikation:

Infrastrukturintegreringsomfång: Förauktorisera Microsoft Power BI med program-ID 871c010f-5e61-4fb1-83ac-98610a7e9110
Anpassade API-omfång: Lägg till omfång för alla anpassade API:er som din arbetsbelastning exponerar
Detaljerade behörigheter: Använd olika omfång för läs- och skrivåtgärder

Om din arbetsbelastning till exempel exponerar data-API:er:

Lägg till data.read omfång för läsåtgärder
Lägg till data.write omfång för skrivåtgärder
Verifiera lämpliga omfång i DINA API-hanterare

Fliken API-behörigheter

Konfigurera behörigheter för externa tjänster som din arbetsbelastning behöver åtkomst till:

Krävs: Fabric.Extend under Power BI-tjänsten (obligatorisk för Fabric-integrering)
Azure-tjänster: Lägga till omfång för Azure-tjänster som https://storage.azure.com/user_impersonation
Anpassade program: Lägga till omfång för dina egna Entra-skyddade program
Tjänster från tredje part: Inkludera externa tjänster som stöder Entra-autentisering

Användningsmönster för token

Använda token för flera tjänster

Klientdelstoken som hämtas via Utökningsverktyget kan användas för att autentisera mot:

Infrastruktur-API:er

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

Azure-tjänster

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

Anpassade applikationer

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

Omfångshantering

Utökningsverktyget abstraherar omfångshantering för vanliga scenarier:

Fabric-klientbibliotek: Inkludera automatiskt nödvändiga Fabric-åtkomstområden
Azure-klientbibliotek: Hantera Azure-tjänstsyften transparent
Anpassade omfång: Ange ytterligare omfång när det behövs

Arbeta med medgivanden

Första tokenförvärvet

Börja med att hämta en token för att upprätta autentiseringskontexten:

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

Det här anropet kan resultera i:

Fråga om medgivande: Om användaren inte har samtyckt till ditt program
Tyst förvärv: Om medgivande tidigare har beviljats

Hantera ytterligare tjänståtkomst

När din arbetsbelastning behöver komma åt ytterligare tjänster anger du de nödvändiga omfången:

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

Exempelscenarier

Scenario 1: Åtkomst till Fabric och Azure-tjänster

Din arbetsbelastning måste:

Listar Fabric-arbetsytor
Läs från Azure Storage
Skriva till Azure Key Vault

Implementering:

Konfigurera API-behörigheter för nödvändiga tjänster
Hämta första tokenn
Använda token för alla tjänstanrop
Hantera medgivandeprompter efter behov

Scenario 2: Anpassad programintegrering

Din arbetsbelastning integreras med din egen backend-tjänst.

Konfigurera serverdelen: Se till att den accepterar Entra-token
Lägg till API-behörigheter: Inkludera backendens omfång i arbetsbelastningsapplikationen
Använd standardautentisering: Samma tokenmönster fungerar för dina anpassade tjänster

Scenario 3: Tjänstintegrering från tredje part

Integrera med externa Entra-aktiverade tjänster:

Tjänstregistrering: Registrera din arbetsbelastning med tredjepartstjänsten
Omfångskonfiguration: Lägg till tjänstens omfång i dina API-behörigheter
Tokenanvändning: Använd samma autentiseringsmönster för externa tjänster

Felhantering och felsökning

Vanliga autentiseringsfel

Medgivande krävs: Användaren har inte beviljat behörighet för ett specifikt omfång
Villkorsstyrd åtkomst: Ytterligare autentiseringskrav (t.ex. MFA)
Förfallodatum för token: Token har upphört att gälla och behöver uppdateras
Ogiltigt omfång: Det begärda omfånget är inte konfigurerat eller tillgängligt

Felhanteringsmönster

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

Omdirigerings-URI-hantering

Utökningsverktyget innehåller inbyggd omdirigerings-URI-hantering för popup-fönster för autentiseringsmedgivande. Detta implementeras i huvudfilen index.ts och hanterar medgivandeomdirigeringar automatiskt.

Verktygslådan hanterar:

Automatisk stängning av fönster: Popup-fönster för medgivande stängs automatiskt efter användarinteraktion
Felhantering: Specifika felkoder identifieras och hanteras på rätt sätt
Felvisning: Misslyckade medgivandeförsök visar användarvänliga felmeddelanden

Aktuell implementering i verktygslådan:

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

Anmärkning

Omdirigerings-URI-hanteringen ingår automatiskt i mallen för utökningsverktyget. Du behöver inte implementera detta själv om du inte vill anpassa beteendet för felhantering.

Metodtips

Tokenhantering

Cachetoken: Återanvänd token tills de upphör att gälla
Hantera uppdatering: Implementera automatisk tokenuppdateringslogik
Säker lagring: Lagra token på ett säkert sätt i webbläsarens minne

Minimal behörighet: Begär endast de omfång som du faktiskt behöver
Progressivt medgivande: Begär ytterligare behörigheter eftersom funktioner används
Tydliga meddelanden: Förklara för användarna varför behörigheter behövs

Felhantering

Graciös försämring: Ge återställningsfunktioner när det är möjligt
Användarfeedback: Tydligt kommunicera autentiseringskrav
Omprövarlogik: Implementera lämpliga återförsöksmekanismer för tillfälliga fel

Feedback

Var den här sidan till hjälp?

Last updated on 2025-12-15