Compartilhar via

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

  • Artigo

Este artigo fornece diretrizes sobre como trabalhar com a autenticação ao criar cargas de trabalho do Microsoft Fabric. Ele inclui informações sobre como trabalhar com tokens e consentimentos.

Antes de começar, verifique se você está familiarizado com os conceitos na visão geral da Autenticação e na configuração da Autenticação.

APIs do plano de dados e do painel de controle

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

  • APIs do plano de controle 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 é Criar Item.

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

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

Na guia Expor uma API, você precisa adicionar escopos para APIs do plano de controle e escopos para APIs do plano de dados:

  • Os escopos adicionados para as APIs do plano de controle devem pré-autorizar o aplicativo Fabric Client for Workloads com o ID do aplicativo d2450708-699c-41e3-8077-b0c8341509aa. Esses escopos são incluídos no token que o back-end da carga de trabalho recebe quando o Fabric o chama.

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

  • Os escopos adicionados para APIs do plano de dados devem pré-autorizar o Power BI da Microsoft com a ID do aplicativo 871c010f-5e61-4fb1-83ac-98610a7e9110. Eles são incluídos no token que a API JavaScript acquireAccessToken retorna.

    Para APIs do 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 que o token recebido inclui esses escopos quando essas APIs são chamadas do cliente. Por exemplo:

    • A carga de trabalho expõe duas APIs ao cliente, ReadData e WriteData.
    • A carga de trabalho expõe dois escopos de plano de dados, data.read e data.write.
    • Na API de 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.

Aba de permissões da API no aplicativo da carga de trabalho do Microsoft Entra ID

Na guia permissões de API, você precisa adicionar todos os escopos que sua carga de trabalho precisa para trocar um token. É obrigatório adicionar o escopo Fabric.Extend no serviço Power BI. As solicitações ao Fabric podem falhar sem esse escopo.

Trabalho com tokens e consentimentos

Quando você está trabalhando com APIs do plano de dados, o front-end do aplicativo precisa adquirir um token para realizar chamadas ao back-end do aplicativo.

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

Etapa 1: Adquirir 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 que a carga de trabalho configurou (o que está configurado na guia permissões de API). Esse cenário ocorre se o usuário não faz parte do locatário inicial do aplicativo e o usuário não concedeu consentimento ao Microsoft Graph para este aplicativo antes.

  • O usuário não vê uma janela de consentimento. Esse cenário ocorrerá se o usuário já consentiu pelo menos uma vez ao Microsoft Graph para este aplicativo ou se fizer parte do inquilino principal do aplicativo.

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 é destinado ao back-end do workload e pode ser usado para chamar diretamente o back-end a partir do front-end do workload.

Etapa 2: Tentar acessar serviços externos

A carga de trabalho pode precisar acessar serviços que exigem autenticação. Para esse acesso, ele precisa executar o fluxo OBO , em que troca o token que recebeu de seu cliente ou do Fabric para outro serviço. A troca de tokens 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 front-end e o back-end. 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 de carga de trabalho.

Depois que a carga de trabalho propagar o erro, ele poderá chamar a API JavaScript acquireAccessToken para resolver o problema de consentimento ou política de acesso condicional e repetir a operação.

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

Cenários de exemplo

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

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

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

  • Gravar em um arquivo lakehouse: PUT https://onelake.dfs.fabric.microsoft.com/{filePath}?resource=file

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

  • 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 warehouse: https://analysis.windows.net/powerbi/api/Warehouse.ReadWrite.All ou https://analysis.windows.net/powerbi/api/Item.ReadWrite.All
  • Para gravar em um arquivo lakehouse: https://storage.azure.com/user_impersonation

Observação

Você pode encontrar escopos necessários para cada API do Fabric este artigo de referência.

Os escopos mencionados anteriormente precisam ser configurados no aplicativo de trabalho nas permissões de API.

Vamos ver alguns exemplos de cenários que a carga de trabalho pode enfrentar.

Exemplo 1

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

  1. O front-end da carga de trabalho solicita um token usando a API JavaScript.

  2. O front-end da carga de trabalho chama a API de back-end da carga de trabalho para obter os workspaces do usuário e anexa o token na solicitação.

  3. O back-end da carga de trabalho valida o token e tenta trocar isso pelo escopo necessário (digamos https://analysis.windows.net/powerbi/api/Workspace.Read.All).

  4. A carga de trabalho falha ao trocar o token pelo 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 da workload chama 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 solicitar consentimento para todas as suas dependências estáticas configuradas em seu aplicativo, portanto, ela chama a API JavaScript e fornece promptFullConsent:

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

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

Observação

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 back-end do fluxo de trabalho precisa acessar o OneLake na API de Criação de Item (chamada do sistema Fabric para o fluxo de trabalho):

  1. O front-end da carga de trabalho chama a API Criar Item JavaScript.

  2. O back-end de processamento 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 do locatário da autenticação multifator configurada pelo usuário precisa acessar o Armazenamento do Azure (consulte códigos de erro do AADSTS).

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

  5. O front-end da carga de trabalho chama a API JavaScript acquireAccessToken e fornece reivindicações como claimsForConditionalAccessPolicy, nas quais claims se refere às reivindicações propagadas do back-end da carga de trabalho.

    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. Em nosso exemplo, esse 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 front-end da carga de trabalho pode extrair o código de erro da URL e tratá-lo adequadamente.

Observação

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