Condividi tramite

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