Introducción a las directrices de autenticación de cargas de trabajo en Microsoft Fabric

En este artículo se proporcionan instrucciones sobre cómo trabajar con la autenticación al compilar cargas de trabajo de Microsoft Fabric. Incluye información sobre cómo trabajar con tokens y consentimientos.

Antes de empezar, asegúrese de que está familiarizado con los conceptos de Visión general de la autenticación y Configuración de autenticación.

API del plano de datos y del plano de control

• La API del plano de datos es la API que expone el backend de la carga de trabajo. El front-end de carga de trabajo puede llamarlos directamente. En el caso de las API del plano de datos, el back-end de carga de trabajo puede decidir qué API exponer.

• Las APIs del plano de control son APIs que pasan a través de Fabric. El proceso comienza con el front-end de carga de trabajo que llama a una API de JavaScript y termina con Fabric llamando al back-end de carga de trabajo. Un ejemplo de este tipo de API es Crear elemento.

  Para las API del plano de control, la carga de trabajo debe seguir los contratos definidos en el back-end de carga de trabajo e implementar esas API.

Exponer una pestaña de API en la aplicación del entorno de trabajo en Microsoft Entra ID

En la pestaña Exponer una API, debe agregar ámbitos para las API del plano de control y ámbitos para las API del plano de datos.

• Los ámbitos agregados para las API del plano de control deben autenticar previamente la aplicación Fabric Client for Workloads con el identificador de aplicación d2450708-699c-41e3-8077-b0c8341509aa. Esos ámbitos se incluyen en el token que recibe el backend de la carga de trabajo cuando Fabric lo llama.

  Debe agregar al menos un ámbito a la API del plano de control para que el flujo funcione correctamente.

• Los ámbitos agregados para las API del plano de datos deben autenticar previamente Microsoft Power BI con el identificador de aplicación 871c010f-5e61-4fb1-83ac-98610a7e9110. Se incluyen en el token que devuelve la API de JavaScript de acquireAccessToken.

  En el caso de las API del plano de datos, puede usar esta pestaña para administrar permisos pormenorizados para cada API que expone la carga de trabajo. Lo ideal es agregar un conjunto de ámbitos para cada API que expone el back-end de carga de trabajo y validar que el token recibido incluye esos ámbitos cuando se llama a esas API desde el cliente. Por ejemplo:

  • La carga de trabajo expone dos API al cliente, ReadData y WriteData.
  • La carga de trabajo expone dos ámbitos de planos de datos, data.read y data.write.
  • En la API de ReadData, la carga de trabajo valida que el ámbito de data.read se incluye en el token antes de continuar con el flujo. Lo mismo se aplica a WriteData.

Pestaña Permisos de API en la aplicación de carga de trabajo en Microsoft Entra ID

En la pestaña permisos de API, debe agregar todos los ámbitos para los que la carga de trabajo necesita intercambiar un token. Un ámbito obligatorio que se debe agregar es Fabric.Extend en el servicio Power BI. Es posible que las solicitudes a Fabric fallen sin este ámbito.

Trabajar con tokens y consentimientos

Cuando se trabaja con las API del plano de datos, el front-end de carga de trabajo debe adquirir un token para las llamadas al back-end de carga de trabajo.

En las secciones siguientes se describe cómo el front-end de carga de trabajo debe usar la API de JavaScript , y los flujos de representación (OBO) ,, a fin de adquirir tokens para la carga de trabajo y servicios externos, y para trabajar con consentimientos.

Paso 1: Adquisición de un token

La carga de trabajo comienza con la solicitud de un token mediante la API de JavaScript sin proporcionar ningún parámetro. Esta llamada puede dar lugar a dos escenarios:

• El usuario ve una ventana de consentimiento de todas las dependencias estáticas (lo que está configurado en la pestaña permisos de API de ) que configuró la carga de trabajo. Este escenario se produce si el usuario no forma parte del inquilino principal de la aplicación y el usuario no concedía consentimiento a Microsoft Graph para esta aplicación antes.

• El usuario no ve una ventana de consentimiento. Este escenario se produce si el usuario ha dado su consentimiento al menos una vez para Microsoft Graph en esta aplicación, o si el usuario forma parte del cliente principal de la aplicación.

En ambos escenarios, la carga de trabajo no debe importar si el usuario dio su consentimiento completo para todas las dependencias (y no puede conocer en este momento). El token recibido tiene la audiencia del backend de carga de trabajo y se puede usar para llamar directamente al backend de carga de trabajo desde el frontend de carga de trabajo.

Paso 2: Intentar acceder a servicios externos

Es posible que la carga de trabajo necesite acceder a los servicios que requieren autenticación. Para ese acceso, debe realizar el flujo de OBO, donde intercambia el token que recibió de su cliente o de Fabric hacia otro servicio. Es posible que se produzca un error en el intercambio de tokens debido a la falta de consentimiento o a alguna directiva de acceso condicional de Microsoft Entra configurada en el recurso para el que la carga de trabajo intenta intercambiar el token.

Para solucionar este problema, es responsabilidad de la carga de trabajo propagar el error al cliente al trabajar con llamadas directas entre el front-end y el back-end. También es responsabilidad de la carga de trabajo propagar el error al cliente al trabajar con llamadas desde Fabric mediante la propagación de errores descrita en comunicación de carga de trabajo.

Una vez que la carga de trabajo propaga el error, puede llamar a la API de JavaScript de acquireAccessToken para resolver el problema de consentimiento o de la directiva de acceso condicional y intentar nuevamente la operación.

Para ver los errores de la API del plano de datos, consulte Control de la autenticación multifactor, el acceso condicional y el consentimiento incremental. Para ver los errores de la API del plano de control, consulte comunicación de carga de trabajo.

Escenarios de ejemplo

Echemos un vistazo a una carga de trabajo que necesita acceder a tres API de Fabric:

• Listar áreas de trabajo: GET https://api.fabric.microsoft.com/v1/workspaces

• Creación de un almacén: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Escribir en un archivo de lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Para poder trabajar con esas API, el back-end de carga de trabajo debe intercambiar tokens para los ámbitos siguientes:

• Para enumerar áreas de trabajo: https://analysis.windows.net/powerbi/api/Workspace.Read.All o https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Para crear un almacén: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All o https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• Para escribir en un archivo lakehouse: https://storage.azure.com/user_impersonation

Nota:

Puede encontrar los alcances necesarios para cada API de Fabric en este artículo de referencia .

Los ámbitos mencionados anteriormente deben configurarse en la aplicación de carga de trabajo en permisos de API.

Echemos un vistazo a ejemplos de escenarios que la carga de trabajo podría encontrar.

Ejemplo 1

Supongamos que el back-end de carga de trabajo tiene una API de plano de datos que obtiene las áreas de trabajo del usuario y las devuelve al cliente:

1. El front-end de carga de trabajo solicita un token mediante la API de JavaScript.

2. El front-end de carga de trabajo llama a la API de back-end de carga de trabajo para obtener las áreas de trabajo del usuario y adjuntar el token en la solicitud.

3. El back-end de carga de trabajo valida el token e intenta intercambiarlo para el ámbito necesario (supongamos https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. La carga de trabajo no puede intercambiar el token del recurso especificado porque el usuario no consiente que la aplicación acceda a este recurso (consulte códigos de error de AADSTS).

5. El back-end de carga de trabajo propaga el error al front-end de carga de trabajo especificando que necesita consentimiento para ese recurso. El front-end de carga de trabajo llama a la API de JavaScript acquireAccessToken y proporciona additionalScopesToConsent:

   workloadClient.auth.acquireAccessToken({additionalScopesToConsent: ["https://analysis.windows.net/powerbi/api/Workspace.Read.All"]})

   Como alternativa, la carga de trabajo puede decidir pedir consentimiento para todas sus dependencias estáticas configuradas en su aplicación, por lo que llama a la API de JavaScript y proporciona promptFullConsent:

   workloadClient.auth.acquireAccessToken({promptFullConsent: true}).

Esta llamada solicita una ventana de consentimiento independientemente de si el usuario ha aceptado o no algunas de las dependencias. Después de eso, la interfaz de carga de trabajo puede reintentar la operación.

Nota:

Si el intercambio de tokens sigue produciendo un error de consentimiento, significa que el usuario no concedió el consentimiento. La carga de trabajo debe controlar estos escenarios; Por ejemplo, notifique al usuario que esta API requiere consentimiento y no funcionará sin ella.

Ejemplo 2

Supongamos que el sistema backend de carga de trabajo necesita acceder a OneLake en la API de Crear Elemento (llamada desde Fabric a la carga de trabajo):

1. El frontend de la carga de trabajo llama a la API de JavaScript Create Item.

2. El backend de carga de trabajo recibe una llamada de "Fabric" y extrae el token delegado y lo valida.

3. La carga de trabajo intenta intercambiar el token por https://storage.azure.com/user_impersonation, pero falla porque el administrador del tenant de la autenticación multifactor, configurada según las necesidades del usuario, es necesaria para acceder a Azure Storage (consulte códigos de error AADSTS).

4. La carga de trabajo propaga el error junto con las afirmaciones devueltas en el error de Microsoft Entra ID al cliente utilizando la propagación de errores descrita en Comunicación de carga de trabajo.

5. El frontend de la carga de trabajo llama a la API de JavaScript de acquireAccessToken y proporciona reclamaciones como claimsForConditionalAccessPolicy, donde claims hace referencia a las reclamaciones propagadas desde el backend de la carga de trabajo.

   workloadClient.auth.acquireAccessToken({claimsForConditionalAccessPolicy: claims})

Luego de eso, la carga de trabajo puede reintentar la operación.

Control de errores al solicitar consentimientos

A veces, el usuario no puede conceder consentimiento debido a varios errores. Después de una solicitud de consentimiento, la respuesta se devuelve al URI de redirección. En nuestro ejemplo, este código es responsable de controlar la respuesta. (Puede encontrarlo en el archivo index.ts).

const redirectUriPath = '/close'; 
const url = new URL(window.location.href); 
if (url.pathname?.startsWith(redirectUriPath)) { 
    // Handle errors, Please refer to https://learn.microsoft.com/entra/identity-platform/reference-error-codes 
    if (url?.hash?.includes("error")) { 
        // Handle missing service principal error 
        if (url.hash.includes("AADSTS650052")) { 
            printFormattedAADErrorMessage(url?.hash); 
        // handle user declined the consent error 
        } else  if (url.hash.includes("AADSTS65004")) { 
            printFormattedAADErrorMessage(url?.hash); 
        } 
    } 
    // Always close the window  
    window.close(); 
} 

El front-end de carga de trabajo puede extraer el código de error de la dirección URL y controlarlo en consecuencia.

Nota:

En ambos escenarios (error y éxito), la carga de trabajo debe cerrar siempre la ventana inmediatamente, sin demoras.