Referência da API JavaScript de autenticação

O Fabric Extensibility Toolkit fornece uma API JavaScript para adquirir tokens de autenticação que podem ser usados para acessar APIs Fabric, serviços Azure e qualquer aplicação protegida pelo Entra. Este artigo fornece referências e exemplos abrangentes de uso da API.

Referência de API

acquireFrontendAccessToken(params: AcquireFrontendAccessTokenParams): Promise<AccessToken>;

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

A API retorna um AccessToken objeto que contém:

• token: A string de token JWT a ser usada em cabeçalhos de autorização

Uso Básico

Aquisição simples de tokens

// Acquire a token with default Fabric permissions
const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

// Use the token in API calls
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/json'
  }
});

Token com escopos específicos

// Request specific scopes for Azure Storage
const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: ['https://storage.azure.com/user_impersonation']
});

Exemplos de uso de tokens

Acesso à API de Fabric

O token pode ser usado diretamente com APIs REST do Fabric:

async function listWorkspaces() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });
  
  const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Azure service access

Use escopos para especificar os serviços Azure aos quais você precisa acessar:

async function readFromStorage(accountName, containerName, blobName) {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token.token}`,
      'x-ms-version': '2021-12-02'
    }
  });
  
  return await response.text();
}

Acesso a aplicações personalizadas

Acesse suas próprias aplicações protegidas pelo Entra:

async function callCustomAPI() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://myapp.contoso.com/data.read']
  });
  
  const response = await fetch('https://myapp.contoso.com/api/data', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

Referência de parâmetro

scopes

Um array de strings de escopo que especificam as permissões que seu token precisa.

Common Azure service scopes:

• https://storage.azure.com/user_impersonation - Azure Storage
• https://vault.azure.net/user_impersonation - Cofre Azure Key
• https://management.azure.com/user_impersonation - Azure Resource Manager
• https://graph.microsoft.com/User.Read - Microsoft Graph

Exemplo de uso:

const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: [
    'https://storage.azure.com/user_impersonation'
  ]
});

Arranjo de osciloscópios vazios: Use um array vazio para obter um token com permissões padrão do Fabric:

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

Gerenciamento de consentimento

Fluxo automático de consentimento

O Extensibility Toolkit gerencia automaticamente os fluxos de trabalho de consentimento:

• Solicitação inicial: Se o consentimento estiver faltando, uma janela pop-up se abre
• Interação do Usuário: O usuário concede ou nega permissões
• Fechamento automático: Popup fecha automaticamente após a ação do usuário
• Entrega do token: Se bem-sucedida, o token é devolvido à sua aplicação

Gerenciamento do popup de consentimento

O toolkit gerencia pop-ups de consentimento automaticamente, mas você pode personalizar o comportamento do URI de redirecionamento. Crie uma página de redirecionamento que trate da resposta de consentimento:

// redirect.js - Handle consent redirect
const redirectUriPath = '/close';
const url = new URL(window.location.href);

if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle consent errors
  if (url?.hash?.includes("error")) {
    // Extract error information
    const errorMatch = url.hash.match(/error=([^&]+)/);
    const errorDescription = url.hash.match(/error_description=([^&]+)/);
    
    // Handle specific errors
    if (url.hash.includes("AADSTS650052")) {
      console.error("Service principal not configured");
    } else if (url.hash.includes("AADSTS65004")) {
      console.error("User declined consent");
    }
  }
  
  // Always close the popup immediately
  window.close();
}

Consentimento entre inquilinos

Para acessar recursos entre diferentes locatários:

// Request consent for cross-tenant access
const token = await workloadClient.auth.acquireAccessToken({
  additionalScopesToConsent: ['https://api.partner-app.com/data.read']
});

Tratamento de erros

Cenários de erro comuns

async function robustTokenAcquisition() {
  try {
    return await workloadClient.auth.acquireAccessToken();
  } catch (error) {
    switch (error.code) {
      case 'user_cancelled':
        console.log('User cancelled the consent dialog');
        break;
      case 'consent_required':
        console.log('Additional consent required');
        break;
      case 'interaction_required':
        console.log('User interaction required');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
    throw error;
  }
}

Tratamento de expiração de token

class TokenManager {
  private currentToken: AccessToken | null = null;
  
  async getValidToken(): Promise<AccessToken> {
    if (!this.currentToken || this.isTokenExpired(this.currentToken)) {
      this.currentToken = await workloadClient.auth.acquireAccessToken();
    }
    return this.currentToken;
  }
  
  private isTokenExpired(token: AccessToken): boolean {
    // Add buffer time to prevent requests with almost-expired tokens
    const bufferMinutes = 5;
    const expirationWithBuffer = new Date(token.expiresOn.getTime() - (bufferMinutes * 60 * 1000));
    return new Date() >= expirationWithBuffer;
  }
}

Práticas recomendadas

Cache e reutilização de tokens

• Tokens de cache: Armazenar tokens na memória até a expiração
• Atualização automática: Implementar atualização automática de token antes do vencimento
• Armazenamento seguro: Nunca persista tokens para armazenamento local ou cookies

Gerenciamento do escopo

• Escopos mínimos: Solicite apenas as permissões necessárias
• Consentimento progressivo: Solicite escopos adicionais conforme recursos são usados
• Validação de escopo: Os tokens de verificação incluem os escopos necessários antes das chamadas de API

Tratamento avançado de erros

• Degradação gradual: Fornecer funcionalidade de recuo quando a autenticação falhar
• Mensagens do usuário: Explique claramente por que as permissões são necessárias
• Lógica de retentativa: Implementar mecanismos de retentativa apropriados para falhas transitórias

Otimização de desempenho

• Requisições paralelas: Adquirir tokens para múltiplos serviços em paralelo sempre que possível
• Operações em lote: Agrupar chamadas de API para minimizar a sobrecarga de aquisição de tokens
• Gerenciamento de cache: Implementar estratégias eficientes de cache de tokens

Conteúdo relacionado

• Início rápido: Adquira tokens Microsoft Entra - Guia simples para começar
• Visão geral da autenticação - Conceitos de autenticação de alto nível
• Diretrizes de autenticação - Melhores práticas e recomendações
• APIs do Access Fabric - Wrappers de API pré-construídos