Oversigt over retningslinjer for godkendelse af arbejdsbelastninger i Microsoft Fabric

Denne artikel indeholder retningslinjer for, hvordan du arbejder med godkendelse, når du bygger Microsoft Fabric-arbejdsbelastninger. Den indeholder oplysninger om at arbejde med tokens og samtykker.

Før du begynder, skal du sørge for, at du kender begreberne i oversigt over godkendelse og konfiguration af godkendelse.

API'er til dataplan og kontrolflade

• API'er for dataplan er API'er, som arbejdsbelastningens backend viser. Frontend for arbejdsbelastninger kan kalde dem direkte. For dataplan-API'er kan arbejdsbelastningens backend bestemme, hvilke API'er der skal vises.

• Api'er for kontrolflade er API'er, der går gennem Fabric. Processen starter med, at frontend for arbejdsbelastning kalder en JavaScript-API, og den slutter med, at Fabric kalder arbejdsbelastningens backend. Et eksempel på en sådan API er Opret element.

  For kontrolplan-API'er skal arbejdsbelastningen følge de kontrakter, der er defineret i backend for arbejdsbelastningen, og implementere disse API'er.

Vis en API-fane i arbejdsbelastningens program i Microsoft Entra ID

På fanen Eksponer en API- skal du tilføje områder for kontrolplan-API'er og områder for dataplan-API'er:

• De områder, der er tilføjet for api'er for kontrolplanet, skal forhåndsgodkende programmet Fabric Client for Workloads med program-id'et d2450708-699c-41e3-8077-b0c8341509aa. Disse områder er inkluderet i det token, som arbejdsbelastningens backend modtager, når Fabric kalder den.

  Du skal tilføje mindst ét område for API'en til kontrolplanet, for at flowet fungerer.

• De områder, der er tilføjet for dataplan-API'er, skal forhåndsgodkende Microsoft Power BI med program-id'et 871c010f-5e61-4fb1-83ac-98610a7e9110. De er inkluderet i det token, som acquireAccessToken JavaScript-API'en returnerer.

  For dataplan-API'er kan du bruge denne fane til at administrere detaljerede tilladelser for hver API, som din arbejdsbelastning viser. Ideelt set skal du tilføje et sæt områder for hver API, som arbejdsbelastningsbackend viser og validerer, at det modtagne token omfatter disse områder, når disse API'er kaldes fra klienten. For eksempel:

  • Arbejdsbelastningen viser to API'er for klienten, ReadData og WriteData.
  • Arbejdsbelastningen viser to dataplanområder, data.read og data.write.
  • I api'en for ReadData validerer arbejdsbelastningen, at det data.read område er inkluderet i tokenet, før det fortsætter med flowet. Det samme gælder for WriteData.

Fanen API-tilladelser i arbejdsbelastningens program i Microsoft Entra ID

Under fanen API-tilladelser skal du tilføje alle de områder, som din arbejdsbelastning skal udveksle et token for. Et obligatorisk område, der skal tilføjes, er Fabric.Extend under Power BI-tjenesten. Anmodninger til Fabric mislykkes muligvis uden dette omfang.

Arbejde med tokens og samtykker

Når du arbejder med dataplan-API'er, skal frontend-arbejdsbelastningen hente et token til kald til arbejdsbelastningens backend.

I følgende afsnit beskrives det, hvordan frontend af arbejdsbelastninger skal bruge JavaScript API- og på vegne af (OBO)-flow til at hente tokens til arbejdsbelastningen og eksterne tjenester og til at arbejde med samtykker.

Trin 1: Hent et token

Arbejdsbelastningen starter med at bede om et token ved hjælp af JavaScript-API'en uden at angive nogen parametre. Dette kald kan resultere i to scenarier:

• Brugeren får vist et samtykkevindue med alle de statiske afhængigheder (hvad der er konfigureret under fanen API-tilladelser), som arbejdsbelastningen er konfigureret. Dette scenarie sker, hvis brugeren ikke er en del af programmets hjemmelejer, og brugeren ikke har givet samtykke til Microsoft Graph for dette program før.

• Brugeren kan ikke se et samtykkevindue. Dette scenarie sker, hvis brugeren allerede har givet samtykke mindst én gang til Microsoft Graph for dette program, eller hvis brugeren er en del af programmets hjemmelejer.

I begge scenarier er arbejdsbelastningen ligeglad med, om brugeren gav fuldt samtykke til alle afhængighederne (og kan ikke vide det på nuværende tidspunkt). Det modtagne token har backendmålgruppen for arbejdsbelastningen og kan bruges til at kalde arbejdsbelastningens backend direkte fra frontend for arbejdsbelastning.

Trin 2: Prøv at få adgang til eksterne tjenester

Arbejdsbelastningen skal muligvis have adgang til tjenester, der kræver godkendelse. For denne adgang skal den udføre OBO-flowet, hvor det udveksler det token, som det modtog fra klienten eller fra Fabric, til en anden tjeneste. Tokenudvekslingen mislykkes muligvis på grund af manglende samtykke eller en microsoft Entra-politik for betinget adgang, der er konfigureret for den ressource, som arbejdsbelastningen forsøger at udveksle tokenet for.

For at løse dette problem er det arbejdsbelastningens ansvar at overføre fejlen til klienten, når der arbejdes med direkte kald mellem frontend og backend. Det er også arbejdsbelastningens ansvar at overføre fejlen til klienten, når der arbejdes med kald fra Fabric, ved hjælp af den fejloverførsel, der er beskrevet i Arbejdsbelastningskommunikation.

Når arbejdsbelastningen har overført fejlen, kan den kalde acquireAccessToken JavaScript-API'en for at løse problemet med samtykket eller politikken betinget adgang og prøve handlingen igen.

Du kan se fejl i API-fejl for dataplan i Håndtering af multifaktorgodkendelse, betinget adgang og trinvist samtykke. Du kan få mere at vide om fejl i API-kontrolfladen under arbejdsbelastningskommunikation.

Eksempelscenarier

Lad os se på en arbejdsbelastning, der skal have adgang til tre Fabric-API'er:

• Listearbejdsområder: GET https://api.fabric.microsoft.com/v1/workspaces

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

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

For at kunne arbejde med disse API'er skal arbejdsbelastningens backend udveksle tokens for følgende områder:

• Til visning af arbejdsområder: https://analysis.windows.net/powerbi/api/Workspace.Read.All eller https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Oprettelse af et lager: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All eller https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• For at skrive til en lakehouse fil: https://storage.azure.com/user_impersonation

Bemærk

Du kan finde de områder, der er nødvendige for hver Fabric-API, i denne referenceartikel.

De områder, der er nævnt tidligere, skal konfigureres i arbejdsbelastningsprogrammet under API-tilladelser.

Lad os se på eksempler på scenarier, som arbejdsbelastningen kan støde på.

Eksempel 1

Lad os antage, at arbejdsbelastningens backend har en dataplan-API, der henter brugerens arbejdsområder og returnerer dem til klienten:

1. Frontend for arbejdsbelastning beder om et token ved hjælp af JavaScript-API'en.

2. Frontend for arbejdsbelastning kalder arbejdsbelastnings-backend-API'en for at hente brugerens arbejdsområder og vedhæfter tokenet i anmodningen.

3. Backend-arbejdsbelastningen validerer tokenet og forsøger at ombytte det med det påkrævede omfang (lad os sige https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Arbejdsbelastningen kan ikke udveksle tokenet for den angivne ressource, fordi brugeren ikke har givet samtykke til, at programmet skal have adgang til denne ressource (se AADSTS-fejlkoder).

5. Arbejdsbelastningens backend overfører fejlen til frontend for arbejdsbelastningen ved at angive, at den skal have samtykke for den pågældende ressource. Frontend for arbejdsbelastning kalder javascript-API'en for acquireAccessToken og leverer additionalScopesToConsent:

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

   Alternativt kan arbejdsbelastningen beslutte at anmode om samtykke for alle de statiske afhængigheder, der er konfigureret i programmet, så den kalder JavaScript-API'en og giver promptFullConsent:

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

Dette kald beder om et samtykkevindue, uanset om brugeren har givet samtykke til nogle af afhængighederne eller ej. Derefter kan frontend-arbejdsbelastningen prøve handlingen igen.

Bemærk

Hvis tokenudvekslingen stadig mislykkes på en samtykkefejl, betyder det, at brugeren ikke gav samtykke. Arbejdsbelastningen skal håndtere sådanne scenarier. Giv f.eks. brugeren besked om, at denne API kræver samtykke og ikke fungerer uden den.

Eksempel 2

Lad os antage, at arbejdsbelastningens backend skal have adgang til OneLake på API'en Opret element (kald fra Fabric til arbejdsbelastningen):

1. Frontend for arbejdsbelastning kalder JavaScript-API'en Opret element.

2. Arbejdsbelastningens backend modtager et kald fra Fabric og udtrækker det delegerede token og validerer det.

3. Arbejdsbelastningen forsøger at udveksle tokenet for https://storage.azure.com/user_impersonation men mislykkes, fordi lejeradministratoren af den brugerkonfigurerede multifaktorgodkendelse, der er nødvendig for at få adgang til Azure Storage (se AADSTS-fejlkoder).

4. Arbejdsbelastningen overfører fejlen sammen med de krav, der returneres i fejlen fra Microsoft Entra ID, til klienten ved hjælp af den fejloverførsel, der er beskrevet i Arbejdsbelastningskommunikation.

5. Frontend for arbejdsbelastning kalder acquireAccessToken JavaScript-API'en og leverer krav som claimsForConditionalAccessPolicy, hvor claims refererer til de krav, der er overført fra arbejdsbelastningens backend:

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

Derefter kan arbejdsbelastningen prøve handlingen igen.

Håndtering af fejl, når der anmodes om samtykke

Nogle gange kan brugeren ikke give samtykke på grund af forskellige fejl. Efter en anmodning om samtykke returneres svaret til omdirigerings-URI'en. I vores eksempel er denne kode ansvarlig for håndtering af svaret. Du kan finde 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(); 
} 

Frontend til arbejdsbelastning kan udtrække fejlkoden fra URL-adressen og håndtere den i overensstemmelse hermed.

Bemærk

I begge scenarier (fejl og succes) skal arbejdsbelastningen altid lukke vinduet med det samme uden ventetid.