Del via

Autentificering JavaScript API-reference

Fabric Extensibility Toolkit tilbyder et JavaScript-API til at erhverve autentificeringstokens, som kan bruges til at få adgang til Fabric API'er, Azure-tjenester og enhver Entra-sikret applikation. Denne artikel giver omfattende referencer til API'er og brugseksempler.

Tips

For en hurtig startguide, se Erhverv Microsoft Entra-tokens.

API-reference

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

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

Notat

Den nuværende implementering af udvidelsesværktøjssættet understøtter grundlæggende token-anskaffelse med scopes. Avancerede funktioner som fuld samtykke-prompt og håndtering af betinget adgang er endnu ikke tilgængelige, men kan blive tilføjet i fremtidige versioner.

API'et returnerer et AccessToken objekt, der indeholder:

  • token: JWT-tokenstrengen til brug i autorisationsheadere

Grundlæggende brug

Simpel token-erhvervelse

// 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 med specifikke scopes

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

Eksempler på tokenbrug

Fabric API-adgang

Tokenet kan bruges direkte med Fabric REST API'er:

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

Brug scopes til at specificere de Azure-tjenester, du har brug for adgang til:

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

Brugerdefineret applikationsadgang

Få adgang til dine egne Entra-sikrede applikationer:

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

Parametrereference

Områder

Et array af scope-strenge, der specificerer de tilladelser, dit token har brug for.

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

Brugseksempel:

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

Tomt scopes-array: Brug et tomt array til at få et token med standard Fabric-tilladelser:

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

Udvidelsesværktøjssættet håndterer automatisk samtykke-workflows:

  • Indledende anmodning: Hvis samtykke mangler, åbner et popup-vindue
  • Brugerinteraktion: Bruger giver eller nægter tilladelser
  • Automatisk lukning: Popup-vinduet lukker automatisk efter brugerens handling
  • Tokenlevering: Hvis det lykkes, returneres tokenet til din applikation

Værktøjskassen håndterer automatisk samtykkepopups, men du kan tilpasse redirect-URI-adfærden. Opret en omdirigeringsside, der håndterer samtykkesvaret:

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

For adgang til ressourcer på tværs af forskellige lejere:

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

Fejlhåndtering

Almindelige fejlscenarier

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-udløbshåndtering

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

Bedste praksis

Token-cache og genbrug

  • Cache-tokens: Gem tokens i hukommelsen indtil udløb
  • Automatisk opdatering: Implementér automatisk tokenopdatering før udløb
  • Sikker lagring: Persister aldrig tokens til lokal lagring eller cookies

Omfangsstyring

  • Minimale scopes: Anmod kun om de tilladelser, du har brug for
  • Progressiv samtykke: Anmod om yderligere teleskoper, efterhånden som funktioner bruges,
  • Scope-validering: Verificér tokens inkluderer nødvendige scopes før API-kald

Avanceret fejlhåndtering

  • Graceful degradation: Giv backup-funktionalitet, når autentificering fejler
  • Brugerbeskeder: Forklar tydeligt, hvorfor tilladelser er nødvendige
  • Gentagelseslogik: Implementér passende genprøvningsmekanismer for midlertidige fejl

Optimering af ydeevnen

  • Parallelle forespørgsler: Erhverv tokens for flere tjenester parallelt, når det er muligt
  • Batchoperationer: Grupper API-kald for at minimere tokenanskaffelsesoverhead
  • Cache-styring: Implementér effektive token-caching-strategier

Relateret indhold

  • Last updated on