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

Artikel
12/15/2024

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.

API:er för dataplan och kontrollplan

API:er för dataplanet är API:er som arbetsbelastningens serverdel exponerar. Frontend för arbetsbelastningen kan anropa dem direkt. För API:er för dataplanet kan arbetsbelastningsserverdelen bestämma vilka API:er som ska exponeras.
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 kontrollplans-API:er måste arbetslasten följa de avtal 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.

Omfången som läggs till för kontrollplanets API:er bör förauktorisera programmet Fabric Client för Workloads med applikations-ID d2450708-699c-41e3-8077-b0c8341509aa. Dessa omfång ingår i den token som arbetsbelastningens serverdel tar emot när Fabric anropar den.

Du måste lägga till minst ett omfång för kontrollplanets API för att flödet ska fungera.
Omfången som läggs till för dataplanens API:er bör förauktorisera Microsoft Power BI med applikations-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:et verifierar arbetsbelastningen att data.read-omfånget ingår i token innan den fortsätter med flödet. Samma sak gäller för WriteData.

Fliken API-behörigheter i arbetslastens program 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. Begäranden till Fabric kan misslyckas utan det här omfånget.

Arbeta med token och medgivanden

När du arbetar med API:er för dataplan måste arbetsbelastningsklientdelen hämta en token för anrop till arbetsbelastningens serverdel.

I följande avsnitt beskrivs hur arbetsbelastningsklientdelen ska använda JavaScript API och OBO-flöden för att hämta tokener för arbetsbelastningen och externa tjänster och för att hantera medgivanden.

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 token har arbetsbelastningens backendmålgrupp och kan användas för att direkt anropa 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 arbetsbelastningens ansvar att sprida felet till klienten när du arbetar med direktanrop mellan klientdelen och serverdelen. Det är också arbetsbördans ansvar att föra vidare felet till klienten när du arbetar med anrop från Fabric, genom att använda den felöverföring som beskrivs i arbetsbördans kommunikation.

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 fel i kontrollplanens API, 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 måste arbetsbelastningsserverdelen byta token mot följande omfång:

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

Kommentar

Du kan hitta de behörigheter som behövs för varje Fabric-API i den här referensartikeln.

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.

Frontend för arbetsbelastningen begär en token med hjälp av JavaScript-API:et.
Arbetsbelastningens klientdel anropar arbetsbelastningens serverdels-API för att hämta användarens arbetsytor och bifogar token i begäran.
Serverdelen för arbetsbelastningen validerar token och försöker byta ut den mot det nödvändiga omfånget (låt oss säga https://analysis.windows.net/powerbi/api/Workspace.Read.All).
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).
Serverdelen för arbetsbelastningen sprider felet till arbetsbelastningens klientdel genom att ange att den behöver medgivande för resursen. Arbetsbelastningsfrontend anropar JavaScript-API:n acquireAccessToken och tillhandahåller additionalScopesToConsent:

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

Arbetsbelastningen kan också välja att be om medgivande för alla sina statiska beroenden som har konfigurerats för programmet, så det anropar JavaScript-API:et och tillhandahåller 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 arbetsbelastningens frontend försöka utföra åtgärden igen.

Kommentar

Om tokenutbytet fortfarande misslyckas på ett medgivandefel innebär det att användaren inte gav sitt medgivande. Arbetsbelastningen måste hantera sådana scenarier. Meddela till exempel användaren att det här API:et kräver medgivande och inte fungerar utan det.

Exempel 2

Anta att arbetsbelastningsback-end måste komma åt OneLake via API för att skapa objekt (anrop från Fabric till arbetsbelastningen):

Klientdelen för arbetsbelastningen anropar JavaScript-API:et Skapa objekt.
Serverdelen för arbetsbelastningen tar emot ett anrop från Fabric och extraherar den delegerade token och validerar den.
Arbetsbelastningen försöker byta token mot https://storage.azure.com/user_impersonation men misslyckas eftersom klientadministratören för den användarkonfigurerade multifaktorautentisering som krävs för åtkomst till Azure Storage (se AADSTS-felkoder).
Arbetsbelastningen propagerar felet tillsammans med de påståenden som returneras i felet från Microsoft Entra ID till klienten genom att använda den felspridning som beskrivs i Workload communication.
Belastningsfrontändan anropar acquireAccessToken JavaScript-API:t och tillhandahåller krav som claimsForConditionalAccessPolicy, där claims refererar till krav som överförts från arbetsbelastningens backend.

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

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

Hantera fel vid begäran om medgivande

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.

Kommentar

I båda scenarierna (fel och framgång) måste arbetsbelastningen alltid stänga fönstret omedelbart, utan svarstid.

Dela via

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

API:er för dataplan och kontrollplan

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

Fliken API-behörigheter i arbetslastens program i Microsoft Entra ID

Arbeta med token och medgivanden

Steg 1: Hämta en token

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

Exempelscenarier

Exempel 1

Exempel 2

Hantera fel vid begäran om medgivande

Feedback

Ytterligare resurser