Visão geral das diretrizes de autenticação de carga de trabalho no Microsoft Fabric

Este artigo fornece diretrizes sobre como trabalhar com autenticação quando você está criando cargas de trabalho do Microsoft Fabric. Inclui informações sobre como trabalhar com tokens e consentimentos.

Antes de começar, certifique-se de que está familiarizado com os conceitos em Visão Geral da Autenticação e Configuração da Autenticação.

Data plane and control plane APIs

• Data plane APIs are APIs that the workload backend exposes. The workload frontend can call them directly. For data plane APIs, the workload backend can decide on what APIs to expose.

• Control plane APIs are APIs that go through Fabric. O processo começa com o front-end da carga de trabalho chamando uma API JavaScript e termina com o Fabric chamando o back-end da carga de trabalho. Um exemplo dessa API é Create Item.

  For control plane APIs, the workload must follow the contracts defined in the workload backend and implement those APIs.

Expose an API tab on the workload's application in Microsoft Entra ID

On the Expose an API tab, you need to add scopes for control plane APIs and scopes for data plane APIs:

• The scopes added for control plane APIs should preauthorize the Fabric Client for Workloads application with application ID d2450708-699c-41e3-8077-b0c8341509aa. Those scopes are included in the token that the workload backend receives when Fabric calls it.

  You need to add at least one scope for the control plane API for the flow to work.

• The scopes added for data plane APIs should preauthorize Microsoft Power BI with application ID 871c010f-5e61-4fb1-83ac-98610a7e9110. Eles estão incluídos no token que a API JavaScript acquireAccessToken retorna.

  Para APIs de plano de dados, você pode usar essa guia para gerenciar permissões granulares para cada API que sua carga de trabalho expõe. Idealmente, você deve adicionar um conjunto de escopos para cada API que o back-end da carga de trabalho expõe e validar se o token recebido inclui esses escopos quando essas APIs são chamadas do cliente. Por exemplo:

  • A carga de trabalho expõe duas APIs para o cliente, ReadData e WriteData.
  • A carga de trabalho expõe dois escopos de plano de dados, data.read e data.write.
  • In the ReadData API, the workload validates that the data.read scope is included in the token before it continues with the flow. O mesmo se aplica a WriteData.

API permissions tab on the workload's application in Microsoft Entra ID

On the API permissions tab, you need to add all the scopes that your workload needs to exchange a token for. A mandatory scope to add is Fabric.Extend under the Power BI service. Requests to Fabric might fail without this scope.

Working with tokens and consents

When you're working with data plane APIs, the workload frontend needs to acquire a token for calls to the workload backend.

The following sections describe how the workload frontend should use the JavaScript API and on-behalf-of (OBO) flows to acquire tokens for the workload and external services, and to work with consents.

Etapa 1: Adquira um token

A carga de trabalho começa com a solicitação de um token usando a API JavaScript sem fornecer parâmetros. Essa chamada pode resultar em dois cenários:

• The user sees a consent window of all the static dependencies (what's configured on the API permissions tab) that the workload configured. Este cenário ocorre se o utilizador não pertencer ao inquilino de origem da aplicação e não tiver concedido consentimento ao Microsoft Graph para esta aplicação anteriormente.

• O usuário não vê uma janela de consentimento. This scenario happens if the user already consented at least once to Microsoft Graph for this application, or if the user is a part of the application's home tenant.

In both scenarios, the workload shouldn't care whether or not the user gave full consent for all of the dependencies (and can't know at this point). The received token has the workload backend audience and can be used to directly call the workload backend from the workload frontend.

Passo 2: Tente aceder a serviços externos

A carga de trabalho pode precisar acessar serviços que exigem autenticação. Para ter esse acesso, precisa realizar o fluxo OBO, em que troca o token que recebeu do seu cliente ou do Fabric por outro serviço. A troca de token pode falhar devido à falta de consentimento ou a alguma política de Acesso Condicional do Microsoft Entra configurada no recurso pelo qual a carga de trabalho está tentando trocar o token.

To solve this problem, it's the workload's responsibility to propagate the error to the client when working with direct calls between the frontend and the backend. It's also the workload's responsibility to propagate the error to the client when working with calls from Fabric by using the error propagation described in Workload communication.

Depois que a carga de trabalho propaga o erro, ela pode chamar a API JavaScript acquireAccessToken para resolver o problema da política de consentimento ou Acesso Condicional e tentar novamente a operação.

For data plane API failures, see Handling multifactor authentication, Conditional Access, and incremental consent. For control plane API failures, see Workload communication.

Cenários de exemplo

Vamos dar uma olhada em uma carga de trabalho que precisa acessar três APIs de malha:

• List workspaces: GET https://api.fabric.microsoft.com/v1/workspaces

• Create a warehouse: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Write to a lakehouse file: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

To be able to work with those APIs, the workload backend needs to exchange tokens for the following scopes:

• Para listar espaços de trabalho: https://analysis.windows.net/powerbi/api/Workspace.Read.All ou https://analysis.windows.net/powerbi/api/Workspace.ReadWrite.All
• Para criar um armazém: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All ou https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
• For writing to a lakehouse file: https://storage.azure.com/user_impersonation

The scopes mentioned earlier need to be configured on the workload application under API permissions.

Vamos analisar exemplos de cenários que a carga de trabalho pode possivelmente enfrentar.

Example 1

Vamos supor que o back-end da carga de trabalho tenha uma API de plano de dados que obtém os espaços de trabalho do usuário e os retorna ao cliente:

1. O frontend de carga de trabalho solicita um token usando a API JavaScript.

2. The workload frontend calls the workload backend API to get the workspaces of the user and attaches the token in the request.

3. The workload backend validates the token and tries to exchange it for the required scope (let's say https://analysis.windows.net/powerbi/api/Workspace.Read.All).

4. A carga de trabalho falha ao trocar o token para o recurso especificado porque o usuário não consentiu que o aplicativo acessasse esse recurso (consulte códigos de erro do AADSTS).

5. O back-end da carga de trabalho propaga o erro para o front-end da carga de trabalho especificando que ele precisa de consentimento para esse recurso. The workload frontend calls the acquireAccessToken JavaScript API and provides additionalScopesToConsent:

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

   Como alternativa, a carga de trabalho pode decidir pedir consentimento para todas as suas dependências estáticas configuradas em seu aplicativo, por isso chama a API JavaScript e fornece promptFullConsent:

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

This call prompts a consent window regardless of whether or not the user has consented to some of the dependencies. After that, the workload frontend can retry the operation.

Example 2

Let's assume that the workload backend needs to access OneLake on the Create Item API (call from Fabric to the workload):

1. O frontend da carga de trabalho chama a API JavaScript "Create Item".

2. The workload backend receives a call from Fabric and extracts the delegated token and validates it.

3. The workload tries to exchange the token for https://storage.azure.com/user_impersonation but fails because the tenant administrator of the user-configured multifactor authentication needed to access Azure Storage (see AADSTS error codes).

4. The workload propagates the error alongside the claims returned in the error from Microsoft Entra ID to the client by using the error propagation described in Workload communication.

5. The workload frontend calls the acquireAccessToken JavaScript API and provides claims as claimsForConditionalAccessPolicy, where claims refers to the claims propagated from the workload backend:

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

After that, the workload can retry the operation.

Handling errors when requesting consents

Às vezes, o usuário não pode conceder consentimento devido a vários erros. Após uma solicitação de consentimento, a resposta é retornada para o URI de redirecionamento. No nosso exemplo, este código é responsável por lidar com a resposta. (Você pode encontrá-lo no arquivo 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(); 
} 

O frontend da carga de trabalho pode extrair o código de erro da URL e manipulá-lo adequadamente.