Compartir a través de

Directrices de autenticación para el kit de herramientas de extensibilidad de Microsoft Fabric

En este artículo se proporcionan instrucciones sobre cómo trabajar con la autenticación al compilar cargas de trabajo del kit de herramientas de extensibilidad de Microsoft Fabric. Incluye información sobre cómo trabajar con tokens, consentimientos y acceder a varios servicios desde la aplicación de front-end.

Antes de empezar, asegúrese de que está familiarizado con los conceptos en Authentication overview.

Modelo de autenticación solo de front-end

El Kit de herramientas de extensibilidad usa una arquitectura de solo front-end que simplifica la autenticación en comparación con las cargas de trabajo tradicionales:

  • Llamadas de API directas: el front-end llama directamente a las API de Fabric, los servicios de Azure y las aplicaciones externas.
  • Reutilización de tokens: se puede usar un único token para autenticarse en varios servicios protegidos por Entra.
  • Consentimiento simplificado: la plataforma controla la administración del consentimiento con petición automática.

Configuración de la aplicación Microsoft Entra

Exponer una pestaña de API

Configure ámbitos para la aplicación de carga de trabajo:

  • Ámbitos de integración de Fabric: autenticación previa de Microsoft Power BI con el identificador de aplicación 871c010f-5e61-4fb1-83ac-98610a7e9110
  • Ámbitos de API personalizados: agregue ámbitos para las API personalizadas que expone la carga de trabajo.
  • Permisos pormenorizados: use distintos ámbitos para las operaciones de lectura y escritura.

Por ejemplo, si la carga de trabajo expone las API de datos:

  • Agregar data.read ámbito para las operaciones de lectura
  • Agregar data.write ámbito para las operaciones de escritura
  • Validación de los ámbitos adecuados en los controladores de API

Pestaña Permisos de API

Configure los permisos para los servicios externos a los que necesita acceder la carga de trabajo:

  • Obligatorio: Fabric.Extend en el servicio Power BI (obligatorio para la integración de Fabric)
  • Servicios de Azure: adición de ámbitos para servicios de Azure, como https://storage.azure.com/user_impersonation
  • Aplicaciones personalizadas: agregar ámbitos para sus propias aplicaciones protegidas por Entra
  • Servicios de terceros: incluya los servicios externos que admitan la autenticación entra.

Patrones de uso de tokens

Uso de tokens para varios servicios

El token de front-end adquirido a través del kit de herramientas de extensibilidad se puede usar para autenticarse en:

API de Fabric

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Servicios de Azure

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Aplicaciones personalizadas

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Administración de ámbitos

El Kit de herramientas de extensibilidad abstrae la administración del ámbito para escenarios comunes:

  • Bibliotecas cliente de Fabric: incluya automáticamente ámbitos de Fabric necesarios.
  • Bibliotecas de cliente de Azure: control de los ámbitos de servicio de Azure de forma transparente
  • Ámbitos personalizados: especifique ámbitos adicionales cuando sea necesario.

Trabajar con consentimientos

Adquisición inicial de tokens

Empiece por adquirir un token para establecer el contexto de autenticación:

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

Esta llamada puede dar lugar a:

  • Aviso de consentimiento: si el usuario no ha aceptado la aplicación
  • Adquisición silenciosa: si se concedió previamente el consentimiento

Control del acceso adicional al servicio

Cuando la carga de trabajo necesite acceder a servicios adicionales, especifique los ámbitos necesarios:

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

Escenarios de ejemplo

Escenario 1: Acceso a los servicios de Fabric y Azure

La carga de trabajo debe:

  • Enumerar áreas de trabajo de Fabric
  • Leer desde Azure Storage
  • Escribir en Azure Key Vault

Implementación:

  1. Configuración de permisos de API para los servicios necesarios
  2. Adquisición del token inicial
  3. Uso del token para todas las llamadas de servicio
  4. Manejar las solicitudes de consentimiento cuando sea necesario

Escenario 2: Integración de aplicaciones personalizadas

El flujo de trabajo se integra con tu propio servicio backend.

  1. Configuración del backend: Asegúrese de que acepta Entra tokens.
  2. Agregar permisos de API: incluya los ámbitos del back-end en la aplicación de tareas.
  3. Uso de la autenticación estándar: el mismo patrón de token funciona para los servicios personalizados.

Escenario 3: Integración de servicios de terceros

Integración con servicios externos habilitados para Entra:

  1. Registro del servicio: Registre su carga de trabajo con el servicio de terceros
  2. Configuración del ámbito: agregue los ámbitos del servicio a los permisos de API.
  3. Uso de tokens: use el mismo patrón de autenticación para servicios externos.

Control de errores y solución de problemas

Errores comunes de autenticación

  • Consentimiento necesario: el usuario no ha concedido permiso para un ámbito específico
  • Acceso condicional: requisitos de autenticación adicionales (por ejemplo, MFA)
  • Expiración del token: el token ha expirado y necesita actualización.
  • Ámbito no válido: el ámbito solicitado no está configurado ni disponible

Patrones de control de errores

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

Manejo de URI de redirección

El kit de herramientas de extensibilidad incluye la gestión de URI de redirección integrada para ventanas emergentes de consentimiento para autenticación. Esto se implementa en el archivo principal index.ts y controla los redireccionamientos de consentimiento automáticamente.

El kit de herramientas controla:

  • Cierre automático de ventanas: los elementos emergentes de consentimiento se cierran automáticamente después de la interacción del usuario
  • Control de errores: se detectan códigos de error específicos y se controlan adecuadamente.
  • Visualización de errores: los intentos de consentimiento con errores muestran mensajes de error amigables

Implementación actual en el kit de herramientas:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

Nota:

El control de URI de redirección se incluye automáticamente en la plantilla del kit de herramientas de extensibilidad. No es necesario implementar esto usted mismo a menos que quiera personalizar el comportamiento de control de errores.

procedimientos recomendados

Administración de tokens

  • Tokens de caché: reutilización de tokens hasta que expiren
  • Control de la actualización: implementación de la lógica de actualización automática de tokens
  • Almacenamiento seguro: almacenar tokens de forma segura en la memoria del explorador
  • Permisos mínimos: solicite solo los ámbitos que realmente necesita.
  • Consentimiento progresivo: solicitar permisos adicionales a medida que se usan características
  • Borrar mensajería: explicar a los usuarios por qué se necesitan permisos

Control de errores

  • Degradación elegante: proporcione una funcionalidad de respaldo siempre que sea posible.
  • Comentarios del usuario: Comunicar claramente los requisitos de autenticación
  • Lógica de reintento: Implementar mecanismos de reintento apropiados para fallos transitorios

Contenido relacionado

  • Last updated on