Αναφορά API JavaScript ελέγχου ταυτότητας

Το Κιτ εργαλείων επεκτασιμότητας Fabric παρέχει ένα JavaScript API για την απόκτηση διακριτικών ελέγχου ταυτότητας που μπορούν να χρησιμοποιηθούν για πρόσβαση σε API Fabric, υπηρεσίες Azure και οποιαδήποτε εφαρμογή με ασφάλεια Entra. Αυτό το άρθρο παρέχει ολοκληρωμένη αναφορά API και παραδείγματα χρήσης.

Αναφορά API

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

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

Το API επιστρέφει ένα AccessToken αντικείμενο που περιέχει:

• token: Η συμβολοσειρά token JWT που θα χρησιμοποιείται στις κεφαλίδες εξουσιοδότησης

Βασική χρήση

Απλή απόκτηση διακριτικών

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

Διακριτικό με συγκεκριμένα πεδία

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

Παραδείγματα χρήσης διακριτικού

Πρόσβαση στο API Fabric

Το διακριτικό μπορεί να χρησιμοποιηθεί απευθείας με Fabric REST API:

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

Χρησιμοποιήστε εμβέλειες για να καθορίσετε τις υπηρεσίες Azure στις οποίες χρειάζεστε πρόσβαση:

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

Προσαρμοσμένη πρόσβαση σε εφαρμογές

Αποκτήστε πρόσβαση στις δικές σας εφαρμογές με ασφάλεια 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();
}

Αναφορά παραμέτρου

Εμβέλειες

Ένας πίνακας συμβολοσειρών εύρους που καθορίζουν τα δικαιώματα που χρειάζεται το διακριτικό σας.

Κοινά πεδία υπηρεσίας Azure:

• https://storage.azure.com/user_impersonation - Χώρος αποθήκευσης Azure
• https://vault.azure.net/user_impersonation - Azure Key Vault
• https://management.azure.com/user_impersonation - Διαχείριση πόρων Azure
• https://graph.microsoft.com/User.Read - Γράφημα της Microsoft

Παράδειγμα χρήσης:

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

Πίνακας κενών πεδίων: Χρησιμοποιήστε έναν κενό πίνακα για να λάβετε ένα διακριτικό με προεπιλεγμένα δικαιώματα Fabric:

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

Διαχείριση συγκατάθεσης

Αυτόματη ροή συναίνεσης

Το Κιτ εργαλείων επεκτασιμότητας χειρίζεται αυτόματα τις ροές εργασιών συναίνεσης:

• Αρχικό αίτημα: Εάν λείπει η συγκατάθεση, ανοίγει ένα αναδυόμενο παράθυρο
• Αλληλεπίδραση χρήστη: Ο χρήστης εκχωρεί ή απορρίπτει δικαιώματα
• Αυτόματο κλείσιμο: Το αναδυόμενο παράθυρο κλείνει αυτόματα μετά από ενέργεια του χρήστη
• Παράδοση διακριτικού: Εάν είναι επιτυχής, το διακριτικό επιστρέφεται στην εφαρμογή σας

Χειρισμός αναδυόμενων παραθύρων συναίνεσης

Η εργαλειοθήκη διαχειρίζεται αυτόματα τα αναδυόμενα παράθυρα συναίνεσης, αλλά μπορείτε να προσαρμόσετε τη συμπεριφορά URI ανακατεύθυνσης. Δημιουργήστε μια σελίδα ανακατεύθυνσης που χειρίζεται την απόκριση συναίνεσης:

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

Συγκατάθεση μεταξύ μισθωτών

Για πρόσβαση σε πόρους σε διαφορετικούς μισθωτές:

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

Χειρισμός σφαλμάτων

Συνήθη σενάρια σφαλμάτων

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

Χειρισμός λήξης διακριτικού

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

Βέλτιστες πρακτικές

Προσωρινή αποθήκευση και επαναχρησιμοποίηση διακριτικών

• Διακριτικά προσωρινής μνήμης: Αποθηκεύστε τα διακριτικά στη μνήμη μέχρι τη λήξη
• Αυτόματη ανανέωση: Εφαρμογή αυτόματης ανανέωσης διακριτικού πριν από τη λήξη
• Ασφαλής αποθήκευση: Ποτέ μην διατηρείτε διακριτικά στον τοπικό χώρο αποθήκευσης ή στα cookies

Διαχείριση πεδίου εφαρμογής

• Ελάχιστο εύρος: Ζητήστε μόνο τα δικαιώματα που χρειάζεστε
• Προοδευτική συγκατάθεση: Ζητήστε πρόσθετα εύρη καθώς χρησιμοποιούνται λειτουργίες
• Επικύρωση εύρους: Επαληθεύστε ότι τα διακριτικά περιλαμβάνουν τα απαιτούμενα πεδία πριν από τις κλήσεις API

Προηγμένος χειρισμός σφαλμάτων

• Χαριτωμένη υποβάθμιση: Παρέχετε εφεδρική λειτουργικότητα όταν αποτυγχάνει ο έλεγχος ταυτότητας
• Μηνύματα χρήστη: Εξηγήστε με σαφήνεια γιατί χρειάζονται δικαιώματα
• Λογική επανάληψης: Εφαρμόστε κατάλληλους μηχανισμούς επανάληψης για παροδικές αποτυχίες

Βελτιστοποίηση επιδόσεων

• Παράλληλα αιτήματα: Αποκτήστε διακριτικά για πολλές υπηρεσίες παράλληλα, όταν είναι δυνατόν
• Λειτουργίες παρτίδας: Ομαδοποιήστε κλήσεις API για να ελαχιστοποιήσετε τα γενικά έξοδα απόκτησης διακριτικών
• Διαχείριση προσωρινής μνήμης: Εφαρμόστε αποτελεσματικές στρατηγικές προσωρινής αποθήκευσης διακριτικών

Σχετικό περιεχόμενο

• Γρήγορη εκκίνηση: Απόκτηση διακριτικών Microsoft Entra - Απλός οδηγός γρήγορων αποτελεσμάτων
• Επισκόπηση ελέγχου ταυτότητας - Έννοιες ελέγχου ταυτότητας υψηλού επιπέδου
• Οδηγίες ελέγχου ταυτότητας - Βέλτιστες πρακτικές και προτάσεις
• Access Fabric API - Προκατασκευασμένα περιτυλίγματα API