Authentifizierung JavaScript API-Referenz

Das Fabric Extensibility Toolkit bietet eine JavaScript-API zum Erwerb von Authentifizierungstoken, die verwendet werden können, um auf Fabric-APIs, Azure-Dienste und jede von Entra gesicherte Anwendung zuzugreifen. Dieser Artikel bietet umfassende API-Referenzen und Anwendungsbeispiele.

API-Referenz

acquireFrontendAccessToken(params: AcquireFrontendAccessTokenParams): Promise<AccessToken>;

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

Die API liefert ein AccessToken Objekt zurück, das enthält:

• Token: Der JWT-Tokenstring zur Verwendung in Autorisierungsheadern

Grundlegende Nutzung

Einfache Token-Erwerbung

// Acquire a token with default Fabric permissions
const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

// Use the token in API calls
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/json'
  }
});

Token mit spezifischen Scopes

// Request specific scopes for Azure Storage
const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: ['https://storage.azure.com/user_impersonation']
});

Beispiele für Token-Nutzung

Fabric-API-Zugriff

Das Token kann direkt mit Fabric REST APIs verwendet werden:

async function listWorkspaces() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });
  
  const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Azure Service Access

Verwenden Sie Scopes, um die Azure-Dienste anzugeben, auf die Sie Zugriff benötigen:

async function readFromStorage(accountName, containerName, blobName) {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token.token}`,
      'x-ms-version': '2021-12-02'
    }
  });
  
  return await response.text();
}

Benutzerdefinierter Anwendungszugriff

Greifen Sie auf Ihre eigenen Entra-gesicherten Anwendungen zu:

async function callCustomAPI() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://myapp.contoso.com/data.read']
  });
  
  const response = await fetch('https://myapp.contoso.com/api/data', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Parameterreferenz

scopes

Ein Array von Scope-Strings, die die Berechtigungen angeben, die dein Token benötigt.

Übliche Azure Service Scopes:

• https://storage.azure.com/user_impersonation - Azure Storage
• https://vault.azure.net/user_impersonation - Azure Key Vault
• https://management.azure.com/user_impersonation - Azure Resource Manager
• https://graph.microsoft.com/User.Read - Microsoft Graph

Verwendungsbeispiel:

const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: [
    'https://storage.azure.com/user_impersonation'
  ]
});

Leere Scopes-Array: Verwenden Sie ein leeres Array, um ein Token mit Standard-Fabric-Berechtigungen zu erhalten:

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

Einwilligungsverwaltung

Automatischer Einwilligungsfluss

Das Extensibility Toolkit verwaltet automatisch Einwilligungs-Workflows:

• Erstanfrage: Wenn die Zustimmung fehlt, öffnet sich ein Popup-Fenster
• Benutzerinteraktion: Der Nutzer gewährt oder verweigert Berechtigungen
• Automatisches Schließen: Das Popup schließt sich automatisch nach Benutzeraktion
• Token-Zustellung: Wenn erfolgreich, wird der Token an Ihre Anwendung zurückgegeben

Behandlung von Einwilligungs-Popups

Das Toolkit verwaltet automatisch Einwilligungs-Popups, aber du kannst das Redirect-URI-Verhalten anpassen. Erstelle eine Weiterleitungsseite, die die Einwilligungsantwort behandelt:

// redirect.js - Handle consent redirect
const redirectUriPath = '/close';
const url = new URL(window.location.href);

if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle consent errors
  if (url?.hash?.includes("error")) {
    // Extract error information
    const errorMatch = url.hash.match(/error=([^&]+)/);
    const errorDescription = url.hash.match(/error_description=([^&]+)/);
    
    // Handle specific errors
    if (url.hash.includes("AADSTS650052")) {
      console.error("Service principal not configured");
    } else if (url.hash.includes("AADSTS65004")) {
      console.error("User declined consent");
    }
  }
  
  // Always close the popup immediately
  window.close();
}

Zustimmung zum Cross-Tenant

Zum Zugriff auf Ressourcen verschiedener Mieter:

// Request consent for cross-tenant access
const token = await workloadClient.auth.acquireAccessToken({
  additionalScopesToConsent: ['https://api.partner-app.com/data.read']
});

Fehlerbehandlung

Häufige Fehlerszenarien

async function robustTokenAcquisition() {
  try {
    return await workloadClient.auth.acquireAccessToken();
  } catch (error) {
    switch (error.code) {
      case 'user_cancelled':
        console.log('User cancelled the consent dialog');
        break;
      case 'consent_required':
        console.log('Additional consent required');
        break;
      case 'interaction_required':
        console.log('User interaction required');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
    throw error;
  }
}

Token-Ablaufhandhabung

class TokenManager {
  private currentToken: AccessToken | null = null;
  
  async getValidToken(): Promise<AccessToken> {
    if (!this.currentToken || this.isTokenExpired(this.currentToken)) {
      this.currentToken = await workloadClient.auth.acquireAccessToken();
    }
    return this.currentToken;
  }
  
  private isTokenExpired(token: AccessToken): boolean {
    // Add buffer time to prevent requests with almost-expired tokens
    const bufferMinutes = 5;
    const expirationWithBuffer = new Date(token.expiresOn.getTime() - (bufferMinutes * 60 * 1000));
    return new Date() >= expirationWithBuffer;
  }
}

Bewährte Methoden

Token-Caching und Wiederverwendung

• Cache-Token: Speichern Token bis zum Ablauf im Speicher
• Automatische Aktualisierung: Automatische Token-Aktualisierung vor Ablauf implementieren
• Sichere Speicherung: Niemals Token für lokale Speicher oder Cookies erhalten

Geltungsbereichsverwaltung

• Minimale Scopes: Fordern Sie nur die Berechtigungen an, die Sie benötigen
• Progressive Zustimmung: Zusätzliche Scopes anfordern, sobald Funktionen verwendet werden
• Scope-Validierung: Überprüfen Sie, ob Token vor API-Aufrufen erforderliche Scopes enthalten

Erweiterte Fehlerbehandlung

• Graceful Degradation: Bereitstellung von Notfall-Funktionalität, wenn die Authentifizierung fehlschlägt
• Benutzernachrichten: Erklären Sie klar, warum Berechtigungen benötigt werden
• Wiederholungslogik: Implementieren geeigneter Wiederholungsmechanismen für vorübergehende Fehler

Leistungsoptimierung

• Parallele Anfragen: Erwerben Sie Token für mehrere Dienste parallel, wenn möglich,
• Batch-Operationen: Gruppen-API-Aufrufe zur Minimierung des Token-Akquisitions-Overheads
• Cache-Management: Effiziente Token-Caching-Strategien implementieren

Verwandte Inhalte

• Schneller Start: Microsoft Entra Token erwerben – Ein einfacher Einstiegsleitfaden
• Authentifizierungsübersicht – Konzepte der hochrangigen Authentifizierung
• Authentifizierungsrichtlinien – Best Practices und Empfehlungen
• Access Fabric APIs – Vorgefertigte API-Wrapper