Översikt över riktlinjer för arbetsbelastningsautentisering i Microsoft Fabric

Den här artikeln innehåller riktlinjer för hur du arbetar med autentisering när du skapar Microsoft Fabric-arbetsbelastningar. Den innehåller information om hur du arbetar med token och medgivanden.

Innan du börjar, kontrollera att du är bekant med begreppen i autentiseringsöversikt och autentiseringsinställningar.

Dataplans- och styrplans-API:er

• Data plane API:er är API:er som arbetsbelastningens backend exponerar. Arbetsbelastningsfrontend kan kalla dem direkt. För dataplans-API:er kan arbetslastens backend avgöra vilka API:er som ska göras tillgängliga.

• Kontrollplans-API är API:er som går igenom Fabric. Processen börjar med att arbetsbelastningsklientdelen anropar ett JavaScript-API och slutar med att Fabric anropar arbetsbelastningens serverdel. Ett exempel på ett sådant API är Skapa objekt.

  För API:er för kontrollplanet måste arbetslasten följa de kontrakt som definieras i arbetslastens backend och implementera dessa API:er.

Visa en API-flik på applikationen för arbetslasten i Microsoft Entra ID

På fliken Exponera ett API måste du lägga till omfång för API:er för kontrollplanet och omfång för API:er för dataplanet.

• De scopes som lagts till för kontrollplans-API:er bör förauktorisera applikationen Fabric Client for Workloads med applikations-IDd2450708-699c-41e3-8077-b0c8341509aa. Dessa scopes ingår i tokenen som arbetsbelastningsbackend får när Fabric anropar den.

  Du behöver lägga till minst ett behörighetsomfång för API:t för kontrollplanet för att flödet ska fungera.

• De omfång som lagts till för API:er för dataplanet bör i förväg auktorisera Microsoft Power BI med program-ID 871c010f-5e61-4fb1-83ac-98610a7e9110. De ingår i token som acquireAccessToken JavaScript-API:et returnerar.

  För API:er för dataplan kan du använda den här fliken för att hantera detaljerade behörigheter för varje API som din arbetsbelastning exponerar. Helst bör du lägga till en uppsättning omfång för varje API som arbetsbelastningens serverdel exponerar och verifiera att den mottagna token innehåller dessa omfång när dessa API:er anropas från klienten. Till exempel:

  • Arbetsbelastningen exponerar två API:er för klienten, ReadData och WriteData.
  • Arbetsbelastningen exponerar två dataplansomfång, data.read och data.write.
  • I ReadData API kontrollerar arbetsbelastningen att scopet data.read finns i tokenen innan den fortsätter flödet. Samma sak gäller för WriteData.

API-behörighetsfliken på arbetsbelastningens applikation i Microsoft Entra ID

På fliken API-behörigheter måste du lägga till alla omfång som din applikation behöver för att utbyta en token. Ett obligatoriskt omfång att lägga till är Fabric.Extend under Power BI-tjänsten. Förfrågningar till Fabric kan misslyckas utan den här behörigheten.

Att arbeta med tokens och samtycken

När du arbetar med dataplan-API:er behöver arbetsbelastningsfrontend hämta en token för anrop till arbetsbelastningsbackend.

Följande avsnitt beskriver hur frontend för arbetsbelastningen ska använda JavaScript API och on-behalf-of (OBO)-flöden för att hämta token för arbetsbelastningen och externa tjänster samt hantera samtycken.

Steg 1: Hämta en token

Arbetsbelastningen börjar med att fråga efter en token med hjälp av JavaScript-API:et utan att ange några parametrar. Det här anropet kan resultera i två scenarier:

• Användaren ser ett medgivandefönster för alla statiska beroenden (vad som har konfigurerats på fliken API-behörigheter) som arbetsbelastningen har konfigurerat. Det här scenariot inträffar om användaren inte är en del av programmets hemklientorganisation och användaren inte gav medgivande till Microsoft Graph för det här programmet tidigare.

• Användaren ser inget medgivandefönster. Det här scenariot inträffar om användaren redan har samtyckt minst en gång till Microsoft Graph för det här programmet, eller om användaren är en del av programmets hemklientorganisation.

I båda scenarierna bör arbetsbelastningen inte bry sig om huruvida användaren gav fullständigt medgivande för alla beroenden (och inte kan veta i det här läget). Den mottagna tokenen har målgruppen för arbetsbelastningens backend och kan användas för att direkt anropa arbetsbelastningens backend från arbetsbelastningens frontend.

Steg 2: Försök att komma åt externa tjänster

Den aktuella arbetsuppgiften kan behöva komma åt tjänster som kräver autentisering. För att få åtkomst måste den utföra OBO-flödet , där den byter ut den token som den tog emot från sin klient eller från Fabric till en annan tjänst. Tokenutbytet kan misslyckas på grund av bristande medgivande eller någon princip för villkorsstyrd åtkomst i Microsoft Entra som har konfigurerats för den resurs som arbetsbelastningen försöker byta token mot.

För att lösa det här problemet är det arbetslastens ansvar att vidarebefordra felet till klienten vid direkta anrop mellan frontend och backend. Det är också arbetslastens ansvar att vidarebefordra felet till klienten vid arbete med anrop från Fabric genom att använda den felvidarebefordran som beskrivs i Workload communication.

När arbetsbelastningen har spridit felet kan den anropa acquireAccessToken JavaScript-API:et för att lösa problemet med medgivandet eller principen för villkorsstyrd åtkomst och försöka utföra åtgärden igen.

Information om API-fel (dataplan) finns i Hantera multifaktorautentisering, villkorsstyrd åtkomst och inkrementellt medgivande. För misslyckanden med kontrollplans-API:er, se Arbetsbelastningskommunikation.

Exempelscenarier

Nu ska vi ta en titt på en arbetsbelastning som behöver åtkomst till tre Infrastruktur-API:er:

• Lista arbetsytor: GET https://api.fabric.microsoft.com/v1/workspaces

• Skapa ett lager: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Skriv till en lakehouse-fil: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

För att kunna arbeta med dessa API:er behöver arbetsbelastningsbackend byta tokens mot följande scopes:

• För att visa arbetsytor: https://analysis.windows.net/powerbi/api/Workspace.Read.All eller https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• För att skapa ett lager: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All eller https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• För att skriva till en lakehouse-fil: https://storage.azure.com/user_impersonation

De tidigare nämnda omfången måste konfigureras i arbetsbelastningsapplikationen under API-behörigheter.

Låt oss ta en titt på exempel på scenarier som arbetsbelastningen kan stöta på.

Exempel 1

Anta att arbetsbelastningens backend har ett dataplane-API som hämtar användarens arbetsytor och returnerar dem till klienten.

1. Frontenden för arbetsbelastningen begär en token med hjälp av JavaScript-API:t.

2. Frontendkomponenten för arbetsbelastningen anropar backend-API:et för arbetsbelastningen för att hämta användarens arbetsytor och bifogar tokenen i begäran.

3. Backenden för arbetsbelastningen validerar tokenen och försöker byta ut den mot det begärda behörighetsomfånget (säg https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Arbetsbelastningen kan inte byta ut token mot den angivna resursen eftersom användaren inte har samtyckt till att programmet får åtkomst till den här resursen (se AADSTS-felkoder).

5. Arbetsbelastningens serverdel vidarebefordrar felet till den arbetsbelastningens klientdel genom att ange att den behöver medgivande för den resursen. Arbetsbelastningens frontend anropar acquireAccessToken JavaScript-API:et och tillhandahåller additionalScopesToConsent:

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

   Alternativt kan arbetslasten välja att begära samtycke för alla sina statiska beroenden som är konfigurerade i programmet, genom att anropa JavaScript-API:t och ange promptFullConsent:

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

Det här samtalet uppmanar till ett medgivandefönster oavsett om användaren har samtyckt till några av beroendena eller inte. Därefter kan frontend för arbetsbelastningen försöka utföra åtgärden igen.

Exempel 2

Låt oss anta att arbetsbelastningsbackend behöver åtkomst till OneLake i Create Item API (anrop från Fabric till arbetsbelastningen):

1. Gränssnittet för arbetsbelastningen anropar JavaScript-API:et Create Item.

2. En arbetslastsbackend tar emot ett anrop från Fabric, extraherar den delegerade tokenen och validerar den.

3. Arbetsbelastningen försöker byta token mot https://storage.azure.com/user_impersonation men misslyckas eftersom hyresgästadministratören av den användarkonfigurerade multifaktorautentiseringen behövde åtkomst till Azure Storage (se AADSTS-felkoder).

4. Arbetsbelastningen sprider felet tillsammans med de krav som returneras i felet från Microsoft Entra ID till klienten genom att använda felpropagationen som beskrivs i Workload communication.

5. Arbetsbelastningens frontend anropar acquireAccessToken JavaScript-API:t och tillhandahåller anspråk som claimsForConditionalAccessPolicy, där claims avser de anspråk som vidarebefordras från arbetsbelastningens backend:

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

Därefter kan arbetsbelastningen försöka utföra åtgärden igen.

Hanteringsfel vid begäran om samtycke

Ibland kan användaren inte bevilja medgivande på grund av olika fel. Efter en begäran om medgivande returneras svaret till omdirigerings-URI:n. I vårt exempel ansvarar den här koden för att hantera svaret. (Du hittar den i filen 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(); 
} 

Gränssnittet för arbetsbelastningen kan extrahera felkoden från URL:en och hantera den därefter.