Authentifizierungsrichtlinien für das Microsoft Fabric Extensibility Toolkit

Dieser Artikel enthält Richtlinien zum Arbeiten mit der Authentifizierung beim Erstellen von Microsoft Fabric-Extensibility Toolkit-Workloads. Sie enthält Informationen zum Arbeiten mit Token, Zustimmungen und zugriff auf verschiedene Dienste aus Ihrer Front-End-Anwendung.

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

Frontend-only-Authentifizierungsmodell

Das Extensibility Toolkit verwendet eine reine Frontend-Architektur, die die Authentifizierung im Vergleich zu herkömmlichen Workloads vereinfacht.

Direkte API-Aufrufe: Ihr Frontend ruft Fabric-APIs, Azure-Dienste und externe Anwendungen direkt auf.
Tokenwiederverwendung: Ein einzelnes Token kann verwendet werden, um sich bei mehreren entra-gesicherten Diensten zu authentifizieren.
Vereinfachte Zustimmung: Die Zustimmungsverwaltung wird von der Plattform mit automatischer Eingabeaufforderung verarbeitet.

Microsoft Entra-Anwendungskonfiguration

API-Registerkarte anzeigen

Konfigurieren Sie Bereiche für Ihre Workloadanwendung:

Fabric-Integrationsbereiche: Vorabautorisierung von Microsoft Power BI mit Anwendungs-ID 871c010f-5e61-4fb1-83ac-98610a7e9110
Benutzerdefinierte API-Bereiche: Hinzufügen von Bereichen für benutzerdefinierte APIs, die Ihre Workload verfügbar macht
Granulare Berechtigungen: Nutzen Sie unterschiedliche Zugriffsbereiche für Lese- und Schreibvorgänge

Wenn Ihre Workload beispielsweise Daten-APIs verfügbar macht:

Füge data.read Bereich für Lesevorgänge hinzu
Füge data.write Bereich für Schreibvorgänge hinzu
Überprüfen der geeigneten Bereiche in Ihren API-Handlern

Registerkarte "API-Berechtigungen"

Konfigurieren von Berechtigungen für externe Dienste, auf die Ihre Workload zugreifen muss:

Erforderlich: Fabric.Extend unter Power BI-Dienst (obligatorisch für die Fabric-Integration)
Azure-Dienste: Hinzufügen von Bereichen für Azure-Dienste wie https://storage.azure.com/user_impersonation
Benutzerdefinierte Anwendungen: Hinzufügen von Bereichen für eigene entra-gesicherte Anwendungen
Dienste von Drittanbietern: Einschließen aller externen Dienste, die entra-Authentifizierung unterstützen

Tokenverwendungsmuster

Verwenden von Token für mehrere Dienste

Das über das Extensibility Toolkit erworbene Frontend-Token kann verwendet werden, um sich gegen folgendes zu authentifizieren:

Fabric-APIs

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Azure-Dienste

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Benutzerdefinierte Anwendungen

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Geltungsbereichsverwaltung

Das Extensibility Toolkit abstrahiert die Bereichsverwaltung für häufige Szenarien:

Fabric-Clientbibliotheken: Automatisches Einschließen erforderlicher Fabric-Bereiche
Azure-Clientbibliotheken: Behandeln von Azure-Dienstbereichen transparent
Benutzerdefinierte Bereiche: Angeben zusätzlicher Bereiche bei Bedarf

Arbeiten mit Zustimmungen

Anfänglicher Tokenerwerb

Beginnen Sie, indem Sie ein Token abrufen, um den Authentifizierungskontext einzurichten:

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

Dieser Aufruf kann zu folgenden Ergebnissen führen:

Zustimmungsaufforderung: Wenn der Benutzer Ihrer Anwendung nicht zugestimmt hat
Stille Übernahme: Falls zuvor die Zustimmung erteilt wurde

Verwaltung von zusätzlichem Dienstzugriff

Wenn Ihre Workload auf zusätzliche Dienste zugreifen muss, geben Sie die erforderlichen Bereiche an:

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

Beispielszenarien

Szenario 1: Zugreifen auf Fabric- und Azure-Dienste

Ihre Arbeitsauslastung erfordert Folgendes:

Fabric-Arbeitsbereiche auflisten
Lesen aus Azure Storage
In Azure Key Vault schreiben

Implementierung:

Konfigurieren von API-Berechtigungen für erforderliche Dienste
Initialtoken abrufen
Verwenden des Tokens für alle Dienstaufrufe
Zustimmungsaufforderungen bei Bedarf behandeln

Szenario 2: Benutzerdefinierte Anwendungsintegration

Ihre Workload ist in Ihren eigenen Back-End-Dienst integriert:

Konfigurieren Ihres Back-End: Stellen Sie sicher, dass sie Entra-Token akzeptiert
Hinzufügen von API-Berechtigungen: Einschließen der Bereiche Ihres Back-Ends in die Workloadanwendung
Standardauthentifizierung verwenden: Das gleiche Tokenmuster funktioniert für Ihre benutzerdefinierten Dienste.

Szenario 3: Integration des Drittanbieterdiensts

Integration in externe Entra-fähige Dienste:

Dienstregistrierung: Registrieren Sie Ihre Workload bei einem Drittanbieterdienst.
Bereichskonfiguration: Hinzufügen der Bereiche des Diensts zu Ihren API-Berechtigungen
Tokenverwendung: Verwenden desselben Authentifizierungsmusters für externe Dienste

Fehlerbehandlung und Fehlerbehebung

Häufige Authentifizierungsfehler

Zustimmung erforderlich: Der Benutzer hat keine Berechtigung für einen bestimmten Bereich erteilt.
Bedingter Zugriff: Zusätzliche Authentifizierungsanforderungen (z. B. MFA)
Tokenablauf: Das Token ist abgelaufen und muss aktualisiert werden.
Ungültiger Bereich: Der angeforderte Bereich ist nicht konfiguriert oder verfügbar.

Fehlerbehandlungsmuster

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

Umleitungs-URI-Behandlung

Das Erweiterbarkeits-Toolkit enthält integrierte Umleitungs-URI-Verarbeitung für Authentifizierungszustimmungs-Popups. Dies wird in der Hauptdatei index.ts implementiert und verarbeitet die Zustimmungsumleitungen automatisch.

Das Toolkit behandelt:

Automatisches Schließen des Fensters: Popups werden nach der Benutzerinteraktion automatisch geschlossen
Fehlerbehandlung: Bestimmte Fehlercodes werden erkannt und entsprechend behandelt.
Fehleranzeige: Fehlgeschlagene Zustimmungsversuche zeigen benutzerfreundliche Fehlermeldungen an

Aktuelle Implementierung im Toolkit:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

Hinweis

Die Umleitungs-URI-Behandlung wird automatisch in der Erweiterungs-Toolkit-Vorlage enthalten. Sie müssen dies nicht selbst implementieren, es sei denn, Sie möchten das Verhalten der Fehlerbehandlung anpassen.

Bewährte Methoden

Tokenverwaltung

Cache-Tokens: Tokens wiederverwenden, bis sie ablaufen
Behandeln der Aktualisierung: Implementieren der automatischen Tokenaktualisierungslogik
Sicherer Speicher: Sicheres Speichern von Token im Browserspeicher

Minimale Berechtigungen: Fordern Sie nur die Bereiche an, die Sie tatsächlich benötigen.
Progressive Zustimmung: Anfordern zusätzlicher Berechtigungen, wenn Features verwendet werden
Klares Messaging: Erläutern, warum Berechtigungen erforderlich sind

Fehlerbehandlung

Sanfte Degradierung: Bereitstellung von Fallback-Funktionen nach Möglichkeit
Benutzerfeedback: Klare Kommunikation der Authentifizierungsanforderungen
Wiederholungslogik: Implementieren geeigneter Wiederholungsmechanismen für vorübergehende Fehler

Feedback

War diese Seite hilfreich?

Last updated on 2025-12-15