Übersicht über die Richtlinien für die Workloadauthentifizierung in Microsoft Fabric

Dieser Artikel enthält Richtlinien zum Arbeiten mit der Authentifizierung beim Erstellen von Microsoft Fabric-Workloads. Sie enthält Informationen zum Arbeiten mit Token und Zustimmungen.

Bevor Sie beginnen, stellen Sie sicher, dass Sie mit den Konzepten in Authentifizierungsübersicht und Authentifizierungseinrichtungvertraut sind.

APIs der Datenebene und der Steuerungsebene

• Datenebenen-APIs sind Schnittstellen, die vom Workload-Back-End bereitgestellt werden. Das Workload-Frontend kann sie direkt aufrufen. Bei APIs der Datenebene kann das Workload-Back-End entscheiden, welche APIs verfügbar gemacht werden sollen.

• Steuerungsebenen-APIs sind APIs, die über Fabric geleitet werden. Der Prozess beginnt mit dem Workload-Frontend, das eine JavaScript-API aufruft, und er endet mit Fabric, die das Workload-Back-End aufruft. Ein Beispiel für eine solche API ist "Element erstellen".

  Für Steuerebenen-APIs muss die Workload den im Workload-Back-End definierten Verträgen folgen und diese APIs implementieren.

API-Registerkarte in der Workload-Anwendung in Microsoft Entra ID bereitstellen

Auf der Registerkarte Api- verfügbar machen, müssen Sie Bereiche für Steuerebenen-APIs und Bereiche für Datenebenen-APIs hinzufügen:

• Die Bereiche, die für Control-Plane-APIs hinzugefügt wurden, sollten den Fabric-Client für die Workloads-Anwendung mit Anwendungs-ID d2450708-699c-41e3-8077-b0c8341509aavorab genehmigen. Diese Bereiche sind im Token enthalten, das das Workload-Back-End empfängt, wenn Fabric sie aufruft.

  Sie müssen mindestens einen Bereich für die API der Steuerebene hinzufügen, damit der Ablauf funktioniert.

• Die für Datenebenen-APIs hinzugefügten Bereiche sollten Microsoft Power BI mit Anwendungs-ID 871c010f-5e61-4fb1-83ac-98610a7e9110vorab autorisieren. Sie sind im Token enthalten, das die acquireAccessToken JavaScript-API zurückgibt.

  Für APIs auf Datenebene können Sie diese Registerkarte verwenden, um granulare Berechtigungen für jede API zu verwalten, die Ihre Workload verfügbar macht. Im Idealfall sollten Sie eine Reihe von Bereichen für jede API hinzufügen, die vom Workload-Back-End verfügbar gemacht und überprüft wird, ob das empfangene Token diese Bereiche enthält, wenn diese APIs vom Client aufgerufen werden. Zum Beispiel:

  • Die Workload macht zwei APIs für den Client verfügbar, ReadData und WriteData.
  • Die Workload macht zwei Datenebenenbereiche, data.read und data.writeverfügbar.
  • In der ReadData-API überprüft die Arbeitslast, ob der data.read-Bereich im Token enthalten ist, bevor der Prozess fortfährt. Dasselbe gilt für WriteData.

Registerkarte "API-Berechtigungen" in der Anwendung der Workload in der Microsoft Entra-ID

Auf der Registerkarte API-Berechtigungen müssen Sie alle Bereiche hinzufügen, für die Ihre Workload ein Token austauschen muss. Ein Pflichtbereich zum Hinzufügen ist Fabric.Extend unter dem Power BI-Dienst. Anforderungen an Fabric können ohne diesen Bereich fehlschlagen.

Arbeiten mit Token und Zustimmungen

Wenn Sie mit Datenebenen-APIs arbeiten, muss das Workload-Frontend ein Token für Aufrufe an das Workload-Backend erwerben.

In den folgenden Abschnitten wird beschrieben, wie das Workload-Frontend die JavaScript-API- und im Auftrag von (OBO)-Flüssen verwenden soll, um Token für die Workload und externe Dienste abzurufen und mit Zustimmungen zu arbeiten.

Schritt 1: Abrufen eines Tokens

Die Workload beginnt mit der Abfrage eines Tokens mithilfe der JavaScript-API, ohne Parameter bereitzustellen. Dieser Aufruf kann zu zwei Szenarien führen:

• Der Benutzer sieht ein Zustimmungsfenster für alle statischen Abhängigkeiten, die in der Registerkarte API-Berechtigungen konfiguriert sind und die die Workload eingerichtet hat. Dieses Szenario tritt ein, wenn der Benutzer kein Teil des Mandanten der Anwendung ist und Microsoft Graph für diese Anwendung zuvor keine Zustimmung erteilt hat.

• Der Benutzer sieht kein Zustimmungsfenster. Dieses Szenario tritt auf, wenn der Benutzer mindestens einmal seine Zustimmung zu Microsoft Graph für diese Anwendung gegeben hat oder Teil des Heimmandanten der Anwendung ist.

In beiden Szenarien sollte es der Workload egal sein, ob der Benutzer die vollständige Zustimmung für alle Abhängigkeiten erteilt hat (und dies zum jetzigen Zeitpunkt nicht wissen könnte). Das empfangene Token hat die Workload-Back-End-Empfängergruppe und kann direkt dazu verwendet werden, das Workload-Back-End vom Workload-Frontend aus aufzurufen.

Schritt 2: Versuchen Sie, auf externe Dienste zuzugreifen

Die Workload muss möglicherweise auf Dienste zugreifen, die eine Authentifizierung erfordern. Für diesen Zugriff muss der OBO-Flussausgeführt werden, wobei es das Token austauscht, das es von seinem Client oder von Fabric an einen anderen Dienst empfangen hat. Der Tokenaustausch kann aufgrund fehlender Zustimmung oder einer Microsoft Entra-Richtlinie für bedingten Zugriff fehlschlagen, die für die Ressource konfiguriert ist, für die die Workload versucht, das Token auszutauschen.

Um dieses Problem zu lösen, liegt es in der Verantwortung der Workload, den Fehler beim Arbeiten mit direkten Aufrufen zwischen dem Front-End und dem Back-End an den Client zu verteilen. Es liegt auch in der Verantwortung der Workload, den Fehler bei der Bearbeitung von Aufrufen von Fabric an den Client weiterzuleiten, indem die in Workload-Kommunikationbeschriebene Fehlerweiterleitung verwendet wird.

Nachdem die Workload den Fehler weitergegeben hat, kann sie die acquireAccessToken JavaScript-API aufrufen, um das Zustimmungs- oder Richtlinienproblem mit bedingtem Zugriff zu lösen und den Vorgang erneut auszuführen.

Informationen zu API-Fehlern auf der Datenebene finden Sie unter Behandeln von mehrstufiger Authentifizierung, bedingter Zugriff und inkrementeller Zustimmung. Informationen zu Steuerungsebenen-API-Fehlern finden Sie unter Workload-Kommunikation.

Beispielszenarien

Sehen wir uns eine Arbeitslast an, die auf drei Fabric-APIs zugreifen muss:

• Arbeitsbereiche auflisten: GET https://api.fabric.microsoft.com/v1/workspaces

• Erstellen eines Warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• In eine Lakehouse-Datei schreiben: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Um mit diesen APIs arbeiten zu können, muss das Workload-Back-End Token für die folgenden Bereiche austauschen:

• Zum Auflisten von Arbeitsbereichen: https://analysis.windows.net/powerbi/api/Workspace.Read.All oder https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Zum Erstellen eines Lagers: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All oder https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Zum Schreiben einer Lakehouse-Datei: https://storage.azure.com/user_impersonation

Die zuvor genannten Geltungsbereiche müssen bei der Workload-Anwendung unter den API-Berechtigungen konfiguriert werden.

Sehen wir uns Beispiele für Szenarien an, denen die Arbeitslast begegnen könnte.

Beispiel 1

Nehmen wir an, dass das Workload-Back-End über eine Datenebenen-API verfügt, die die Arbeitsbereiche des Benutzers abruft und sie an den Client zurückgibt:

1. Das Workload-Frontend fordert ein Token mithilfe der JavaScript-API an.

2. Das Workload-Front-End ruft die Workload-Back-End-API auf, um die Arbeitsbereiche des Benutzers abzurufen und fügt das Token in der Anforderung an.

3. Das Workload-Back-End überprüft das Token und versucht, es für den erforderlichen Bereich auszutauschen (angenommen https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. Die Arbeitslast kann das Token für die angegebene Ressource nicht austauschen, weil der Benutzer der Anwendung den Zugriff auf diese Ressource nicht genehmigt hat (siehe hierzu AADSTS-Fehlercodes).

5. Das Workload-Back-End gibt den Fehler an das Workload-Frontend weiter, indem es angibt, dass es die Zustimmung für diese Ressource benötigt. Das Workload-Frontend ruft die acquireAccessToken JavaScript-API auf und stellt additionalScopesToConsentbereit:

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

   Alternativ kann sich die Workload entscheiden, die Zustimmung für alle statischen Abhängigkeiten zu verlangen, die für ihre Anwendung konfiguriert sind, sodass sie die JavaScript-API aufruft und promptFullConsentbereitstellt:

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

Dieser Aufruf öffnet ein Zustimmungsfenster, ganz gleich, ob der Benutzer einigen der Abhängigkeiten zugestimmt hat oder nicht. Danach kann das Workload-Frontend den Vorgang erneut versuchen.

Beispiel 2

Nehmen wir an, dass das Workload-Back-End auf OneLake in der Create Item API zugreifen muss (Aufruf von Fabric bis zur Workload):

1. Das Workload-Frontend ruft die JavaScript-API zum Erstellen von Elementen auf.

2. Das Workload-Back-End empfängt einen Aufruf von Fabric und extrahiert das delegierte Token und überprüft es.

3. Die Workload versucht, das Token für https://storage.azure.com/user_impersonation auszutauschen, schlägt jedoch fehl, da der Mandantenadministrator der vom Benutzer konfigurierten mehrstufigen Authentifizierung für den Zugriff auf Azure Storage erforderlich ist (siehe AADSTS-Fehlercodes).

4. Die Workload propagiert den Fehler zusammen mit den im Fehler von Microsoft Entra ID enthaltenen Ansprüchen an den Client, indem die in Workload-Kommunikation beschriebene Fehlerweiterleitungverwendet wird.

5. Das Workload-Frontend ruft die acquireAccessToken JavaScript-API auf und stellt Claims als claimsForConditionalAccessPolicybereit, wobei claims auf die vom Workload-Backend weitergeleiteten Ansprüche verweist.

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

Danach kann die Arbeitslast den Vorgang wiederholen.

Behandeln von Fehlern beim Anfordern von Zustimmungen

Manchmal kann der Benutzer aufgrund verschiedener Fehler keine Zustimmung erteilen. Nach einer Zustimmungsanforderung wird die Antwort an den Weiterleitungs-URI zurückgegeben. In unserem Beispiel ist dieser Code für die Behandlung der Antwort verantwortlich. (Sie finden sie in der index.ts Datei.)

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

Das Workload-Frontend kann den Fehlercode aus der URL extrahieren und entsprechend behandeln.