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

Este artigo fornece orientações sobre como trabalhar com autenticação ao construir cargas de trabalho do toolkit de extensibilidade do Microsoft Fabric. Inclui informações sobre como trabalhar com tokens, consentimentos e acesso a vários serviços a partir da sua aplicação frontend.

Antes de começar, certifique-se de que está familiarizado com os conceitos na visão geral de Autenticação.

Modelo de autenticação apenas no frontend

O Extensibility Toolkit utiliza uma arquitetura apenas frontend que simplifica a autenticação em comparação com cargas de trabalho tradicionais:

• Chamadas diretas de API: O seu frontend chama diretamente APIs Fabric, serviços Azure e aplicações externas
• Reutilização de tokens: Um único token pode ser usado para autenticar contra múltiplos serviços Entra-secured
• Consentimento simplificado: A gestão do consentimento é feita pela plataforma com solicitação automática.

Configuração da aplicação Microsoft Entra

Expor uma aba API

Configure os escopos para a sua aplicação de trabalho:

• Escopos de integração do Fabric: Pré-autorizar Microsoft Power BI com ID da aplicação 871c010f-5e61-4fb1-83ac-98610a7e9110
• Escopos de APIs personalizados: Adicione escopos para quaisquer APIs personalizadas que a sua carga de trabalho exponha
• Permissões granulares: Use diferentes escopos para operações de leitura vs. escrita

Por exemplo, se a sua carga de trabalho expor APIs de dados:

• Adicionar âmbito data.read para operações de leitura
• Adicionar data.write âmbito para operações de escrita
• Valide os escopos apropriados nos seus handlers de API

Separador de permissões da API

Configure permissões para serviços externos que a sua carga de trabalho precisa aceder a.

• Obrigatório: Fabric.Extend no Power BI Service (obrigatório para integração com o Fabric)
• Serviços Azure: Adicionar escopos para serviços Azure como https://storage.azure.com/user_impersonation
• Aplicações personalizadas: Adicione escopos para as suas próprias aplicações protegidas pela Entra
• Serviços de terceiros: Incluir quaisquer serviços externos que suportem autenticação Entra

Padrões de utilização de tokens

Utilização de tokens para múltiplos serviços

O token frontend adquirido através do Extensibility Toolkit pode ser usado para autenticar contra:

Fabric APIs

// 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}`
  }
});

Aplicações personalizadas

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

Gestão do âmbito

O Extensibility Toolkit abstrai a gestão de âmbito para cenários comuns:

• Bibliotecas cliente do Fabric: Incluem automaticamente os escopos necessários do Fabric
• Bibliotecas cliente Azure: Gerir os escopos dos serviços Azure de forma transparente
• Âmbitos personalizáveis: Especifique âmbitos adicionais quando necessário

Trabalhar com consentimentos

Aquisição inicial de tokens

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

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

Esta chamada pode resultar em:

• Pedido de consentimento: Se o utilizador não consentiu com a sua candidatura
• Aquisição silenciosa: Se o consentimento já foi concedido anteriormente

Gestão do acesso adicional ao serviço

Quando a sua carga de trabalho precisar de aceder a serviços adicionais, especifique os âmbimos 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: Aceder aos serviços Fabric e Azure

A sua carga de trabalho precisa de:

• Listar espaços de trabalho do Fabric
• Ler do Armazenamento do Azure
• Escrever no Azure Key Vault

Implementação:

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

Cenário 2: Integração de aplicações personalizadas

A sua carga de trabalho integra-se com o seu próprio serviço de backend:

1. Configure o seu backend: Certifique-se de que aceita tokens Entra
2. Adicionar permissões de API: Inclua os escopos do seu backend na aplicação da carga de trabalho
3. Use autenticação padrão: O mesmo padrão de token funciona para os seus serviços personalizáveis

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

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

1. Registo do serviço: Registe a sua carga de trabalho junto do serviço de terceiros
2. Configuração do âmbito: Adicione os escopos do serviço às permissões da sua API
3. Utilização do token: Usar 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 utilizador não concedeu permissão para um âmbito específico
• Acesso condicional: Requisitos adicionais de autenticação (por exemplo, MFA)
• Expiração do token: O token expirou e precisa de ser atualizado
• Âmbito inválido: O âmbito solicitado não está configurado nem 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

As ferramentas de extensibilidade incluem a gestão de URI de redirecionamento incorporada para janelas de consentimento de autenticação. Isto é implementado no ficheiro principal index.ts e gere automaticamente os redirecionamentos de consentimento.

O kit de ferramentas aborda:

• Fecho automático de janelas: Os pop-ups de consentimento fecham-se automaticamente após a interação do utilizador
• Tratamento de erros: Códigos de erro específicos são detetados e tratados adequadamente
• Ecrã de erro: Tentativas de consentimento falhadas mostram mensagens de erro amigáveis ao utilizador

Implementação atual no toolkit:

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();
  }
}

Melhores práticas

Gestão de tokens

• Tokens de cache: Reutilizar tokens até expirarem
• Gestão de atualização: Implementar lógica automática de atualização de tokens
• Armazenamento seguro: Armazenar tokens de forma segura na memória do navegador

Gestão de consentimentos

• Permissões mínimas: Solicite apenas os telescópios de que realmente precisa
• Consentimento progressivo: Solicitar permissões adicionais à medida que as funcionalidades são usadas
• Mensagem clara: Explique aos utilizadores porque é que as permissões são necessárias

Tratamento de erros

• Degradação gradual: Fornecer funcionalidade de recuo sempre que possível
• Feedback dos utilizadores: Comunicar claramente os requisitos de autenticação
• Lógica de tentativas: Implementar mecanismos de tentativas apropriados para falhas transitórias

Conteúdo relacionado

• Visão geral da autenticação
• API JavaScript de autenticação