Acceso programático a la API de Fluid mediante OAuth 2.0

Este artículo explica cómo permitir que una aplicación, script o automatización programada llame a la API de Fluid sin que una persona inicie sesión, utilizando el flujo de credenciales de cliente de OAuth 2.0 con Microsoft Entra ID (anteriormente Azure AD).

Use esto cuando no haya un usuario interactivo – por ejemplo, una sincronización de datos nocturna, una integración de backend, una Azure Function/Logic App, o un flujo de Power Automate desatendido. En lugar de una persona, su aplicación se autentica como ella misma y Fluid ejecuta la solicitud como una cuenta de servicio de Fluid dedicada que un administrador vincula a su aplicación.

NOTA: Si una persona real está iniciando sesión (Power Apps, Excel, Power BI, Power Automate asistido), no desea este flujo – use en su lugar el artículo de acceso delegado correspondiente Excel y Power BI mediante OAuth 2.0 . Este flujo es únicamente para escenarios de máquina a máquina, sin usuario.

---

En este flujo no hay ningún usuario que inicie sesión, por lo que su aplicación demuestra su propia identidad ante Microsoft Entra ID mediante su ID de aplicación (cliente) más un secreto de cliente (o certificado). Entra emite un token de acceso solo de aplicación para la API de Fluid. Su aplicación envía ese token a Fluid como un token Bearer.

Fluid reconoce el token como solo de aplicación (no tiene usuario) y busca a qué cuenta de servicio de Fluid está vinculada la aplicación. La solicitud se ejecuta entonces como esa cuenta de servicio, con exactamente los permisos de Fluid que se le hayan otorgado.

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

Deben cumplirse tres condiciones para que esto funcione:

1. Su aplicación está registrada en Entra y tiene permiso para solicitar un token para la API de Fluid (Parte 1).

2. OAuth 2.0 está habilitado en Fluid.

3. Su aplicación está vinculada a una cuenta de servicio de Fluid (Parte 2). Hasta que exista este vínculo, Fluid rechaza el token.

---

Necesitará lo siguiente:

Esta guía asume que la aplicación de la API de Fluid ya se ha registrado en Entra y que OAuth 2.0 se ha habilitado en Fluid (la configuración única que comparten todas las integraciones de Fluid + Microsoft). Si no es así, complete ese paso primero; necesitará el ID de aplicación (cliente) de la API de Fluid y su ID de directorio (inquilino).

---

La generación de informes de OAuth 2.0 debe estar activada para su sitio de Fluid, y la dirección web de su sitio (por ejemplo https://yourcompany.fluid.work) debe estar registrada en la aplicación de la API de Fluid para que Microsoft emita tokens para ella.

1. Inicie sesión en su instancia de Fluid como administrador de Fluid y haga clic en su foto de perfil en la esquina superior derecha, elija Admin Console > Proveedor de autenticación (o vaya a /Config/AuthenticationProvider).

2. Enable OAuth2 API

   

Para que Microsoft permita que Excel y Power BI obtengan un token para Fluid, un administrador de Microsoft Entra de su organización otorga un consentimiento único a la aplicación de la API de Fluid. Usted genera el enlace de consentimiento directamente desde su consola de administración de Fluid.

1. Inicie sesión en su instancia de Fluid como administrador de Fluid y haga clic en su foto de perfil en la esquina superior derecha, elija Admin Console > Proveedor de autenticación (o vaya a /Config/AuthenticationProvider).

2. Ubique el campo Your Entra Tenant GUID e ingrese el ID de su inquilino de Microsoft Entra — un GUID con el formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Puede encontrarlo en el Azure Portal en Microsoft Entra ID > Overview.

3. Una vez que haya ingresado el ID de su inquilino, el campo Fluid API Consent Url genera automáticamente el enlace de consentimiento de administrador correcto para su inquilino.

   

4. Haga clic en el icono de copiar junto al campo Fluid API Consent Url para copiar el enlace al portapapeles. Se verá algo similar a lo siguiente:

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

5. Envíe el enlace copiado a un administrador de Microsoft Entra de su organización (o ábralo usted mismo si tiene ese rol). El administrador abre el enlace, inicia sesión y acepta la solicitud de permisos. Esto registra la API de Fluid en su inquilino para que sus usuarios puedan iniciar sesión en ella desde Excel y Power BI.

NOTA: Este es un paso de consentimiento, no un registro de aplicación. Usted está aprobando la aplicación publicada de Fluid – no la crea ni es su propietario. Sin este consentimiento, el inicio de sesión puede fallar con AADSTS650057 o "Se necesita la aprobación del administrador".

Para que Entra emita un token solo de aplicación para la API de Fluid, el registro de la aplicación Fluid API debe ofrecer al menos un rol de aplicación.

• En el centro de administración de Microsoft Entra, abra App registrations > su aplicación Fluid API.

• Seleccione App roles > + Create app role e ingrese:

  • Display name: Access Fluid API

  • Allowed member types: Applications

  • Value: Api.Access

  • Description: "Allows an application to call the Fluid API as a service account."

• Asegúrese de que Do you want to enable this app role? esté marcado, y seleccione Apply.

NOTA: Fluid no requiere un nombre de rol específico – identifica su aplicación por su ID de aplicación (cliente) (vea la Parte 2). Este rol existe únicamente para que Microsoft Entra emita un token solo de aplicación para la API de Fluid.

Registre una aplicación independiente para representar su automatización (se recomienda una por integración, para que cada una pueda vincularse y revocarse de forma independiente).

• En App registrations, seleccione + New registration.

• Name: algo descriptivo, por ejemplo Fluid Nightly Sync.

• Supported account types: Accounts in this organizational directory only.

• Deje Redirect URI en blanco y seleccione Register.

• En la página Overview, copie el Application (client) ID – esta es la identidad que Fluid asignará a una cuenta de servicio.

• Seleccione Certificates & secrets > + New client secret, agregue un secreto y copie inmediatamente el Value del secreto.

CONSEJO: Un certificado es más seguro que un secreto de cliente y se recomienda para producción. Puede cargar uno en Certificates & secrets > Certificates en lugar de crear un secreto.

• Aún dentro de la aplicación de automatización, seleccione API permissions > + Add a permission > My APIs.

• Elija su aplicación Fluid API.

• Seleccione Application permissions, marque Api.Access, y seleccione Add permissions.

• Seleccione Grant admin consent for [your organisation] y confirme. El estado del permiso debe mostrar una marca verde.

ADVERTENCIA: Los permisos de aplicación siempre requieren consentimiento del administrador. Sin el paso de Grant admin consent, su solicitud de token en la Parte 3 fallará.

ADVERTENCIA: No confunda los dos ID de aplicación (cliente). El token se solicita para el ID de cliente de la Fluid API (el recurso), pero Fluid vincula la cuenta de servicio al ID de cliente de la aplicación de automatización (el emisor de la llamada). Son valores distintos.

---

Dado que el vínculo reside dentro de Fluid, este paso lo realiza un Administrador del sistema Fluid (o el soporte de Fluid). Proporciónele:

• El ID de aplicación (cliente) de su aplicación de automatización (del Paso 2).

• La cuenta de servicio de Fluid como la que quiere que se ejecute la automatización – idealmente un usuario de Fluid dedicado, que no represente a una persona, creado para esta integración con el mínimo acceso que necesita.

Paso A. Crear (o confirmar) la cuenta de servicio de Fluid

1. En la Consola de Administración de Fluid, cree un usuario dedicado para la automatización (no reutilice la cuenta de una persona real). Por ejemplo, llámelo svc-power-automate con un nombre visible como Power Automate Service Account.

2. Asegúrese de que la cuenta esté activa y otórguele únicamente los permisos/roles de Fluid que el flujo necesita (privilegio mínimo).

3. Anote el nombre de usuario o correo electrónico de la cuenta — lo usará a continuación para encontrar su ID interno.

Paso B. Agregar el ID de cliente de su aplicación como nombre de usuario secundario de la cuenta de servicio de Fluid

1. Haga clic en su foto de perfil en la esquina superior derecha y elija User & Resource Management

2. Ubique la cuenta de usuario de Fluid que desea usar como la cuenta con la que quiere que se ejecute su automatización.

3. Haga clic en el usuario para editar sus datos

4. Junto al nombre de usuario, haga clic en el botón Add Username

5. Marque la casilla Is OAuth2 Client ID, e ingrese su Client ID, el valor n.º 3 de la tabla anterior

6. Haga clic en Save para guardar el ID de cliente y luego en Update para guardar los datos del usuario.

7. Ahora, cuando Power Automate envíe el token de autenticación, Fluid podrá hacer coincidir el token con un usuario y ejecutar la API usando esa cuenta de usuario.

ADVERTENCIA: Hasta que exista este vínculo, cada solicitud de la automatización se rechaza con 401 y un evento de seguridad ClientAppNotMapped. Esto es intencional – solo las aplicaciones explícitamente aprobadas pueden ejecutarse de forma desatendida.

---

Su automatización solicita a Entra un token solo de aplicación, dirigido a la Fluid API. Use el ámbito .default (construido a partir del Application ID URI de la Fluid API).

Solicitud 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

Ejemplo en 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: El scope debe ser api://{fluid-api-client-id}/.default – el identificador propio de la API de Fluid – no un nombre de ámbito personalizado. La audiencia del token es entonces la API de Fluid, que es lo que Fluid valida.

Envíe el token en el encabezado Authorization en cada solicitud:

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

Una llamada exitosa devuelve datos de Fluid (HTTP 200), ejecutándose como su cuenta de servicio asignada.

CONSEJO: Reutilice el token hasta que esté por expirar (típicamente ~60–75 minutos) en lugar de solicitar uno nuevo para cada llamada. Guárdelo en caché y renuévelo solo cuando sea necesario.

Las mismas dos solicitudes (obtener token, luego llamar a Fluid) funcionan desde cualquier host desatendido:

• Power Automate (desatendido) / Azure Logic Apps: use una acción HTTP para hacer POST al endpoint del token, guarde access_token en una variable, y luego use una segunda acción HTTP para llamar a https://yourcompany.fluid.work/api/... con Authorization: Bearer <token>. Guarde el secreto en Azure Key Vault y léalo con el conector de Key Vault en lugar de codificarlo directamente.

• Azure Functions / Web Jobs / servicios: use MSAL (ConfidentialClientApplication) con AcquireTokenForClient y el ámbito api://{fluid-api-client-id}/.default; se encarga de la caché y renovación del token por usted.

---

• Privilegio mínimo: otorgue a la cuenta de servicio de Fluid vinculada únicamente los permisos que la automatización necesita. La aplicación puede hacer cualquier cosa que esa cuenta pueda hacer.

• Una aplicación por integración: registre una aplicación de automatización independiente para cada integración, de modo que puedan supervisarse, rotarse y revocarse de forma independiente.

• Prefiera certificados antes que secretos de cliente para producción, y rote las credenciales según un calendario – la integración deja de funcionar en el momento en que un secreto/certificado expira.

• Almacene los secretos de forma segura (por ejemplo, Azure Key Vault); nunca los incorpore directamente en el código o en las definiciones de flujo.

• Supervise y revise: los intentos fallidos aparecen en Administration Console > Security Events en Fluid. Confirme periódicamente que cada aplicación asignada siga siendo necesaria, y elimine los vínculos que no lo sean.

• Revocar el acceso: para cortar de inmediato una automatización, elimine su vínculo en Fluid o deshabilite/elimine su aplicación de Entra (o su credencial).

---

---

• Para el lado de Fluid (habilitar OAuth 2.0, crear y vincular la cuenta de servicio, permisos), contacte a su Administrador del sistema Fluid o a su Gerente de cuenta de Fluid.

• Para el lado de Microsoft Entra (registro de aplicación, roles de aplicación, secretos/certificados, consentimiento de administrador), contacte a su administrador de Microsoft 365 / Azure.

• Excel y Power BI mediante OAuth 2.0

• Programar la actualización automática de Power BI desde Fluid OAuth 2.0

• Conectar Power Apps a Fluid mediante OAuth 2.0

• Configurar Power Automate para llamar a la API de Fluid mediante OAuth 2.0