Omówienie wytycznych dotyczących uwierzytelniania obciążeń w usłudze Microsoft Fabric

Artykuł
12/13/2024

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.

Przed rozpoczęciem upewnij się, że znasz pojęcia z Przegląd uwierzytelniania i Konfiguracja uwierzytelniania.

Interfejsy API płaszczyzny danych i płaszczyzny sterowania

Interfejsy API płaszczyzny danych to interfejsy udostępniane przez backend obciążenia. Fronton obciążenia może wywoływać je bezpośrednio. W przypadku interfejsów API płaszczyzny danych zaplecze obciążenia może zdecydować, jakie interfejsy API mają być uwidaczniane.
interfejsy API płaszczyzny sterowania to interfejsy API przechodzące przez sieć szkieletową. Proces rozpoczyna się od wywołania przez frontend obciążenia interfejsu JavaScript API i kończy się na wywołaniu zaplecza obciążenia przez Fabric. Przykładem takiego interfejsu API jest tworzenie elementu.

W przypadku interfejsów API płaszczyzny sterowania obciążenie musi być zgodne z kontraktami zdefiniowanymi w zapleczu obciążenia i zaimplementować te interfejsy API.

Wyświetl kartę API w aplikacji obciążenia w Microsoft Entra ID

Na karcie Ujawnić interfejs API należy dodać zakresy dla interfejsów API płaszczyzny sterowania oraz zakresy dla interfejsów API płaszczyzny danych.

Zakresy dodane dla interfejsów API płaszczyzny sterowania powinny wstępnie uwierzytelniać aplikację Fabric Client for Workloads o identyfikatorze aplikacji d2450708-699c-41e3-8077-b0c8341509aa. Zakresy te są uwzględniane w tokenie, który zaplecze robocze odbiera, gdy Fabric go wywołuje.

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

W przypadku interfejsów API płaszczyzny danych możesz użyć tej karty do zarządzania uprawnieniami na poziomie szczegółowości dla każdego interfejsu 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 sprawdza, czy zakres data.read jest uwzględniony w tokenie przed kontynuowaniem procesu. To samo dotyczy WriteData.

Zakładka Uprawnienia API w aplikacji dla obciążenia roboczego w Microsoft Entra ID

Na karcie uprawnienia interfejsu API należy dodać wszystkie zakresy wymagane przez obciążenie do wymiany tokenu. Obowiązkowym zakresem do dodania jest Fabric.Extend w usłudze Power BI. Żądania do Fabric mogą zakończyć się niepowodzeniem bez tego zakresu.

Praca z tokenami i zgodami

Podczas pracy z interfejsami API płaszczyzny danych fronton obciążenia musi uzyskać token dla wywołań zaplecza obciążenia.

W poniższych sekcjach opisano, jak fronton obciążenia powinien używać interfejsu API języka JavaScript i przepływów on-behalf-of (OBO) do uzyskiwania tokenów dla obciążeń 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 wywołanie może spowodować dwa scenariusze:

Użytkownik widzi okno zgody wszystkich zależności statycznych (skonfigurowane na karcie uprawnień interfejsu API ) skonfigurowanego obciążenia. Ten scenariusz występuje, jeśli użytkownik nie jest częścią dzierżawy głównej aplikacji, a użytkownik nie udzielił wcześniej zgody na program Microsoft Graph dla tej aplikacji.
Użytkownik nie widzi okna zgody. Ten scenariusz występuje, jeśli użytkownik wyraził już zgodę co najmniej raz na program Microsoft Graph dla tej aplikacji lub jeśli użytkownik jest częścią dzierżawy głównej 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 ma docelowego odbiorcę zaplecza obciążenia i może być używany do bezpośredniego wywoływania zaplecza obciążenia z front-endu obciążenia.

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, gdzie wymienia token otrzymany od klienta lub z 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, obciążenie jest odpowiedzialne za propagowanie błędu do klienta podczas pracy z bezpośrednimi wywołaniami między frontonem a zapleczem. To również do obciążenia roboczego należy propagowanie błędu do klienta podczas pracy z wywołaniami z Fabric, przy użyciu propagacji błędów opisanej w rozdziale Komunikacja obciążenia.

Po tym, jak obciążenie spowoduje błąd, może zostać wywołany interfejs API języka JavaScript acquireAccessToken, aby rozwiązać problem z zgodą lub problem z zasadami dostępu warunkowego i ponowić próbę wykonania operacji.

Aby uzyskać informacje o błędach interfejsu API płaszczyzny danych, zobacz Obsługa uwierzytelniania wieloskładnikowego, dostępu warunkowego, i zgody przyrostowej. Aby uzyskać informacje o błędach interfejsu API płaszczyzny 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 listę obszarów roboczych: GET https://api.fabric.microsoft.com/v1/workspaces
Tworzenie magazynu: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses
Zapisywanie w pliku lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Aby móc pracować z tymi interfejsami API, zaplecze obciążenia musi wymieniać tokeny dla następujących zakresów:

Wyświetlanie listy obszarów 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 w pliku lakehouse: https://storage.azure.com/user_impersonation

Uwaga

Zakresy wymagane dla każdego interfejsu API Fabric można znaleźć 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 zaplecze robocze ma interfejs API warstwy danych, który pobiera przestrzenie robocze użytkownika i zwraca je do klienta.

Interfejs frontowy obciążenia roboczego prosi o token, używając interfejsu API JavaScript.
Fronton obciążenia wywołuje interfejs API zaplecza obciążenia, aby pobrać obszary robocze użytkownika i dołączyć token w żądaniu.
Zaplecze obciążenia weryfikuje token i próbuje wymienić go dla wymaganego zakresu (załóżmy: 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 zadaniowe propaguje błąd do interfejsu użytkownika, precyzując, że wymaga zgody dla tego zasobu. Fronton obciążenia wywołuje interfejs API języka JavaScript acquireAccessToken i udostępnia additionalScopesToConsent:

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

Alternatywnie obciążenie może zdecydować się poprosić o zgodę na wszystkie swoje statyczne zależności skonfigurowane w aplikacji, dlatego wywołuje interfejs API języka JavaScript i udostępnia 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. Następnie frontend obciążenia może ponowić próbę wykonania operacji.

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 zaplecze roboczego musi uzyskać dostęp do usługi OneLake w interfejsu API tworzenia elementu (wywołanie z Fabric do zaplecza roboczego):

Fronton obciążenia wywołuje interfejs API tworzenia elementu JavaScript.
Backend obciążenia odbiera wywołanie z Fabric, wyodrębnia token delegowany i go weryfikuje.
Obciążenie próbuje wymienić token dla https://storage.azure.com/user_impersonation, ale nie udaje się to, ponieważ administrator dzierżawy odpowiedzialny za skonfigurowane przez użytkownika uwierzytelnianie wieloskładnikowe, które jest wymagane do uzyskania dostępu do usługi Azure Storage, uniemożliwia proces (zobacz kody błędów AADSTS ).
Obciążenie propaguje błąd wraz z oświadczeniami zwróconymi w błędzie z identyfikatora Entra firmy Microsoft do klienta przy użyciu propagacji błędów opisanej w Komunikacja obciążenia.
Fronton obciążenia wywołuje interfejs API języka JavaScript acquireAccessToken i udostępnia oświadczenia jako claimsForConditionalAccessPolicy, gdzie claims odnosi się do oświadczeń propagowanych z zaplecza obciążenia:

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

Następnie obciążenie może ponowić próbę wykonania operacji.

Obsługa błędów podczas żądania zgody

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ń.

Udostępnij za pośrednictwem

Omówienie wytycznych dotyczących uwierzytelniania obciążeń w usłudze Microsoft Fabric

Interfejsy API płaszczyzny danych i płaszczyzny sterowania

Wyświetl kartę API w aplikacji obciążenia w Microsoft Entra ID

Zakładka Uprawnienia API w aplikacji dla obciążenia roboczego 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 żądania zgody

Opinia

Dodatkowe zasoby