Riferimento API JavaScript di autenticazione

Il Fabric Extensibility Toolkit fornisce un'API JavaScript per acquisire token di autenticazione che possono essere utilizzati per accedere alle API Fabric, ai servizi Azure e a qualsiasi applicazione protetta da Entra. Questo articolo fornisce esempi completi di riferimento e utilizzo delle API.

Suggerimento

Per una guida iniziale rapida, consulta Acquisisci i token Microsoft Entra.

Informazioni di riferimento sulle API

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

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

Annotazioni

L'attuale implementazione del toolkit di estensibilità supporta l'acquisizione di token di base con ambitivi. Funzionalità avanzate come il consenso completo e la gestione dell'accesso condizionato non sono ancora disponibili, ma potrebbero essere aggiunte in future versioni.

L'API restituisce un AccessToken oggetto che contiene:

  • token: La stringa di token JWT da utilizzare nelle intestazioni di autorizzazione

Utilizzo di base

Semplice acquisizione dei token

// 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 con telescopi specifici

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

Esempi di utilizzo dei token

Accesso API Fabric

Il token può essere utilizzato direttamente con le 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

Usa gli scope per specificare i servizi Azure a cui hai bisogno di accesso:

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

Accesso alle applicazioni personalizzate

Accedi alle tue applicazioni protette da 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();
}

Riferimento ai parametri

scopes

Una serie di stringhe di scope che specificano i permessi di cui il tuo token ha bisogno.

Ambiti di servizio Azure comuni:

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

Esempio di utilizzo:

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

Matrice di scope vuoti: Usa un array vuoto per ottenere un token con i permessi Fabric predefiniti:

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

L'Extensibility Toolkit gestisce automaticamente i flussi di lavoro di consenso:

  • Richiesta iniziale: Se manca il consenso, si apre una finestra pop-up
  • Interazione dell'utente: l'utente concede o nega permessi
  • Chiusura automatica: il popup si chiude automaticamente dopo l'azione dell'utente
  • Consegna del token: Se ha successo, il token viene restituito alla tua applicazione

Il toolkit gestisce automaticamente i pop-up di consenso, ma puoi personalizzare il comportamento dell'URI di reindirizzamento. Crea una pagina di reindirizzamento che gestisca la risposta di consenso:

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

Per accedere alle risorse tra diversi tenant:

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

Gestione degli errori

Scenari di errore comuni

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

Gestione della scadenza dei token

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

Procedure consigliate

Cache e riutilizzo dei token

  • Token cache: Conservare i token in memoria fino alla scadenza
  • Aggiornamento automatico: implementare l'aggiornamento automatico del token prima della scadenza
  • Archiviazione sicura: Non far mai persistere i token nello storage locale o nei cookie

Gestione dell'ambito

  • Ambiti minimi: richiedi solo i permessi necessari
  • Consenso progressivo: richiedere ulteriori ambiti man mano che vengono utilizzate funzionalità
  • Validazione dell'ambito: I token di verifica includono gli scope richiesti prima delle chiamate API

Gestione avanzata degli errori

  • Degrado graduale: fornire funzionalità di riserva quando l'autenticazione fallisce
  • Messaggistica utente: Spiega chiaramente perché sono necessari i permessi
  • Logica dei ritenti: Implementare meccanismi di ritentazione appropriati per i fallimenti transitori.

Ottimizzazione delle prestazioni

  • Richieste parallele: acquisire token per più servizi in parallelo quando possibile
  • Operazioni batch: Chiamate API di gruppo per minimizzare il sovraccarico di acquisizione dei token
  • Gestione della cache: Implementare strategie efficienti di cache dei token

Contenuti correlati

  • Last updated on