Udostępnij przez

Wytyczne dotyczące uwierzytelniania dla zestawu narzędzi Microsoft Fabric Extensibility Toolkit

Ten artykuł zawiera wskazówki dotyczące pracy z uwierzytelnianiem w trakcie tworzenia obciążeń zestawu narzędzi rozszerzalności Microsoft Fabric. Zawiera informacje dotyczące pracy z tokenami, uzyskiwania zgody i dostępu do różnych usług z aplikacji frontendowej.

Przed rozpoczęciem upewnij się, że znasz pojęcia w temacie Omówienie uwierzytelniania.

Model uwierzytelniania tylko front-endowego

Zestaw narzędzi rozszerzalności używa architektury wyłącznie frontendowej, która upraszcza uwierzytelnianie w porównaniu z tradycyjnymi obciążeniami.

  • Bezpośrednie wywołania interfejsu API: Frontend bezpośrednio wywołuje interfejsy API Fabric, usługi platformy Azure i aplikacje zewnętrzne
  • Ponowne użycie tokenu: pojedynczy token może służyć do uwierzytelniania w wielu usługach zabezpieczonych przez firmę Entra
  • Uproszczona zgoda: zarządzanie zgodą jest obsługiwane przez platformę z automatycznym monitowaniem

Konfiguracja aplikacji Microsoft Entra

Wyświetl kartę interfejsu API

Skonfiguruj zakresy dla aplikacji roboczej:

  • Zakresy integracji sieci szkieletowej: wstępne uwierzytelnianie usługi Microsoft Power BI przy użyciu identyfikatora aplikacji 871c010f-5e61-4fb1-83ac-98610a7e9110
  • Niestandardowe zakresy interfejsu API: Dodawanie zakresów dla dowolnych niestandardowych interfejsów API uwidacznianych w ramach pracy obciążeniowej
  • Szczegółowe uprawnienia: używanie różnych zakresów dla operacji odczytu i zapisu

Jeśli na przykład obciążenie udostępnia interfejsy API danych,

  • Dodawanie data.read zakresu operacji odczytu
  • Dodaj data.write zakres dla operacji zapisu
  • Weryfikowanie odpowiednich zakresów w programach obsługi interfejsu API

Karta Uprawnień interfejsu API

Skonfiguruj uprawnienia dla usług zewnętrznych, do których twoje obciążenie musi uzyskać dostęp:

  • Wymagane: Fabric.Extend w obszarze Usługa Power BI (obowiązkowe dla integracji z usługą Fabric)
  • Usługi platformy Azure: Dodawanie zakresów dla usług platformy Azure, takich jak https://storage.azure.com/user_impersonation
  • Aplikacje niestandardowe: dodawanie zakresów dla własnych aplikacji zabezpieczonych przez usługę Entra
  • Usługi innych firm: uwzględnij wszystkie usługi zewnętrzne, które obsługują uwierzytelnianie Entra

Wzorce użycia tokenów

Używanie tokenów dla wielu usług

Token frontendowy uzyskany za pomocą Extensibility Toolkit może służyć do uwierzytelniania względem:

Interfejsy API sieci szkieletowej

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

Usługi platformy Azure

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

Aplikacje niestandardowe

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

Zarządzanie zakresami

Zestaw narzędzi Extensibility Toolkit abstrahuje zarządzanie zakresem w typowych scenariuszach.

  • Biblioteki klienta Fabric: automatycznie uwzględnij wymagane zakresy Fabric
  • Biblioteki klienckie platformy Azure: przezroczyste obsługa zakresów usług platformy Azure
  • Zakresy niestandardowe: określ dodatkowe zakresy w razie potrzeby

Praca z zgodyami

Początkowe pozyskiwanie tokenów

Zacznij od uzyskania tokenu w celu ustanowienia kontekstu uwierzytelniania:

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

To wywołanie może spowodować:

  • Monit o wyrażenie zgody: jeśli użytkownik nie wyraził zgody na aplikację
  • Pozyskiwanie dyskretne: jeśli udzielono wcześniej zgody

Obsługa dodatkowego dostępu do usług

Jeśli obciążenie musi uzyskać dostęp do dodatkowych usług, określ wymagane zakresy:

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

Przykładowe scenariusze

Scenariusz 1. Uzyskiwanie dostępu do sieci szkieletowej i usług platformy Azure

Twoje obciążenie musi:

  • Lista przestrzeni roboczych Fabric
  • Odczyt z usługi Azure Storage
  • Zapisz do Azure Key Vault

Implementacja:

  1. Konfigurowanie uprawnień interfejsu API dla wymaganych usług
  2. Uzyskiwanie tokenu początkowego
  3. Użyj tokenu dla wszystkich wywołań usługi
  4. Obsługa monitów o wyrażenie zgody zgodnie z potrzebami

Scenariusz 2. Integracja aplikacji niestandardowych

Twoje obciążenie robocze integruje się z Twoją własną usługą backendową.

  1. Konfigurowanie zaplecza: Upewnij się, że akceptuje tokeny Entra
  2. Dodawanie uprawnień interfejsu API: uwzględnij zakresy uprawnień backendu w aplikacji roboczej
  3. Użyj uwierzytelniania standardowego: ten sam wzorzec tokenu działa dla usług niestandardowych

Scenariusz 3. Integracja usługi innej firmy

Integracja z zewnętrznymi usługami z obsługą Entra:

  1. Rejestracja usługi: rejestrowanie obciążenia w usłudze innej firmy
  2. Konfiguracja zakresu: Dodaj zakresy usługi do uprawnień interfejsu API
  3. Użycie tokenu: użyj tego samego wzorca uwierzytelniania dla usług zewnętrznych

Obsługa błędów i rozwiązywanie problemów

Typowe błędy uwierzytelniania

  • Wymagana zgoda: Użytkownik nie udzielił uprawnień dla określonego zakresu
  • Dostęp warunkowy: dodatkowe wymagania dotyczące uwierzytelniania (np. uwierzytelnianie wieloskładnikowe)
  • Wygaśnięcie tokenu: token wygasł i wymaga odświeżenia
  • Nieprawidłowy zakres: żądany zakres nie jest skonfigurowany lub dostępny

Wzorce obsługi błędów

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

Obsługa identyfikatora URI przekierowania

Zestaw narzędzi rozszerzalności zawiera wbudowaną obsługę identyfikatora URI przekierowania na potrzeby wyskakujących okienek zgody na uwierzytelnianie. Jest to implementowane w głównym index.ts pliku i automatycznie obsługuje przekierowania zgody.

Zestaw narzędzi obsługuje:

  • Automatyczne zamykanie okna: wyskakujące okienka zgody są zamykane automatycznie po interakcji użytkownika
  • Obsługa błędów: wykryto i odpowiednio obsłużono określone kody błędów
  • Wyświetlanie błędu: Nieudane próby zgody pokazują przyjazne dla użytkownika komunikaty o błędach

Bieżąca implementacja w zestawie narzędzi:

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

Uwaga / Notatka

Obsługa URI przekierowania jest automatycznie dołączana do szablonu zestawu narzędzi rozszerzalności. Nie musisz implementować tego samodzielnie, chyba że chcesz dostosować zachowanie obsługi błędów.

Najlepsze rozwiązania

Zarządzanie tokenami

  • Tokeny pamięci podręcznej: ponowne używanie tokenów do momentu ich wygaśnięcia
  • Obsługa odświeżania: implementowanie logiki automatycznego odświeżania tokenu
  • Bezpieczne przechowywanie: Bezpieczne przechowywanie tokenów w pamięci przeglądarki
  • Minimalne uprawnienia: żądaj tylko potrzebnych zakresów
  • Zgoda progresywna: żądanie dodatkowych uprawnień w miarę użycia funkcji
  • Przejrzyste komunikaty: wyjaśnij użytkownikom, dlaczego są potrzebne uprawnienia

Obsługa błędów

  • Łagodne obniżenie poziomu: zapewnij funkcjonalność rezerwową, gdy jest to możliwe
  • Opinie użytkowników: Jasno komunikuj wymagania dotyczące uwierzytelniania
  • Logika ponawiania prób: Zaimplementuj odpowiednie mechanizmy ponawiania dla błędów przejściowych

Treści powiązane

  • Last updated on