Przegląd wytycznych uwierzytelniania obciążeń w Microsoft Fabric

Ten artykuł zawiera wskazówki dotyczące pracy z uwierzytelnianiem podczas tworzenia obciążeń usługi Microsoft Fabric. Zawiera ona informacje o pracy z tokenami i zgodyami.

Zanim zaczniesz, upewnij się, że znasz pojęcia z przeglądu uwierzytelniania i ustawień uwierzytelniania.

API płaszczyzny danych i płaszczyzny sterowania

API Data plane to API, które udostępnia backend obciążenia. Frontend obciążenia może do nich dzwonić bezpośrednio. W przypadku interfejsów API warstwy danych zaplecze obsługujące obciążenie może decydować o tym, które interfejsy API udostępniać.
API w płaszczyźnie sterowania to API, które przechodzą przez Fabric. Proces rozpoczyna się od wywołania interfejsu API JavaScript przez front-end obciążenia roboczego, a kończy się na wywołaniu back-endu obciążenia roboczego przez Fabric. Przykładem takiego interfejsu API jest tworzenie elementu.

W przypadku interfejsów API płaszczyzny sterowania aplikacja musi przestrzegać kontraktów zdefiniowanych w backendzie aplikacji i implementować te interfejsy API.

Udostępnij zakładkę API na aplikacji obciążenia w Microsoft Entra ID

Na zakładce Expose an API musisz dodać zakresy API płaszczyzn sterowania oraz zakresy API płaszczyzn danych:

Zakresy dodane dla interfejsów API płaszczyzny sterowania powinny nadać wstępną autoryzację aplikacji Fabric Client for Workloads o identyfikatorze aplikacji d2450708-699c-41e3-8077-b0c8341509aa. Te zakresy są zawarte w tokenie, który backend workload otrzymuje, gdy Fabric go wywołuje.

Musisz dodać co najmniej jeden zakres dla interfejsu API płaszczyzny sterowania, aby przepływ działał.
Zakresy dodane dla interfejsów API płaszczyzny danych powinny wstępnie autoryzować usługę Microsoft Power BI przy użyciu identyfikatora aplikacji 871c010f-5e61-4fb1-83ac-98610a7e9110. Są one zawarte w tokenie zwracanym przez acquireAccessToken interfejs API JavaScript.

W przypadku API na płaszczyźnie danych możesz użyć tej zakładki do zarządzania szczegółowymi uprawnieniami dla każdego API, które udostępnia Twoje obciążenie. W idealnym przypadku należy dodać zestaw zakresów dla każdego interfejsu API uwidacznianego przez zaplecze obciążenia i sprawdzić, czy odebrany token zawiera te zakresy, gdy te interfejsy API są wywoływane z klienta. Na przykład:
- Obciążenie udostępnia dwa interfejsy API dla klienta, ReadData i WriteData.
- Obciążenie uwidacznia dwa zakresy płaszczyzny danych, data.read i data.write.
- W interfejsie API ReadData obciążenie robocze weryfikuje, czy zakres data.read jest zawarty w tokenie, zanim będzie kontynuować przepływ. To samo dotyczy WriteData.

Zakładka uprawnień API w aplikacji workloadu w Microsoft Entra ID

Na karcie Uprawnienia API musisz dodać wszystkie zakresy uprawnień, których Twoje obciążenie potrzebuje do wymiany tokenu. Obowiązkowy zakres do dodania to Fabric.Extend w usłudze Power BI. Żądania do Fabric mogą się nie powiodować bez tego zakresu.

Praca z tokenami i zgodami

Podczas pracy z interfejsami API płaszczyzny danych frontend obciążenia musi uzyskać token na potrzeby wywołań do backendu obciążenia.

Poniższe sekcje opisują, jak interfejs użytkownika obciążenia powinien wykorzystywać interfejs API języka JavaScript oraz przepływy w imieniu użytkownika (OBO) do uzyskiwania tokenów dla obciążenia i usług zewnętrznych oraz do pracy ze zgodami.

Krok 1. Uzyskiwanie tokenu

Praca zaczyna się od żądania tokenu za pomocą API JavaScript bez podawania jakichkolwiek parametrów. To wezwanie może skutkować dwoma scenariuszami:

Użytkownik widzi okno zgody obejmujące wszystkie zależności statyczne (skonfigurowane na karcie Uprawnienia API), które skonfigurowało obciążenie robocze. Taka sytuacja występuje, jeśli użytkownik nie należy do dzierżawy macierzystej aplikacji i nie udzielił wcześniej tej aplikacji zgody na korzystanie z Microsoft Graph.
Użytkownik nie widzi okna zgody. Scenariusz ten występuje, jeśli użytkownik wyraził zgodę przynajmniej raz na Microsoft Graph dla tej aplikacji lub jeśli jest częścią domowego dzierżawcy aplikacji.

W obu scenariuszach obciążenie nie powinno się przejmować tym, czy użytkownik udzielił pełnej zgody na wszystkie zależności (i nie może tego wiedzieć w tym momencie). Odebrany token jest przeznaczony dla backendu usługi i może służyć do bezpośredniego wywoływania backendu usługi z frontendu usługi.

Krok 2. Próba uzyskania dostępu do usług zewnętrznych

Obciążenie może wymagać dostępu do usług wymagających uwierzytelniania. Aby uzyskać ten dostęp, musi wykonać przepływ OBO, czyli wymieniać token otrzymany od klienta lub Fabric na inną usługę. Wymiana tokenów może zakończyć się niepowodzeniem z powodu braku zgody lub niektórych zasad dostępu warunkowego firmy Microsoft skonfigurowanych dla zasobu, dla którego obciążenie próbuje wymienić token.

Aby rozwiązać ten problem, to po stronie aplikacji leży obowiązek przekazania błędu do klienta w przypadku bezpośrednich wywołań między frontendem a backendem. Jest to również odpowiedzialność obciążenia roboczego, aby propagować błąd do klienta podczas obsługi wywołań z usługi Fabric przy użyciu mechanizmu propagowania błędów opisanego w Komunikacja obciążenia roboczego.

Po propagacji błędu przez obciążenie może wywołać acquireAccessToken JavaScript API, aby rozwiązać problem polityki zgody lub dostępu warunkowego i ponownie wykonać operację.

W przypadku awarii API w płaszczyźnie danych, zobacz Obsługa uwierzytelniania wieloskładnikowego, Dostęp warunkowy oraz przyrostowa zgoda. Aby dowiedzieć się o awariach API na płaszczyźnie sterowania, zobacz Komunikacja obciążenia.

Przykładowe scenariusze

Przyjrzyjmy się obciążeniu, które musi mieć dostęp do trzech interfejsów API Fabric.

Wyświetl przestrzenie robocze: GET https://api.fabric.microsoft.com/v1/workspaces
Stwórz magazyn: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
Zapisz do pliku domku nad jeziorem: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Aby móc korzystać z tych interfejsów API, backend obsługujący obciążenie musi wymieniać tokeny w celu uzyskania następujących zakresów:

Do wypisywania przestrzeni roboczych: https://analysis.windows.net/powerbi/api/Workspace.Read.All lub https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
Tworzenie magazynu: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All lub https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
Do zapisywania plików do domku nad jeziorem: https://storage.azure.com/user_impersonation

Uwaga

Zakres potrzebny dla każdego API Fabric znajdziesz w tym artykule referencyjnym.

Wcześniej wspomniane zakresy należy skonfigurować w aplikacji roboczej w ramach uprawnień interfejsu API .

Przyjrzyjmy się przykładom scenariuszy, które może napotkać obciążenie.

Przykład 1

Załóżmy, że backend obsługujący obciążenie ma interfejs API płaszczyzny danych, który pobiera przestrzenie robocze użytkownika i zwraca je klientowi:

Frontend obciążenia prosi o token za pomocą JavaScript API.
Frontend obciążenia roboczego wywołuje interfejs API backendu obciążenia roboczego, aby pobrać przestrzenie robocze użytkownika, i dołącza token do żądania.
Backend usługi waliduje token i próbuje wymienić go na token o wymaganym zakresie uprawnień (powiedzmy https://analysis.windows.net/powerbi/api/Workspace.Read.All).
Nie można wymienić tokenu dla określonego zasobu, ponieważ użytkownik nie wyraził zgody na dostęp do tego zasobu przez aplikację (zobacz kody błędów usługi AADSTS).
Zaplecze obciążenia przekazuje błąd do interfejsu użytkownika obciążenia, wskazując, że wymaga zgody na ten zasób. Frontend obciążenia roboczego wywołuje interfejs API języka JavaScript acquireAccessToken i zapewnia additionalScopesToConsent:

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

Alternatywnie obciążenie robocze może zdecydować się poprosić o zgodę dla wszystkich swoich statycznych zależności skonfigurowanych w swojej aplikacji, więc wywołuje interfejs API języka JavaScript i przekazuje promptFullConsent:

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

To wywołanie monituje okno zgody niezależnie od tego, czy użytkownik wyraził zgodę na niektóre zależności. Po tym frontend obciążenia roboczego może ponowić operację.

Uwaga

Jeśli wymiana tokenów nadal kończy się niepowodzeniem po błędzie zgody, oznacza to, że użytkownik nie udzielił zgody. Obciążenie musi obsługiwać takie scenariusze; na przykład powiadom użytkownika, że ten interfejs API wymaga zgody i nie będzie działać bez niego.

Przykład 2

Załóżmy, że backend usługi obciążenia musi uzyskać dostęp do OneLake za pośrednictwem interfejsu API Create Item (wywołanie z platformy Fabric do usługi obciążenia):

Frontend obciążenia nazywa Create Item JavaScript API.
Backend obciążenia roboczego otrzymuje wywołanie z usługi Fabric, wyodrębnia delegowany token i weryfikuje jego poprawność.
Obciążenie robocze próbuje wymienić token dla https://storage.azure.com/user_impersonation, ale kończy się to niepowodzeniem, ponieważ administrator dzierżawy wymaga skonfigurowanego przez użytkownika uwierzytelniania wieloskładnikowego w celu uzyskania dostępu do usługi Azure Storage (zobacz kody błędów AADSTS).
Obciążenie robocze propaguje błąd wraz z oświadczeniami zwróconymi w komunikacie o błędzie z usługi Microsoft Entra ID do klienta, przy użyciu mechanizmu propagowania błędów opisanego w Workload communication.
Fronton obciążenia wywołuje interfejs API JavaScript acquireAccessToken i przekazuje oświadczenia w postaci claimsForConditionalAccessPolicy, gdzie claims odnosi się do oświadczeń propagowanych z zaplecza obciążenia:

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

Po tym obciążenie robocze może ponowić operację.

Obsługa błędów podczas wnioskowania o zgodę

Czasami użytkownik nie może udzielić zgody z powodu różnych błędów. Po żądaniu zgody odpowiedź zostanie zwrócona do adresu URL przekierowania. W naszym przykładzie ten kod jest odpowiedzialny za obsługę odpowiedzi. (Można go znaleźć w pliku 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(); 
}

Fronton obciążenia może wyodrębnić kod błędu z adresu URL i odpowiednio go obsłużyć.

Uwaga

W obu scenariuszach (błąd i powodzenie) proces musi zawsze natychmiast zamknąć okno, bez żadnych opóźnień.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-30

Przegląd wytycznych uwierzytelniania obciążeń w Microsoft Fabric

API płaszczyzny danych i płaszczyzny sterowania

Udostępnij zakładkę API na aplikacji obciążenia w Microsoft Entra ID

Zakładka uprawnień API w aplikacji workloadu w Microsoft Entra ID

Praca z tokenami i zgodami

Krok 1. Uzyskiwanie tokenu

Krok 2. Próba uzyskania dostępu do usług zewnętrznych

Przykładowe scenariusze

Przykład 1

Przykład 2

Obsługa błędów podczas wnioskowania o zgodę

Opinia

Dodatkowe zasoby