Delen via

Authenticatie JavaScript API-referentie

De Fabric Extensibility Toolkit biedt een JavaScript-API voor het verkrijgen van authenticatietokens die kunnen worden gebruikt om toegang te krijgen tot Fabric API's, Azure-diensten en elke door Entra-beveiligde applicatie. Dit artikel biedt uitgebreide API-referenties en gebruiksvoorbeelden.

Aanbeveling

Voor een snelle startgids, zie Microsoft Entra tokens verwerven.

API-referentie

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

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

Opmerking

De huidige implementatie van de uitbreidbaarheidstoolkit ondersteunt basis tokenacquisitie met scopes. Geavanceerde functies zoals volledige toestemming en voorwaardelijke toegang zijn nog niet beschikbaar, maar kunnen in toekomstige releases worden toegevoegd.

De API geeft een AccessToken object terug dat bevat:

  • token: De JWT-tokenstring om te gebruiken in autorisatieheaders

Basaal gebruik

Eenvoudige tokenverwerving

// 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 met specifieke scopes

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

Voorbeelden van tokengebruik

Fabric API-toegang

De token kan direct worden gebruikt met Fabric REST API's:

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

Gebruik scopes om de Azure-services aan te geven waar je toegang toe nodig hebt:

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

Toegang tot aangepaste applicaties

Toegang tot uw eigen door Entra beveiligde applicaties:

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

Parameterreferentie

reikwijdtes

Een array van scope-strings die specificeren welke rechten je token nodig heeft.

Veelvoorkomende 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

Gebruiksvoorbeeld:

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

Lege scopes-array: Gebruik een lege array om een token te krijgen met standaard Fabric-rechten:

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

De Extensibility Toolkit verwerkt automatisch toestemmingsworkflows:

  • Eerste aanvraag: Als toestemming ontbreekt, opent er een pop-up venster
  • Gebruikersinteractie: Gebruiker verleent of weigert rechten
  • Automatische sluiting: Popup sluit automatisch na actie van de gebruiker
  • Tokenlevering: Als het lukt, wordt de token teruggestuurd naar je applicatie

De toolkit beheert automatisch toestemmingspop-ups, maar je kunt het redirect-URI-gedrag aanpassen. Maak een redirectpagina aan die de toestemmingsreactie 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();
}

Voor toegang tot bronnen over verschillende tenants:

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

Foutafhandeling

Veelvoorkomende foutscenario's

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-vervalbehandeling

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

Beste praktijken

Tokencaching en hergebruik

  • Cachetokens: Sla tokens op in het geheugen tot ze verlopen
  • Automatische verversing: Voer automatische tokenverversing uit vóór vervaldatum
  • Veilige opslag: Behoud nooit tokens naar lokale opslag of cookies

Bereikbeheer

  • Minimale scopes: Vraag alleen de rechten aan die je nodig hebt
  • Progressieve toestemming: Vraag extra scopes aan naarmate functies worden gebruikt
  • Scopevalidatie: Controleer of tokens de vereiste scopes bevatten vóór API-aanroepen

Geavanceerde foutafhandeling

  • Graceful degradation: Bied een back-functionaliteit wanneer authenticatie faalt
  • Gebruikersberichten: Leg duidelijk uit waarom permissies nodig zijn
  • Herkansingslogica: Implementeer geschikte herkansingsmechanismen voor tijdelijke mislukkingen

Optimalisatie van prestaties

  • Parallelle verzoeken: Verkrijg tokens voor meerdere diensten parallel wanneer mogelijk
  • Batchbewerkingen: Groeperen API-aanroepen om tokenoverhead te minimaliseren
  • Cachebeheer: Implementeer efficiënte tokencachingstrategieën

Verwante inhoud

  • Last updated on