Compartilhar via

Diretrizes de autenticação para o Microsoft Fabric Extensibility Toolkit

Este artigo fornece diretrizes sobre como trabalhar com a autenticação ao criar cargas de trabalho do kit de ferramentas de extensibilidade do Microsoft Fabric. Ele inclui informações sobre como trabalhar com tokens, consentimentos e acessar vários serviços de seu aplicativo de front-end.

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

Modelo de autenticação apenas no front-end

O Kit de Ferramentas de Extensibilidade usa uma arquitetura somente front-end que simplifica a autenticação em comparação com as cargas de trabalho tradicionais:

  • Chamadas diretas à API: seu front-end chama diretamente APIs do Fabric, serviços do Azure e aplicativos externos
  • Reutilização de token: um único token pode ser usado para autenticar em vários serviços protegidos pelo Entra
  • Consentimento simplificado: o gerenciamento de consentimento é tratado pela plataforma com solicitação automática

Configuração do aplicativo Microsoft Entra

Exibir uma guia de API

Configure escopos para seu aplicativo de carga de trabalho:

  • Escopos de integração do Fabric: pré-autenticar o Microsoft Power BI com a ID do aplicativo 871c010f-5e61-4fb1-83ac-98610a7e9110
  • Escopos de API personalizados: adicionar escopos para as APIs personalizadas que sua carga de trabalho expõe
  • Permissões granulares: use escopos diferentes para operações de leitura versus gravação

Por exemplo, se sua carga de trabalho expõe APIs de dados:

  • Adicionar data.read escopo para operações de leitura
  • Adicionar data.write escopo para operações de gravação
  • Validar escopos apropriados em seus manipuladores de API

Aba permissões de API

Configure permissões para serviços externos que sua carga de trabalho precisa acessar:

  • Obrigatório: Fabric.Extend no Serviço do Power BI (obrigatório para integração do Fabric)
  • Serviços do Azure: adicionar escopos para serviços do Azure, como https://storage.azure.com/user_impersonation
  • Aplicativos personalizados: adicionar escopos para seus próprios aplicativos protegidos pelo Entra
  • Serviços de terceiros: incluir todos os serviços externos que dão suporte à autenticação do Entra

Padrões de uso de token

Usando tokens para vários serviços

O token de front-end adquirido por meio do Kit de Ferramentas de Extensibilidade pode ser usado para autenticar em:

APIs de Fabric

// Token automatically includes required Fabric scopes
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Serviços do Azure

// Same token works for Azure services
const response = await fetch('https://management.azure.com/subscriptions', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Aplicativos personalizados

// Token works for your own Entra-secured applications
const response = await fetch('https://myapp.contoso.com/api/data', {
  headers: {
    'Authorization': `Bearer ${token.accessToken}`
  }
});

Gerenciamento do escopo

O Kit de Ferramentas de Extensibilidade abstrai o gerenciamento de escopo para cenários comuns:

  • Bibliotecas de clientes do Fabric: inclua automaticamente os escopos necessários do Fabric
  • Bibliotecas de clientes do Azure: lidar com escopos de serviço do Azure de forma transparente
  • Escopos personalizados: especificar escopos adicionais quando necessário

Trabalhando com consentimentos

Aquisição inicial de token

Comece adquirindo um token para estabelecer o contexto de autenticação:

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

Essa chamada pode resultar em:

  • Sugestão de consentimento: se o usuário não consentiu ao seu aplicativo
  • Aquisição silenciosa: se o consentimento foi concedido anteriormente

Gerenciando acesso adicional ao serviço

Quando sua carga de trabalho precisar acessar serviços adicionais, especifique os escopos necessários:

try {
  // Request token with specific scopes for Azure Storage
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  // Use token to access Azure Storage
  const response = await fetch('https://mystorageaccount.blob.core.windows.net/', {
    headers: { 'Authorization': `Bearer ${token.token}` }
  });
} catch (error) {
  // Handle authentication or authorization errors
  console.error('Access failed:', error.message);
}

Cenários de exemplo

Cenário 1: Acessando o Fabric e os serviços do Azure

A sua carga de trabalho precisa de:

  • Listar espaços de trabalho do Fabric
  • Leia do Armazenamento do Azure
  • Gravar no Azure Key Vault

Implementação:

  1. Configurar permissões de API para serviços necessários
  2. Adquirir token inicial
  3. Usar token para todas as chamadas de serviço
  4. Gerenciar solicitações de consentimento conforme necessário

Cenário 2: integração personalizada de aplicativos

Sua carga de trabalho se integra ao seu próprio serviço de back-end:

  1. Configurar seu back-end: verifique se ele aceita tokens do Entra
  2. Adicionar permissões de API: incluir os escopos do back-end no aplicativo de carga de trabalho
  3. Usar a autenticação padrão: o mesmo padrão de token funciona para seus serviços personalizados

Cenário 3: Integração de serviços de terceiros

Integração com serviços externos habilitados para Entra:

  1. Registro de serviço: registrar sua carga de trabalho com o serviço de terceiros
  2. Configuração de escopo: adicionar os escopos do serviço às suas permissões de API
  3. Uso de token: use o mesmo padrão de autenticação para serviços externos

Tratamento de erros e solução de problemas

Erros comuns de autenticação

  • Consentimento necessário: o usuário não concedeu permissão para um escopo específico
  • Acesso condicional: requisitos de autenticação adicionais (por exemplo, MFA)
  • Expiração do token: o token expirou e precisa de atualização
  • Escopo inválido: o escopo solicitado não está configurado ou disponível

Padrões de tratamento de erros

async function handleAuthenticatedRequest(url: string, requiredScopes: string[] = []) {
  try {
    const token = await workloadClient.auth.acquireFrontendAccessToken({ 
      scopes: requiredScopes 
    });
    return await makeRequest(url, token);
  } catch (error) {
    if (error.code === 'consent_required') {
      // User needs to grant consent for the requested scopes
      console.error('Consent required for scopes:', requiredScopes);
    }
    throw error;
  }
}

Tratamento de URI de redirecionamento

O kit de ferramentas de expansão inclui a manipulação interna de URI de redirecionamento para janelas pop-up de consentimento de autenticação. Isso é implementado no arquivo principal index.ts e manipula redirecionamentos de consentimento automaticamente.

O kit de ferramentas gerencia:

  • Fechamento automático da janela: pop-ups de consentimento são fechados automaticamente após a interação do usuário
  • Tratamento de erros: códigos de erro específicos são detectados e tratados adequadamente
  • Exibição de erro: tentativas de consentimento com falha mostram mensagens de erro amigáveis ao usuário

Implementação atual no kit de ferramentas:

const redirectUriPath = '/close';
const url = new URL(window.location.href);
if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle errors
  if (url?.hash?.includes("error")) {
    if (url.hash.includes("AADSTS650052")) {
      // Handle missing service principal error
      printFormattedAADErrorMessage(url?.hash);
    } else if (url.hash.includes("AADSTS65004")) {
      // Handle user declined consent error
      printFormattedAADErrorMessage(url?.hash);
    } else {
      window.close();
    }
  } else {
    // Close window on successful consent
    window.close();
  }
}

Observação

O tratamento de URI de redirecionamento é incluído automaticamente no modelo do kit de ferramentas de extensibilidade. Você não precisa implementar isso por conta própria, a menos que deseje personalizar o comportamento de tratamento de erros.

Práticas recomendadas

Gerenciamento de tokens

  • Tokens de cache: reutilizar tokens até que eles expirem
  • Gerenciar atualização: implementar a lógica de atualização automática de token
  • Armazenamento seguro: armazenar tokens com segurança na memória do navegador
  • Permissões mínimas: solicite apenas os escopos de que você realmente precisa
  • Consentimento progressivo: solicitar permissões adicionais à medida que os recursos são usados
  • Limpar mensagens: explicar aos usuários por que as permissões são necessárias

Tratamento de erros

  • Degradação normal: fornecer funcionalidade de fallback quando possível
  • Comentários do usuário: comunicar claramente os requisitos de autenticação
  • Lógica de nova tentativa: Implementar mecanismos de repetição apropriados para falhas transitórias

Conteúdo relacionado

  • Last updated on