Acesso programático à API do Fluid usando OAuth 2.0

Este artigo explica como permitir que um aplicativo, script ou automação agendada chame a API do Fluid sem que uma pessoa faça login, usando o fluxo client-credentials do OAuth 2.0 com o Microsoft Entra ID (anteriormente Azure AD).

Use isso quando não há usuário interativo – por exemplo, uma sincronização de dados noturna, uma integração de back-end, um Azure Function/Logic App ou um fluxo do Power Automate não assistido. Em vez de uma pessoa, seu aplicativo se autentica como ele mesmo e o Fluid executa a solicitação como uma conta de serviço dedicada do Fluid que um administrador vincula ao seu aplicativo.

NOTA: Se uma pessoa real estiver fazendo login (Power Apps, Excel, Power BI, Power Automate assistido), você não quer este fluxo – use o artigo de acesso delegado correspondente Excel e Power BI usando OAuth 2.0. Este fluxo é apenas para cenários máquina a máquina, sem usuário.

Neste fluxo não há usuário para fazer login, portanto seu aplicativo prova sua própria identidade ao Microsoft Entra ID usando seu ID do Aplicativo (cliente) mais um segredo do cliente (ou certificado). O Entra emite um token de acesso somente de aplicativo para a API do Fluid. Seu aplicativo envia esse token ao Fluid como um token Bearer.

O Fluid reconhece o token como somente de aplicativo (sem usuário) e verifica a qual conta de serviço do Fluid o aplicativo está vinculado. A solicitação então é executada como essa conta de serviço, com exatamente as permissões do Fluid que lhe foram concedidas.

Your app  --(client id + secret)-->  Microsoft Entra ID
Your app  <--(application access token)--  Microsoft Entra ID
Your app  --(Bearer token)-->  Fluid API   →  runs as the mapped Fluid service account

Três condições devem ser verdadeiras para que isso funcione:

1. Seu aplicativo está registrado no Entra e autorizado a solicitar um token para a API do Fluid (Parte 1).

2. O OAuth 2.0 está habilitado no Fluid.

3. Seu aplicativo está vinculado a uma conta de serviço do Fluid (Parte 2). Até que esse vínculo exista, o Fluid rejeita o token.

Você precisará de:

Este guia pressupõe que o aplicativo da API do Fluid já foi registrado no Entra e que o OAuth 2.0 foi habilitado no Fluid (a configuração única compartilhada por todas as integrações Fluid + Microsoft). Caso contrário, conclua isso primeiro; você precisará do ID do Aplicativo (cliente) da API do Fluid e do seu ID do Diretório (locatário).

O relatório OAuth 2.0 deve ser ativado para o seu site do Fluid, e o endereço web do seu site (por exemplo, https://yourcompany.fluid.work) deve ser registrado no aplicativo da API do Fluid para que a Microsoft emita tokens para ele.

1. Faça login na sua instância do Fluid como administrador do Fluid e clique na foto do seu perfil no canto superior direito, escolha Console de Administração > Provedor de Autenticação (ou navegue até /Config/AuthenticationProvider).

2. Habilitar a API OAuth2

   

Para que a Microsoft permita que o Excel e o Power BI obtenham um token para o Fluid, um administrador do Microsoft Entra na sua organização concede consentimento único ao aplicativo da API do Fluid. Você gera o link de consentimento diretamente do console de administração do Fluid.

1. Faça login na sua instância do Fluid como administrador do Fluid e clique na foto do seu perfil no canto superior direito, escolha Console de Administração > Provedor de Autenticação (ou navegue até /Config/AuthenticationProvider).

2. Localize o campo GUID do Seu Locatário Entra e insira o ID do locatário do Microsoft Entra — um GUID no formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Você pode encontrá-lo no Portal do Azure em Microsoft Entra ID > Visão Geral.

3. Depois de inserir o ID do locatário, o campo URL de Consentimento da API do Fluid cria automaticamente o link de consentimento de administrador correto para o seu locatário.

   

4. Clique no ícone de copiar ao lado do campo URL de Consentimento da API do Fluid para copiar o link para a área de transferência. Ele será semelhante ao exemplo abaixo:

   https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/adminconsent?client_id=69c9b574-a5bf-46ca-bb04-ed5793d298e4&redirect_uri=https://www.fluid.work

5. Envie o link copiado para um administrador do Microsoft Entra na sua organização (ou abra-o você mesmo se tiver essa função). O administrador abre o link, faz login e aceita o prompt de permissões. Isso registra a API do Fluid no seu locatário para que seus usuários possam fazer login nela pelo Excel e pelo Power BI.

NOTA: Esta é uma etapa de consentimento, não um registro de aplicativo. Você está aprovando o aplicativo publicado do Fluid – você não o cria nem é proprietário dele. Sem este consentimento, o login pode falhar com AADSTS650057 ou "Aprovação de administrador necessária".

Para que o Entra emita um token somente de aplicativo para a API do Fluid, o registro do aplicativo da API do Fluid deve oferecer pelo menos uma função de aplicativo.

• No centro de administração do Microsoft Entra, abra Registros de aplicativo > seu aplicativo da API do Fluid.

• Selecione Funções de aplicativo > + Criar função de aplicativo e insira:

  • Nome de exibição: Access Fluid API

  • Tipos de membro permitidos: Aplicativos

  • Valor: Api.Access

  • Descrição: "Permite que um aplicativo chame a API do Fluid como uma conta de serviço."

• Certifique-se de que Deseja habilitar esta função de aplicativo? esteja marcado e selecione Aplicar.

NOTA: O Fluid não exige um nome de função específico – ele identifica seu aplicativo pelo seu ID do Aplicativo (cliente) (consulte a Parte 2). Esta função existe apenas para que o Microsoft Entra emita um token somente de aplicativo para a API do Fluid.

Registre um aplicativo separado para representar sua automação (recomenda-se um por integração, para que cada um possa ser vinculado e revogado de forma independente).

• Em Registros de aplicativo, selecione + Novo registro.

• Nome: algo descritivo, por exemplo Fluid Nightly Sync.

• Tipos de conta com suporte: Contas somente neste diretório organizacional.

• Deixe o URI de redirecionamento em branco e selecione Registrar.

• Na página Visão geral, copie o ID do aplicativo (cliente) – esta é a identidade que o Fluid mapeará para uma conta de serviço.

• Selecione Certificados & segredos > + Novo segredo do cliente, adicione um segredo e copie o Valor do segredo imediatamente.

DICA: Um certificado é mais seguro do que um segredo do cliente e é recomendado para produção. Você pode fazer upload de um em Certificados & segredos > Certificados em vez de criar um segredo.

• Ainda no aplicativo de automação, selecione Permissões de API > + Adicionar uma permissão > Minhas APIs.

• Escolha seu aplicativo Fluid API.

• Selecione Permissões de aplicativo, marque Api.Access e selecione Adicionar permissões.

• Selecione Conceder consentimento do administrador para [sua organização] e confirme. O status da permissão deve exibir um ícone verde de confirmação.

AVISO: As permissões de aplicativo sempre exigem consentimento do administrador. Sem a etapa Conceder consentimento do administrador, sua solicitação de token na Parte 3 falhará.

AVISO: Mantenha os dois IDs do aplicativo (cliente) distintos. O token é solicitado para o ID do cliente da Fluid API (o recurso), mas o Fluid vincula a conta de serviço ao ID do cliente do aplicativo de automação (o chamador). São valores diferentes.

Como o vínculo existe dentro do Fluid, esta etapa é realizada por um Administrador do Sistema Fluid (ou pelo suporte do Fluid). Forneça a eles:

• O ID do aplicativo (cliente) do seu aplicativo de automação (da Etapa 2).

• A conta de serviço do Fluid com a qual você deseja que a automação seja executada – idealmente um usuário Fluid dedicado e não pessoal criado para esta integração com o mínimo de acesso necessário.

Etapa A. Criar (ou confirmar) a conta de serviço do Fluid

1. No Console de Administração do Fluid, crie um usuário dedicado para a automação (não reutilize a conta de uma pessoa real). Por exemplo, nomeie-o svc-power-automate com um nome de exibição como Power Automate Service Account.

2. Certifique-se de que a conta está ativa e conceda a ela apenas as permissões/funções do Fluid que o fluxo precisa (privilégio mínimo).

3. Anote o nome de usuário ou e-mail da conta — você o usará para encontrar seu ID interno a seguir.

Etapa B. Adicionar o ID do cliente do seu aplicativo como nome de usuário secundário para a conta de serviço do Fluid

1. Clique na foto do seu perfil no canto superior direito e escolha Gerenciamento de Usuários & Recursos

2. Localize a conta de usuário do Fluid que você deseja usar como a conta com a qual sua automação será executada.

3. Clique no usuário para editar seus detalhes

4. Ao lado do nome de usuário, clique no botão Adicionar Nome de Usuário

5. Marque a caixa É ID de Cliente OAuth2 e insira o seu ID de Cliente, valor #3 da tabela acima

6. Clique em Salvar para salvar o ID do cliente e depois em Atualizar para salvar os detalhes do Usuário.

7. Agora, quando o Power Automate passar o token de autenticação, o Fluid será capaz de associar o token a um usuário e executar a API usando essa conta de usuário.

AVISO: Até que este vínculo exista, cada solicitação da automação é rejeitada com 401 e um evento de segurança ClientAppNotMapped. Isso é por design – apenas aplicativos explicitamente aprovados podem ser executados sem supervisão.

Sua automação solicita um token somente de aplicativo do Entra, direcionado à Fluid API. Use o escopo .default (construído a partir do URI do ID do Aplicativo da Fluid API).

Solicitação HTTP:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={automation-app-client-id}
&client_secret={automation-app-secret}
&scope=api://{fluid-api-client-id}/.default
&grant_type=client_credentials

Exemplo em PowerShell:

$tenant   = "99998888-dddd-7777-cccc-6666eeee5555"
$clientId = "55556666-eeee-8888-ffff-1111aaaa2222"      # the automation app
$secret   = "abc8Q~exampleSecretValue..."
$fluidApi = "00001111-aaaa-2222-bbbb-3333cccc4444"      # the Fluid API app (resource)

$body = @{
    client_id     = $clientId
    client_secret = $secret
    scope         = "api://$fluidApi/.default"
    grant_type    = "client_credentials"
}
$resp  = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -Body $body
$token = $resp.access_token

NOTA: O scope deve ser api://{fluid-api-client-id}/.default – o próprio identificador da Fluid API – não um nome de escopo personalizado. O público do token é então a Fluid API, que é o que o Fluid valida.

Envie o token no cabeçalho Authorization em cada solicitação:

$headers = @{ Authorization = "Bearer $token" }
$data = Invoke-RestMethod -Method Get -Uri "https://yourcompany.fluid.work/api/..." -Headers $headers

Uma chamada bem-sucedida retorna dados do Fluid (HTTP 200), sendo executada como sua conta de serviço mapeada.

DICA: Reutilize o token até que ele esteja próximo do vencimento (normalmente ~60–75 minutos) em vez de solicitar um novo para cada chamada. Armazene-o em cache e atualize somente quando necessário.

As mesmas duas solicitações (obter token e depois chamar o Fluid) funcionam a partir de qualquer host sem supervisão:

• Power Automate (autônomo) / Azure Logic Apps: use uma ação HTTP para fazer POST no endpoint de token, armazene access_token em uma variável e, em seguida, use uma segunda ação HTTP para chamar https://yourcompany.fluid.work/api/... com Authorization: Bearer <token>. Armazene o segredo no Azure Key Vault e leia-o com o conector do Key Vault em vez de codificá-lo diretamente.

• Azure Functions / Web Jobs / serviços: use o MSAL (ConfidentialClientApplication) com AcquireTokenForClient e o escopo api://{fluid-api-client-id}/.default; ele gerencia o cache e a renovação de tokens para você.

• Privilégio mínimo: conceda à conta de serviço Fluid vinculada apenas as permissões necessárias para a automação. O aplicativo pode fazer tudo o que essa conta pode fazer.

• Um aplicativo por integração: registre um aplicativo de automação separado para cada integração, para que possam ser monitorados, rotacionados e revogados de forma independente.

• Prefira certificados em vez de segredos de cliente para produção, e rotacione as credenciais periodicamente – a integração para de funcionar no momento em que um segredo/certificado expira.

• Armazene segredos com segurança (por exemplo, Azure Key Vault); nunca os incorpore em código ou definições de fluxo.

• Monitore e revise: tentativas com falha aparecem em Console de Administração > Eventos de Segurança no Fluid. Confirme periodicamente se cada aplicativo mapeado ainda é necessário e remova os vínculos que não forem.

• Revogando o acesso: para interromper imediatamente uma automação, remova seu vínculo no Fluid ou desative/exclua seu aplicativo Entra (ou sua credencial).

• Para o lado do Fluid (habilitação do OAuth 2.0, criação e vinculação da conta de serviço, permissões), entre em contato com seu Administrador do Sistema Fluid ou Gerente de Conta Fluid.

• Para o lado do Microsoft Entra (registro de aplicativo, funções de aplicativo, segredos/certificados, consentimento do administrador), entre em contato com seu administrador do Microsoft 365 / Azure.

• Excel e Power BI usando OAuth 2.0

• Agendamento de atualização automática do Power BI a partir do Fluid OAuth 2.0

• Conectando o Power Apps ao Fluid usando OAuth 2.0

• Configurando o Power Automate para chamar a API do Fluid usando OAuth 2.0