Overzicht van richtlijnen voor workloadverificatie in Microsoft Fabric

Dit artikel bevat richtlijnen voor het werken met verificatie bij het bouwen van Microsoft Fabric-workloads. Het bevat informatie over het werken met tokens en toestemmingen.

Voordat je begint, zorg ervoor dat je bekend bent met de concepten in het overzicht van authenticatie en authenticatie-instellingen.

Datavlak- en besturingsvlak-API's

• Data plane-API’s zijn API’s die de workload-backend aanbiedt. De front-end van de workload kan deze rechtstreeks aanroepen. Voor dataplane-API's kan de workload-backend beslissen welke API's worden blootgesteld.

• Besturingsvlak-API's zijn API's die via Fabric gaan. Het proces begint met de front-end van de workload die een JavaScript-API aanroept en eindigt met Fabric die de back-end van de workload aanroept. Een voorbeeld van een dergelijke API is Item maken.

  Voor API's van het besturingsvlak moet de workload de contracten volgen die zijn gedefinieerd in de back-end van de workload en deze API's implementeren.

Een API-tabblad weergeven op de toepassing van de workload in Microsoft Entra ID

Op de tab Een API beschikbaar maken moet u scopes toevoegen voor control plane-API's en scopes voor data plane-API's:

• De scopes die zijn toegevoegd voor control plane API's moeten de Fabric Client for Workloads-applicatie vooraf autoriseren met applicatie-IDd2450708-699c-41e3-8077-b0c8341509aa. Die scopes zijn opgenomen in het token dat de workload-backend ontvangt wanneer Fabric het aanroept.

  U moet ten minste één bereik toevoegen voor de besturingsvlak-API om de workflow te laten functioneren.

• De scopes die zijn toegevoegd voor gegevensvlak-API's, moeten Microsoft Power BI vooraf autoriseren met de applicatie-id 871c010f-5e61-4fb1-83ac-98610a7e9110. Ze worden opgenomen in het token dat de acquireAccessToken JavaScript-API retourneert.

  Voor API's van het gegevensvlak kunt u dit tabblad gebruiken om gedetailleerde machtigingen te beheren voor elke API die uw workload beschikbaar maakt. In het ideale geval zou u een reeks scopes moeten toevoegen voor elke API die de back-end van de workload beschikbaar maakt en controleren of het ontvangen token deze scopes bevat wanneer deze API's vanaf de client worden aangeroepen. Bijvoorbeeld:

  • De workload maakt twee API's beschikbaar voor de client, ReadData en WriteData.
  • De workload bevat twee gegevensvlakbereiken, data.read en data.write.
  • In de ReadData-API controleert de workload of het bereik data.read in het token is opgenomen voordat het proces wordt voortgezet. Hetzelfde geldt voor WriteData.

tabblad API-machtigingen op de workload-applicatie in Microsoft Entra ID

Op het tabblad API-permissies moet je alle scopes toevoegen waarvoor je workload een token moet uitwisselen. Een verplichte scope die moet worden toegevoegd, is Fabric.Extend in de Power BI-service. Aanvragen naar Fabric kunnen mislukken zonder dit bereik.

Werken met tokens en toestemmingen

Wanneer u met API's voor het gegevensvlak werkt, moet de front-end van de workload een token verkrijgen voor aanroepen naar de back-end van de workload.

De volgende secties beschrijven hoe de workload-frontend de JavaScript-API en on-behalf-of (OBO) flows moet gebruiken om tokens voor de workload en externe diensten te verkrijgen, en om met toestemmingen te werken.

Stap 1: Een token verkrijgen

De workload begint met het vragen om een token met behulp van de JavaScript-API zonder parameters op te geven. Deze aanroep kan leiden tot twee scenario's:

• De gebruiker ziet een toestemmingsvenster met alle statische afhankelijkheden (die zijn geconfigureerd op het tabblad API permissions) die voor de workload zijn geconfigureerd. Dit scenario treedt op als de gebruiker geen deel uitmaakt van de basistenant van de toepassing en de gebruiker geen toestemming heeft verleend aan Microsoft Graph voor deze toepassing.

• De gebruiker ziet geen toestemmingsvenster. Dit scenario treedt op als de gebruiker al ten minste één keer toestemming heeft gegeven voor Microsoft Graph voor deze toepassing of als de gebruiker deel uitmaakt van de basistenant van de toepassing.

In beide scenario's hoeft de workload zich niet bezig te houden met de vraag of de gebruiker al dan niet volledige toestemming heeft gegeven voor alle afhankelijkheden (en kan dit op dit moment niet controleren). Het ontvangen token heeft de doelgroep van de workload-backend en kan rechtstreeks worden gebruikt om de workload-backend vanuit de workload-frontend aan te roepen.

Stap 2: Toegang proberen te krijgen tot externe services

De workload moet mogelijk toegang hebben tot services waarvoor verificatie is vereist. Voor die toegang moet het de OBO-flow uitvoeren, waarbij het het token dat het van zijn client of van Fabric heeft ontvangen uitwisselt naar een andere service. De token-uitwisseling kan falen door het ontbreken van toestemming of een Microsoft Entra Voorwaardelijke toegang-beleid dat is geconfigureerd op de resource waarvoor de werklast de token probeert uit te wisselen.

Om dit probleem op te lossen, is het de verantwoordelijkheid van de applicatie om de fout aan de client door te geven wanneer er directe aanroepen zijn tussen de frontend en de backend. Het is ook de verantwoordelijkheid van de workload om de fout door te geven aan de clienttoepassing bij het werken met oproepen vanuit Fabric, door gebruik te maken van de foutdoorgifte zoals beschreven in Workload communication.

Nadat de workload de fout heeft doorgegeven, kan deze de acquireAccessToken JavaScript-API aanroepen om het probleem met het toestemmings- of beleid voor voorwaardelijke toegang op te lossen en de bewerking opnieuw uit te voeren.

Zie Afhandeling van meervoudige verificatie, voorwaardelijke toegang en incrementele toestemmingvoor api-fouten in het gegevensvlak. Voor storingen in de control plane API, zie Workload communication.

Voorbeeldscenario's

Laten we eens kijken naar een workload die toegang nodig heeft tot drie Fabric-API's:

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

• Maak een magazijn: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Schrijf naar een bestand in een lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Om met die API's te kunnen werken, moet de workload-backend tokens uitwisselen voor de volgende scopes:

• Voor het vermelden van werkruimtes: https://analysis.windows.net/powerbi/api/Workspace.Read.All of https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Voor het maken van een magazijn: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All of https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Voor het schrijven naar een lakehouse-bestand: https://storage.azure.com/user_impersonation

Opmerking

In dit naslagartikel vindt u de toepassingsgebieden die nodig zijn voor elke Fabric API.

De eerder genoemde scopes moeten worden geconfigureerd in de workloadapplicatie onder API-permissies.

Laten we eens kijken naar voorbeelden van scenario's die de workload kan tegenkomen.

Voorbeeld 1

Stel dat de back-end van de workload een datavlak-API heeft waarmee de werkruimten van de gebruiker worden opgehaald en naar de cliënt worden geretourneerd.

1. De front-end van de workload vraagt om een token met behulp van de JavaScript-API.

2. De workload-frontend roept de workload-backend-API aan om de werkruimtes van de gebruiker te verkrijgen en voegt het token toe aan het verzoek.

3. De workload-backend valideert de token en probeert deze te ruilen voor de vereiste scope (laten we zeggen https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. De werklast slaagt er niet in het token uit te wisselen voor de opgegeven resource omdat de gebruiker geen toestemming gaf voor de applicatie om deze resource te gebruiken (zie AADSTS-foutcodes).

5. De back-end van de workload geeft de fout door aan de front-end van de workload door aan te geven dat deze goedkeuring nodig heeft voor die resource. De front-end van de workload roept de acquireAccessToken JavaScript-API aan en biedt additionalScopesToConsent:

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

   Als alternatief kan de workload besluiten toestemming te vragen voor alle statische afhankelijkheden die voor de toepassing zijn geconfigureerd, waarbij deze de JavaScript-API aanroept en promptFullConsent opgeeft:

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

Deze oproep opent een toestemmingsvenster, ongeacht of de gebruiker toestemming heeft gegeven voor sommige afhankelijkheden. Daarna kan de front-end van de workload de bewerking opnieuw proberen.

Opmerking

Als de tokenuitwisseling nog steeds mislukt op een toestemmingsfout, betekent dit dat de gebruiker geen toestemming heeft verleend. De workload moet dergelijke scenario's verwerken; Stel de gebruiker op de hoogte dat deze API toestemming vereist en werkt niet zonder deze API.

Voorbeeld 2

Laten we aannemen dat de workload-backend toegang moet hebben tot OneLake via de Create Item API (call from Fabric to the workload):

1. De front-end van de workload roept de JavaScript-API aan om een item te maken.

2. De back-end van de workload ontvangt een aanroep van Fabric en extraheert het gedelegeerde token en valideert het.

3. De werklast probeert het token uit te wisselen voor https://storage.azure.com/user_impersonation, maar dit mislukt omdat de tenantbeheerder van de gebruiker een door de gebruiker geconfigureerde multifactorauthenticatie vereist om toegang te krijgen tot Azure Storage (zie AADSTS-foutcodes).

4. De werklast verspreidt de fout samen met de claims die in de fout van Microsoft Entra ID worden teruggegeven naar de client door gebruik te maken van de foutpropagatie zoals beschreven in Workload communication.

5. De front-end van de workload roept de acquireAccessToken JavaScript-API aan en biedt claims als claimsForConditionalAccessPolicy, waarbij claims verwijst naar de claims die zijn doorgegeven vanuit de back-end van de workload:

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

Daarna kan de werklast de operatie opnieuw proberen.

Afhandelingsfouten bij het aanvragen van toestemming

Soms kan de gebruiker geen toestemming verlenen vanwege verschillende fouten. Na een toestemmingsaanvraag wordt het antwoord geretourneerd naar de omleidings-URI. In ons voorbeeld is deze code verantwoordelijk voor het verwerken van het antwoord. (U vindt deze in het bestand 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(); 
} 

De workload front-end kan de foutcode uit de URL extraheren en dienovereenkomstig afhandelen.

Opmerking

In beide scenario's (fout en succes) moet de workload het venster altijd onmiddellijk sluiten, zonder latentie.