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 u begint, moet u ervoor zorgen dat u bekend bent met de concepten in verificatieoverzicht en verificatie-instelling.

API's voor gegevensvlak en besturingsvlak

• API's voor gegevensvlak zijn API's die door de back-end van de workload worden weergegeven. De front-end van de workload kan deze rechtstreeks aanroepen. Voor API's van het gegevensvlak kan de back-end van de workload bepalen welke API's beschikbaar moeten worden gesteld.

• 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 bereiken die zijn toegevoegd voor besturingsvlak-API's moeten de Fabric Client for Workloads-toepassing vooraf autoriseren met de toepassings-id d2450708-699c-41e3-8077-b0c8341509aa. Deze bereiken worden opgenomen in het token dat de back-end van de workload ontvangt wanneer Fabric deze 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 valideert de workload dat de data.read-scope is opgenomen in het token voordat het doorgaat met het proces. Hetzelfde geldt voor WriteData.

Tabblad API-machtigingen op de toepassing van de workload in Microsoft Entra-id

Op het tabblad API-machtigingen moet u alle scopes toevoegen die nodig zijn voor uw workload om een token uit te wisselen. 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.

In de volgende secties wordt beschreven hoe de front-end van de werkbelasting de JavaScript-API en on-behalf-of (OBO) stromen moet gebruiken om tokens te verkrijgen voor de werkbelasting en externe services, 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 van alle statische afhankelijkheden (wat is geconfigureerd op het API-machtigingen tabblad) die de workload heeft 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 worden gebruikt om de workload-backend rechtstreeks aan te roepen vanuit de workload-frontend.

Stap 2: Toegang proberen te krijgen tot externe services

De workload moet mogelijk toegang hebben tot services waarvoor verificatie is vereist. Voor deze toegang moet de OBO-stroomworden uitgevoerd, waar het het token uitwisselt dat het van de client of van Fabric naar een andere service heeft ontvangen. De tokenuitwisseling kan mislukken vanwege een gebrek aan toestemming of een beleid voor voorwaardelijke toegang van Microsoft Entra dat is geconfigureerd voor de resource waarvoor de werkbelasting het token wil uitwisselen.

Om dit probleem op te lossen, is het de verantwoordelijkheid van de workload om de fout door te geven aan de client bij het werken met directe aanroepen tussen de front-end en de back-end. Het is ook de verantwoordelijkheid van de werkbelasting om de fout door te geven aan de client wanneer er gewerkt wordt met oproepen vanuit Fabric, gebruikmakend van de foutpropagatie die beschreven is in Communicatie van werkbelasting.

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. Zie Werkbelastingcommunicatievoor API-fouten in het controlevlak.

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

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

• Schrijven naar een Lakehouse-bestand: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Als u met deze API's wilt kunnen werken, moet de back-end van de workload tokens uitwisselen voor de volgende bereiken:

• Werkruimten weergeven: 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

Notitie

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

De eerder genoemde scopes moeten worden geconfigureerd op de workloadtoepassing onder API-machtigingen.

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 front-end van de workload roept de back-end-API van de workload aan om de werkruimten van de gebruiker op te halen en het token in de aanvraag te koppelen.

3. De back-end van de werkbelasting valideert het token en probeert het uit te wisselen voor het vereiste bereik (laten we zeggen https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. De werklast kan het token niet uitwisselen voor een opgegeven resource omdat de gebruiker geen toestemming heeft gegeven voor toegang tot de resource (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"]})

   De workload kan ook besluiten toestemming te vragen voor alle statische afhankelijkheden die op de toepassing zijn geconfigureerd, zodat hij de JavaScript-API aanroept en promptFullConsent:

   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.

Notitie

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

Stel dat de workload-backend toegang moet hebben tot OneLake via de API voor het maken van items (vanuit Fabric naar de 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 werkbelasting probeert het token voor https://storage.azure.com/user_impersonation uit te wisselen, maar slaagt er niet in omdat de tenantbeheerder van de door de gebruiker geconfigureerde meervoudige verificatie nodig is voor toegang tot Azure Storage (zie AADSTS-foutcodes).

4. De workload geeft de fout door samen met de claims die in de fout van Microsoft Entra ID aan de client zijn geretourneerd, gebruikmakend van de foutdoorgifte zoals beschreven in Workload communicatie.

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 bewerking opnieuw uitvoeren.

Fouten afhandelen bij het aanvragen van toestemmingen

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.

Notitie

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