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 controlo

  • As APIs de planos de dados são APIs que o backend da carga de trabalho expõe. O frontend de carga de trabalho pode contactá-los diretamente. No caso das APIs do plano de dados, o backend da carga de trabalho pode decidir quais as APIs a expor.

  • APIs de plano de controlo são APIs que passam pelo 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.

    Para APIs de planos de controlo, a carga de trabalho deve seguir os contratos definidos no backend da carga de trabalho e implementar essas APIs.

Expor um separador API na aplicação da carga de trabalho no Microsoft Entra ID

No separador Expor uma API, tem de adicionar âmbitos para APIs do plano de controlo e âmbitos para APIs do plano de dados:

  • Os escopos adicionados para as APIs do plano de controlo devem pré-autorizar a aplicação Fabric Client for Workloads com o ID da aplicação d2450708-699c-41e3-8077-b0c8341509aa. Esses escopos estão incluídos no token que o backend da carga de trabalho recebe quando o Fabric o invoca.

    É necessário adicionar pelo menos um âmbito para a API do plano de controlo para que o fluxo funcione.

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

Separador de permissões da API na aplicação da carga de trabalho no Microsoft Entra ID

No separador Permissões de API, tem de adicionar todos os âmbitos de que a sua carga de trabalho necessita para efetuar a troca de um token. Um escopo obrigatório a adicionar é Fabric.Extend no serviço Power BI. Pedidos ao Fabric podem falhar sem este escopo.

Trabalhar com tokens e consentimentos

Quando se trabalha com APIs do plano de dados, o frontend da carga de trabalho precisa de adquirir um token para efetuar chamadas ao backend da carga de trabalho.

As secções seguintes descrevem como o frontend da carga de trabalho deve usar a API de JavaScript e os fluxos on-behalf-of (OBO) para obter tokens para a carga de trabalho e para serviços externos, e para gerir 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 utilizador vê uma janela de consentimento com todas as dependências estáticas (o que está configurado no separador de 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. Este cenário ocorre se o utilizador já tiver dado consentimento ao Microsoft Graph pelo menos uma vez para esta aplicação, ou se o utilizador fizer parte do tenant de origem da aplicação.

Em ambos os cenários, a carga de trabalho não deve preocupar-se com o facto de o utilizador ter dado ou não o seu consentimento integral para todas as dependências (e não o pode saber nesta fase). O token recebido tem como público-alvo o back-end da carga de trabalho e pode ser utilizado para chamar diretamente o back-end da carga de trabalho a partir do front-end da carga de trabalho.

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 este problema, cabe à aplicação propagar o erro ao cliente quando se utilizam chamadas diretas entre o frontend e o backend. É também da responsabilidade da carga de trabalho propagar o erro ao cliente ao trabalhar com chamadas provenientes do Fabric, recorrendo à propagação de erros descrita em 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.

Para falhas na API do plano de dados, veja Gestão da autenticação multifator, Acesso Condicional e consentimento incremental. Para falhas na API do plano de controlo, veja 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 num ficheiro de lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

Para poder trabalhar com essas APIs, o backend da carga de trabalho tem de trocar tokens pelos 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 ficheiro de lakehouse: https://storage.azure.com/user_impersonation

Nota

Pode encontrar os escopos necessários para cada API Fabric neste artigo de referência.

Os âmbitos mencionados anteriormente precisam de ser configurados na aplicação da carga de trabalho em Permissões da 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 frontend da carga de trabalho chama a API backend da carga de trabalho para obter os espaços de trabalho do utilizador e inclui o token no pedido.

  3. O back-end da carga de trabalho valida o token e tenta trocá-lo para obter o âmbito necessário (por exemplo, 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. A interface da carga de trabalho invoca a API JavaScript 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 abre uma janela de consentimento, independentemente de o utilizador já ter dado consentimento a algumas das dependências ou não. Depois disso, o frontend de carga de trabalho pode tentar novamente 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 assumir que o backend da carga de trabalho precisa de aceder ao OneLake na API Create Item (chamada do Fabric para a carga de trabalho):

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

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

  3. A carga de trabalho tenta trocar o token porhttps://storage.azure.com/user_impersonation, mas falha porque o administrador do tenant da autenticação multifator configurada pelo utilizador precisou de aceder ao Armazenamento do Azure (ver códigos de erro AADSTS).

  4. A carga de trabalho propaga o erro, juntamente com as declarações devolvidas com o erro pelo Microsoft Entra ID, ao cliente, utilizando a propagação de erros descrita em Comunicação da carga de trabalho.

  5. O frontend da carga de trabalho chama a acquireAccessToken API de JavaScript e fornece reivindicações como claimsForConditionalAccessPolicy, onde claims se refere às reivindicações propagadas pelo backend da carga de trabalho:

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

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

Gestão 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.

  • Last updated on