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.

APIs do plano de dados e do plano de controle

• APIs de plano de dados são APIs que o back-end de carga de trabalho expõe. O frontend da carga de trabalho pode chamá-los diretamente. Para APIs de plano de dados, o back-end de carga de trabalho pode decidir quais APIs expor.

• APIs do plano de controle são APIs que passam pela malha. 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.

  Para APIs de plano de controle, a carga de trabalho deve seguir os contratos definidos no back-end de carga de trabalho e implementar essas APIs.

Expor uma guia API no aplicativo da carga de trabalho no Microsoft Entra ID

Na aba Expor uma API, deve adicionar escopos para APIs do plano de controlo e escopos para APIs do plano de dados:

• Os escopos adicionados para APIs de plano de controle devem pré-autorizar o aplicativo Fabric Client for Workloads com ID de aplicativo d2450708-699c-41e3-8077-b0c8341509aa. Esses escopos são incluídos no token que o backend do sistema recebe quando o Fabric faz a chamada.

  Você precisa adicionar pelo menos um escopo para a API do plano de controle para que o fluxo funcione.

• Os escopos adicionados para APIs de plano de dados devem pré-autorizar o Microsoft Power BI com a ID do aplicativo 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.
  • Na API do ReadData, a carga de trabalho valida que o escopo data.read está incluído no token antes de continuar com o fluxo. O mesmo se aplica a WriteData.

Guia Permissões de API no aplicativo da carga de trabalho no Microsoft Entra ID

Na aba permissões da API, deve adicionar todos os âmbitos que a sua carga de trabalho precisa para trocar um token. Um escopo obrigatório a acrescentar é Fabric.Extend no serviço Power BI. As solicitações ao Fabric podem falhar sem esse escopo.

Trabalhar com tokens e consentimentos

Quando se está a trabalhar com APIs de plano de dados, o frontend de carga de trabalho precisa adquirir um token para chamadas ao backend da carga de trabalho.

As secções a seguir descrevem como o front-end de carga de trabalho deve usar a API JavaScript e os fluxos em nome de (OBO) para adquirir tokens para a carga de trabalho e serviços externos, bem como para trabalhar com consentimentos.

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:

• O usuário vê uma janela de consentimento de todas as dependências estáticas (o que está configurado na guia permissões da API ) que a carga de trabalho configurou. 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. Esse cenário acontece se o utilizador já deu consentimento ao Microsoft Graph para esta aplicação pelo menos uma vez, ou se o utilizador fizer parte do inquilino principal da aplicação.

Em ambos os cenários, a carga de trabalho não deve se importar se o usuário deu ou não consentimento total para todas as dependências (e não pode saber neste momento). O token recebido tem o destinatário do back-end de carga de trabalho e pode ser usado para chamar diretamente o back-end a partir do front-end.

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.

Para resolver esse problema, é responsabilidade da carga de trabalho propagar o erro para o cliente ao trabalhar com chamadas diretas entre o frontend e o backend. Também é responsabilidade da carga de trabalho propagar o erro para o cliente ao trabalhar com chamadas do Fabric, usando a propagação de erro descrita em Comunicação da carga de trabalho.

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.

Para falhas de API do plano de dados, consulte Gestão de autenticação multifator, acesso condicional e consentimento incremental. Para falhas de API do plano de controle, consulte Comunicação da carga de trabalho.

Cenários de exemplo

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

• Listar espaços de trabalho: GET https://api.fabric.microsoft.com/v1/workspaces

• Crie um armazém: POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

• Escreva para um ficheiro lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Para poder trabalhar com essas APIs, o back-end de carga de trabalho precisa trocar tokens para os seguintes escopos:

• 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
• Para escrever num arquivo do lakehouse: https://storage.azure.com/user_impersonation

Nota

Você pode encontrar os escopos necessários para cada API de malha em este artigo de referência.

Os escopos mencionados anteriormente precisam ser configurados na aplicação de carga de trabalho sob as permissões de API .

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

Exemplo 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. O front-end de carga de trabalho chama a API de back-end de carga de trabalho para obter os espaços de trabalho do usuário e anexa o token na solicitação.

3. O back-end de carga de trabalho valida o token e tenta trocá-lo pelo escopo necessário (digamos ).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. O frontend de carga de trabalho chama a API JavaScript do acquireAccessToken e fornece 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}).

Esta chamada solicita uma janela de consentimento, independentemente de o usuário ter ou não consentido com algumas das dependências. Depois disso, o frontend de carga de trabalho pode repetir a operação.

Nota

Se a troca de tokens ainda falhar em um erro de consentimento, isso significa que o usuário não concedeu consentimento. A carga de trabalho precisa lidar com esses cenários; por exemplo, notifique o usuário de que essa API requer consentimento e não funcionará sem ela.

Exemplo 2

Vamos supor que o backend do workload precise aceder ao OneLake na API de Criação de Item (chamada de Fabric para o workload):

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

2. O sistema de retaguarda da carga de trabalho recebe uma chamada do Fabric, extrai o token delegado e o valida.

3. A carga de trabalho tenta trocar o token por https://storage.azure.com/user_impersonation mas falha porque o administrador locatário da autenticação multifator configurada pelo usuário precisava acessar o Armazenamento do Azure (consulte códigos de erro AADSTS).

4. A carga de trabalho propaga o erro juntamente com as declarações retornadas no erro do Microsoft Entra ID para o cliente, utilizando a propagação de erro descrita em Comunicação da carga de trabalho.

5. O frontend da tarefa chama a API JavaScript do acquireAccessToken e fornece as reivindicações como claimsForConditionalAccessPolicy, onde claims se refere às reivindicações propagadas do backend da tarefa.

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

Depois disso, a carga de trabalho pode repetir a operação.

Tratamento de erros ao solicitar consentimentos

À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.

Nota

Em ambos os cenários (erro e sucesso), a carga de trabalho deve sempre fechar a janela imediatamente, sem latência.