Del via

Oversikt over retningslinjer for arbeidsbelastningsgodkjenning i Microsoft Fabric

  • Artikkel

Denne artikkelen inneholder retningslinjer for hvordan du arbeider med godkjenning når du bygger Microsoft Fabric-arbeidsbelastninger. Den inneholder informasjon om hvordan du arbeider med tokener og samtykker.

Før du begynner, må du kontrollere at du er kjent med konseptene i Oversikt over godkjenning og konfigurasjon av godkjenning.

API-er for dataplan og kontrollfly

  • dataplan-API-er er API-er som arbeidsbelastningens serverdel eksponerer. Arbeidsbelastnings frontend kan ringe dem direkte. For dataplan-API-er kan arbeidsbelastningens serverdel bestemme hvilke API-er som skal eksponeres.

  • Kontroll fly API-er er API-er som går gjennom Fabric. Prosessen starter med arbeidsbelastningen som kaller en JavaScript-API, og den slutter med at Fabric kaller arbeidsbelastningen backend. Et eksempel på en slik API er Opprett element.

    For kontrollplan-API-er må arbeidsbelastningen følge kontraktene som er definert i arbeidsbelastningens serverdel og implementere disse API-ene.

Vise en API-fane på arbeidsbelastningens program i Microsoft Entra ID

På fanen Vise en API-, må du legge til omfang for kontrollplan-API-er og omfang for dataplan-API-er:

  • Omfangene som er lagt til for API-er for kontrollplan, bør forhåndsautorisere Fabric Client for Workloads-programmet med program-ID d2450708-699c-41e3-8077-b0c8341509aa. Disse omfangene er inkludert i tokenet som arbeidsbelastningen backend mottar når Fabric kaller det.

    Du må legge til minst ett omfang for kontrollplan-API-en for at flyten skal fungere.

  • Omfangene som er lagt til for API-er for dataplan, bør forhåndsautorisere Microsoft Power BI med program-ID-871c010f-5e61-4fb1-83ac-98610a7e9110. De er inkludert i tokenet som acquireAccessToken JavaScript-API-en returnerer.

    For dataplan-API-er kan du bruke denne fanen til å administrere detaljerte tillatelser for hver API som arbeidsbelastningen viser. Ideelt sett bør du legge til et sett med omfang for hver API som arbeidsbelastningens serverdel viser og validerer at det mottatte tokenet inkluderer disse omfangene når disse API-ene kalles fra klienten. For eksempel:

    • Arbeidsbelastningen viser to API-er til klienten, ReadData og WriteData.
    • Arbeidsbelastningen viser to dataplanomfang, data.read og data.write.
    • I ReadData API validerer arbeidsbelastningen at det data.read omfanget er inkludert i tokenet før det fortsetter med flyten. Det samme gjelder for WriteData.

API-tillatelser-fanen på arbeidsbelastningens program i Microsoft Entra ID

På API-tillatelser fanen, må du legge til alle omfangene som arbeidsbelastningen må utveksle et token for. Et obligatorisk område å legge til er Fabric.Extend under Power BI-tjenesten. Forespørsler til Fabric kan mislykkes uten dette omfanget.

Arbeide med tokener og samtykker

Når du arbeider med API-er for dataplan, må arbeidsbelastningsforfølgeren skaffe et token for anrop til arbeidsbelastningens serverdel.

De følgende avsnittene beskriver hvordan arbeidsbelastningsforekomster skal bruke JavaScript-API- og på vegne av (OBO)-flyter til å skaffe tokener for arbeidsbelastningen og eksterne tjenester, og til å arbeide med samtykker.

Trinn 1: Hent et token

Arbeidsbelastningen starter med å be om et token ved hjelp av JavaScript-API-en uten å oppgi noen parametere. Dette kallet kan resultere i to scenarioer:

  • Brukeren ser et samtykkevindu for alle statiske avhengigheter (det som er konfigurert på API-tillatelser fanen) som arbeidsbelastningen konfigurerte. Dette scenarioet skjer hvis brukeren ikke er en del av hjemmeleieren av programmet, og brukeren ikke har gitt samtykke til Microsoft Graph for dette programmet før.

  • Brukeren ser ikke et samtykkevindu. Dette scenarioet skjer hvis brukeren allerede samtykket minst én gang til Microsoft Graph for dette programmet, eller hvis brukeren er en del av programmets hjemmeleieren.

I begge scenarioene bør arbeidsmengden ikke bry seg om brukeren ga fullt samtykke til alle avhengighetene (og kan ikke vite på dette tidspunktet). Det mottatte tokenet har målgruppen for arbeidsbelastningen og kan brukes til å ringe arbeidsbelastningen direkte fra arbeidsbelastningsfortjenesten.

Trinn 2: Prøv å få tilgang til eksterne tjenester

Arbeidsmengden må kanskje få tilgang til tjenester som krever godkjenning. For denne tilgangen må den utføre OBO-flyten, der den utveksler tokenet som den mottok fra klienten eller fra Fabric til en annen tjeneste. Tokenutvekslingen kan mislykkes på grunn av manglende samtykke eller en Microsoft Entra-policy for betinget tilgang som er konfigurert på ressursen som arbeidsbelastningen prøver å utveksle tokenet for.

For å løse dette problemet er det arbeidsbelastningens ansvar å overføre feilen til klienten når du arbeider med direkte anrop mellom frontend og serverdel. Det er også arbeidsbelastningens ansvar å overføre feilen til klienten når du arbeider med anrop fra Fabric ved hjelp av feiloverføringen som er beskrevet i arbeidsbelastningskommunikasjon.

Når arbeidsbelastningen overfører feilen, kan den kalle acquireAccessToken JavaScript-API for å løse problemet med samtykket eller policyen for betinget tilgang, og prøve operasjonen på nytt.

Hvis du vil ha dataplan-API-feil, kan du se Håndtere godkjenning med flere faktorer, betinget tilgang og trinnvis samtykke. Hvis du vil ha kontrollplan-API-feil, kan du se Arbeidsbelastningskommunikasjon.

Eksempelscenarioer

La oss ta en titt på en arbeidsbelastning som trenger tilgang til tre Fabric API-er:

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

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

Hvis du vil kunne arbeide med disse API-ene, må arbeidsbelastningens serverdel utveksle tokener for følgende omfang:

  • For oppføring av arbeidsområder: https://analysis.windows.net/powerbi/api/Workspace.Read.All eller https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
  • For å opprette et lager: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All eller https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • For å skrive til en lakehouse-fil: https://storage.azure.com/user_impersonation

Merk

Du kan finne omfang som kreves for hver Fabric API i denne referanseartikkelen.

Omfanget nevnt tidligere må konfigureres på arbeidsbelastningsprogrammet under API-tillatelser.

La oss ta en titt på eksempler på scenarioer som arbeidsbelastningen kan støte på.

Eksempel 1

La oss anta at arbeidsbelastningens serverdel har et dataplan-API som henter arbeidsområdene til brukeren og returnerer dem til klienten:

  1. Arbeidsbelastningsforfølgeren ber om et token ved hjelp av JavaScript-API-en.

  2. Arbeidsbelastningen frontend kaller arbeidsbelastningen backend API for å få arbeidsområdene til brukeren og legger ved tokenet i forespørselen.

  3. Serverdel for arbeidsbelastning validerer tokenet og prøver å bytte det mot det nødvendige omfanget (la oss si https://analysis.windows.net/powerbi/api/Workspace.Read.All).

  4. Arbeidsbelastningen kan ikke bytte tokenet for den angitte ressursen fordi brukeren ikke samtykket til at programmet fikk tilgang til denne ressursen (se AADSTS-feilkoder).

  5. Arbeidsbelastningens serverdel overfører feilen til arbeidsbelastningen frontend ved å angi at den trenger samtykke for denne ressursen. Arbeidsbelastnings frontend kaller acquireAccessToken JavaScript API og gir additionalScopesToConsent:

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

    Arbeidsbelastningen kan eventuelt bestemme seg for å be om samtykke for alle statiske avhengigheter som er konfigurert i programmet, slik at den kaller JavaScript-API-en og gir promptFullConsent:

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

Denne samtalen ber om et samtykkevindu uavhengig av om brukeren har samtykket til noen av avhengighetene eller ikke. Etter dette kan arbeidsmengden som er frontet, prøve operasjonen på nytt.

Merk

Hvis tokenutvekslingen fremdeles mislykkes med en samtykkefeil, betyr det at brukeren ikke ga samtykke. Arbeidsbelastningen må håndtere slike scenarioer. Du kan for eksempel varsle brukeren om at denne API-en krever samtykke og ikke vil fungere uten den.

Eksempel 2

La oss anta at arbeidsbelastningen backend trenger å få tilgang til OneLake på Opprett element API (ring fra Fabric til arbeidsbelastningen):

  1. Arbeidsbelastnings frontend kaller Create Item JavaScript-API-en.

  2. Arbeidsbelastningsstøtten mottar et anrop fra Fabric og trekker ut det delegerte tokenet og validerer det.

  3. Arbeidsbelastningen prøver å bytte tokenet for https://storage.azure.com/user_impersonation men mislykkes fordi leieradministratoren for den brukerkonfigurerte multifaktorgodkjenningen som trengs for å få tilgang til Azure Storage (se AADSTS-feilkoder).

  4. Arbeidsbelastningen overfører feilen sammen med krav som returneres i feilen fra Microsoft Entra ID til klienten ved hjelp av feiloverføringen som er beskrevet i arbeidsbelastningskommunikasjon.

  5. Arbeidsbelastningsfor frontend kaller acquireAccessToken JavaScript API og gir krav som claimsForConditionalAccessPolicy, der claims refererer til krav overført fra arbeidsbelastningen backend:

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

Deretter kan arbeidsbelastningen prøve operasjonen på nytt.

Håndtere feil når du ber om samtykke

Noen ganger kan ikke brukeren gi samtykke på grunn av ulike feil. Etter en samtykkeforespørsel returneres svaret til omadresserings-URI-en. I vårt eksempel er denne koden ansvarlig for å håndtere svaret. (Du finner den i index.ts-filen.)

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(); 
}

Arbeidsmengden frontend kan trekke ut feilkoden fra nettadressen og håndtere den tilsvarende.

Merk

I begge scenarioene (feil og suksess) må arbeidsbelastningen alltid lukke vinduet umiddelbart, uten ventetid.