Dela via

Ö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.

Data plane and control plane APIs

  • Data plane APIs are APIs that the workload backend exposes. The workload frontend can call them directly. For data plane APIs, the workload backend can decide on what APIs to expose.

  • 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.

    For control plane APIs, the workload must follow the contracts defined in the workload backend and implement those APIs.

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.

  • The scopes added for control plane APIs should preauthorize the Fabric Client for Workloads application with application ID d2450708-699c-41e3-8077-b0c8341509aa. Those scopes are included in the token that the workload backend receives when Fabric calls it.

    You need to add at least one scope for the control plane API for the flow to work.

  • The scopes added for data plane APIs should preauthorize Microsoft Power BI with application 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.
    • The workload exposes two data plane scopes, data.read and data.write.
    • In the ReadData API, the workload validates that the data.read scope is included in the token before it continues with the flow. Samma sak gäller för WriteData.

API permissions tab on the workload's application in 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. Requests to Fabric might fail without this scope.

Working with tokens and consents

When you're working with data plane APIs, the workload frontend needs to acquire a token for calls to the workload backend.

The following sections describe how the workload frontend should use the JavaScript API and on-behalf-of (OBO) flows to acquire tokens for the workload and external services, and to work with consents.

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). The received token has the workload backend audience and can be used to directly call the workload backend from the workload 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.

To solve this problem, it's the workload's responsibility to propagate the error to the client when working with direct calls between the frontend and the backend. It's also the workload's responsibility to propagate the error to the client when working with calls from Fabric by using the error propagation described in 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. For control plane API failures, see Workload communication.

Exempelscenarier

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

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

  • Create a warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

  • Write to a lakehouse file: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

To be able to work with those APIs, the workload backend needs to exchange tokens for the following 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
  • For writing to a lakehouse file: https://storage.azure.com/user_impersonation

Note

You can find scopes needed for each Fabric API in this reference article.

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å.

Example 1

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

  1. The workload frontend asks for a token by using the JavaScript API.

  2. The workload frontend calls the workload backend API to get the workspaces of the user and attaches the token in the request.

  3. The workload backend validates the token and tries to exchange it for the required scope (let's say 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. The workload backend propagates the error to the workload frontend by specifying that it needs consent for that resource. The workload frontend calls the acquireAccessToken JavaScript API and provides additionalScopesToConsent:

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

    Alternatively, the workload can decide to ask for consent for all of its static dependencies that are configured on its application, so it calls the JavaScript API and provides 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. After that, the workload frontend can retry the operation.

Note

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.

Example 2

Let's assume that the workload backend needs to access OneLake on the Create Item API (call from Fabric to the workload):

  1. The workload frontend calls the Create Item JavaScript API.

  2. The workload backend receives a call from Fabric and extracts the delegated token and validates it.

  3. The workload tries to exchange the token for https://storage.azure.com/user_impersonation but fails because the tenant administrator of the user-configured multifactor authentication needed to access Azure Storage (see AADSTS error codes).

  4. The workload propagates the error alongside the claims returned in the error from Microsoft Entra ID to the client by using the error propagation described in Workload communication.

  5. The workload frontend calls the acquireAccessToken JavaScript API and provides claims as claimsForConditionalAccessPolicy, where claims refers to the claims propagated from the workload backend:

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

After that, the workload can retry the operation.

Handling errors when requesting consents

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.

Note

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

  • Last updated on