Uwierzytelnianie API JavaScript referencyjne

Narzędzie Fabric Extensibility Toolkit udostępnia API JavaScript do pozyskiwania tokenów uwierzytelniających, które można wykorzystać do dostępu do API Fabric, usług Azure oraz dowolnej aplikacji zabezpieczonej przez Entra. Ten artykuł zawiera kompleksowe przykłady odniesienia i użycia API.

Odniesienie do API

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

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

API zwraca AccessToken obiekt zawierający następujące elementy:

• token: Ciąg tokenów JWT do użycia w nagłówkach autoryzacji

Podstawowy sposób użycia

Proste pozyskiwanie tokenów

// 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 z określonymi zakresami

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

Przykłady użycia tokenów

Dostęp do API Fabric

Token może być używany bezpośrednio z API Fabric REST:

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

Użyj zakresów, aby określić usługi Azure, do których potrzebujesz dostępu:

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

Dostęp do aplikacji niestandardowych

Uzyskaj dostęp do własnych aplikacji zabezpieczonych przez Entra:

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

Dokumentacja parametrów

zakresy

Tablica łańcuchów zakresu, które określają uprawnienia, których wymaga twój token.

Common 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

Przykład użycia:

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

Tablica pustych zakresów: Użyj pustej tablicy, aby uzyskać token z domyślnymi uprawnieniami Fabric:

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

Zarządzanie zgodą

Automatyczny przepływ zgody

Zestaw narzędzi rozszerzalności automatycznie obsługuje procesy związane z wyrażaniem zgody:

• Początkowa prośba: Jeśli brakuje zgody, otwiera się okno wyskakujące
• Interakcja z użytkownikiem: Użytkownik udziela lub odmawia uprawnień
• Automatyczne zamykanie: Popup zamyka się automatycznie po akcji użytkownika
• Dostarczenie tokenów: Jeśli się powiedzie, token wraca do Twojej aplikacji

Obsługa wyskakujących okienek zgody

Zestaw narzędzi automatycznie zarządza wyskakującymi oknami zgody, ale można dostosować zachowanie URI przekierowania. Stwórz stronę przekierowania, która obsługuje odpowiedź na zgodę:

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

Zgoda między najemcami

Do dostępu do zasobów między różnymi tenantami:

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

Obsługa błędów

Typowe scenariusze błędów

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

Obsługa wygaśnięcia tokenów

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

Najlepsze rozwiązania

Bufor i ponowne wykorzystanie tokenów

• Tokeny pamięci podręcznej: Przechowują tokeny w pamięci do czasu wygaśnięcia
• Automatyczne odświeżanie: Wprowadź automatyczne odświeżanie tokenów przed wygaśnięciem
• Bezpieczne przechowywanie: Nigdy nie utrwalaj tokenów na lokalnej pamięci ani na pliki cookie

Zarządzanie zakresami

• Minimalne zakresy: Żądaj tylko tych uprawnień, których potrzebujesz
• Zgoda progresywna: Prośba o dodatkowe zakresy w miarę korzystania z funkcji
• Walidacja zakresu: Weryfikacja tokenów zawiera wymagane zakresy przed wywołaniami API

Zaawansowana obsługa błędów

• Degradacja z ładną jakością: Zapewnienie funkcji awaryjnej w przypadku awarii uwierzytelniania
• Wiadomości użytkownika: Jasno wyjaśnij, dlaczego potrzebne są uprawnienia
• Logika ponawiania prób: Zaimplementuj odpowiednie mechanizmy ponawiania dla błędów przejściowych

Optymalizacja wydajności

• Żądania równoległe: Pobieraj tokeny dla wielu usług równolegle, gdy to możliwe
• Operacje wsadowe: Grupowe wywołania API w celu minimalizacji narzutu pozyskiwania tokenów
• Zarządzanie pamięcią podręczną: Wdrażanie efektywnych strategii buforowania tokenów

Treści powiązane

• Szybki początek: Zdobycie tokenów Microsoft Entra – prosty przewodnik po rozpoczęciu
• Przegląd uwierzytelniania - Koncepcje uwierzytelniania wysokiego poziomu
• Wytyczne dotyczące uwierzytelniania – najlepsze praktyki i zalecenia
• API Access Fabric - Gotowe opakowania API