From 290d3bd19c3b25de5c588e6fb26edda0c1d1e49f Mon Sep 17 00:00:00 2001 From: jottakka Date: Wed, 8 Jul 2026 18:46:04 -0300 Subject: [PATCH 1/3] docs: add Microsoft Power BI OAuth provider page Document the dedicated Microsoft Power BI auth provider (well-known id `microsoft-powerbi`): a Power BI Service OAuth provider that reuses Microsoft Entra endpoints on a separate connection so Power BI resource scopes never mix with Microsoft Graph scopes (the mix trips Entra AADSTS70011). Mirrors the Microsoft provider page structure and covers: Entra app registration, the Arcade-generated redirect URI, granting Power BI Service delegated permissions only (Dataset.Read.All, Dataset.ReadWrite.All, Report.Read.All, Workspace.Read.All plus openid/profile/offline_access) and NOT any Graph or Fabric permission, configuring the provider in the dashboard with an empty Scopes field and client id + secret only, and using it from app code and custom tools. Adds the provider to the auth-providers catalog page. The sidebar title resolves from the page frontmatter title and sorts alphabetically next to Microsoft (matching the cisco-duo precedent), so no _meta.tsx change is needed. Co-Authored-By: Claude Opus 4.8 --- .../auth-providers/microsoft-powerbi/page.mdx | 240 ++++++++++++++++++ app/en/references/auth-providers/page.mdx | 7 + 2 files changed, 247 insertions(+) create mode 100644 app/en/references/auth-providers/microsoft-powerbi/page.mdx diff --git a/app/en/references/auth-providers/microsoft-powerbi/page.mdx b/app/en/references/auth-providers/microsoft-powerbi/page.mdx new file mode 100644 index 000000000..109bc80a8 --- /dev/null +++ b/app/en/references/auth-providers/microsoft-powerbi/page.mdx @@ -0,0 +1,240 @@ +--- +title: Microsoft Power BI +description: Authorize tools and agents with the Power BI Service on behalf of a user +--- + +import { Tabs, Callout, Steps } from "nextra/components"; + +# Microsoft Power BI + + + Microsoft Power BI is a **dedicated** Microsoft auth provider, separate from the + general-purpose [Microsoft](/references/auth-providers/microsoft) (Graph) provider. + To use it, create a custom auth provider of type **Microsoft Power BI** with your + own Microsoft Entra (Azure AD) OAuth 2.0 credentials as described below. + + +The Microsoft Power BI auth provider enables tools and agents to call the [Power BI REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/) on behalf of a user. + +It authorizes against the **Power BI Service** resource (`https://analysis.windows.net/powerbi/api`) and reuses Microsoft's Entra ID endpoints, but on its own connection. Keeping Power BI on a dedicated provider means its resource scopes never mix with the Microsoft Graph scopes used by the general-purpose Microsoft provider. Requesting Power BI and Graph scopes together in a single authorize request mixes token audiences and causes Microsoft Entra to reject the sign-in with **AADSTS70011** (`The provided value for the input parameter scope is not valid`). + +### What's documented here + +This page describes how to use and configure Microsoft Power BI auth with Arcade. + +This auth provider is used by: + +- The Arcade **Power BI MCP Server**, which discovers workspaces, datasets, and reports; inspects and queries semantic models with DAX; and manages dataset refreshes +- Your [app code](#using-microsoft-power-bi-auth-in-app-code) that needs to call Power BI REST APIs +- Or, your [custom tools](#using-microsoft-power-bi-auth-in-custom-tools) that need to call Power BI REST APIs + + + **Power BI Service scopes only.** The Entra app behind this provider must carry + Power BI Service delegated permissions and nothing else. Do not add a Microsoft + Graph permission (e.g. `User.Read`) or a Microsoft Fabric permission + (`api.fabric.microsoft.com`). Any non–Power BI scope mixes token audiences on the + Power BI connection and triggers **AADSTS70011** at authorize time. + + +## Configuring Microsoft Power BI auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Microsoft app credentials. This way, your users will see your application's name requesting permission. + +Before showing how to configure your Power BI app credentials, let's go through the steps to create a Microsoft Entra app. + +### Create a Microsoft Entra app + +- Follow Microsoft's guide to [registering an app with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). +- Set the redirect URL to the redirect URL generated by Arcade (see below). +- Under **API permissions**, add the **Power BI Service** delegated permissions listed in the [section below](#power-bi-service-scopes) — and only those. Then **Grant admin consent** for the permissions. +- Copy the client ID and client secret to use below. + + + Do not add any Microsoft Graph or Microsoft Fabric permission to this app. If you + previously added one (or changed any permission), delete and recreate the user's + connection in Arcade after fixing the app so a fresh, single-resource token is + minted. + + +### Power BI Service scopes + +Add the following **Power BI Service** (`https://analysis.windows.net/powerbi/api`) delegated permissions to your Entra app. These cover the permissions used by the Arcade Power BI MCP Server: + +| Permission | Used for | +| ----------------------- | ------------------------------------------------- | +| `Workspace.Read.All` | Listing workspaces and reading the signed-in user | +| `Dataset.Read.All` | Listing datasets, reading schemas, running DAX | +| `Dataset.ReadWrite.All` | Triggering dataset refreshes | +| `Report.Read.All` | Listing and reading reports | + +In addition, add the standard OpenID Connect permissions `openid`, `profile`, and `offline_access` (the last is required to issue refresh tokens). + + + Individual tools request only the specific Power BI scope each endpoint needs at + call time. You do not configure scopes on the Arcade provider itself (see below). + Write capability is governed entirely by the user's OAuth scopes: a user without a + `*.ReadWrite.All` permission receives a `403` from the API on a write call. + + +To enable schema inspection and DAX queries, an administrator must also turn on the **Dataset Execute Queries REST API** tenant setting (a.k.a. _Semantic Model Execute Queries_) in the Power BI admin portal. + +Next, add the Power BI app to Arcade. + +## Configuring your own Microsoft Power BI Auth Provider in Arcade + + + + +### Configure Microsoft Power BI Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **Microsoft Power BI**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-powerbi-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Microsoft Entra app. +- **Leave the Scopes field empty.** Each tool requests its own Power BI scopes at call time; the provider carries only the client ID and secret. Entering scopes here can send Entra a mixed or invalid scope set in one authorize request and trigger **AADSTS70011**. +- Note the **Redirect URL** generated by Arcade. This must be set as your Microsoft Entra app's redirect URL. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + +When you use tools that require Microsoft Power BI auth using your Arcade account credentials, Arcade will automatically use this provider. If you have multiple Microsoft Power BI providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + + +## Using Microsoft Power BI auth in app code + +Use the Microsoft Power BI auth provider in your own agents and AI apps to get a user token for the Power BI REST API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works. + +Use `client.auth.start()` with the `microsoft-powerbi` provider to get a user token for Power BI APIs: + + + + +```python {8-16} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="microsoft-powerbi", + scopes=[ + "https://analysis.windows.net/powerbi/api/Workspace.Read.All", + "https://analysis.windows.net/powerbi/api/Dataset.Read.All", + ], +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# TODO: Do something interesting with the token... +``` + + + + + +```javascript {8-13} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +let authResponse = await client.auth.start(userId, "microsoft-powerbi", { + scopes: [ + "https://analysis.windows.net/powerbi/api/Workspace.Read.All", + "https://analysis.windows.net/powerbi/api/Dataset.Read.All", + ], +}); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// TODO: Do something interesting with the token... +``` + + + + + +## Using Microsoft Power BI auth in custom tools + +You can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Power BI REST API. + +Power BI is a Microsoft provider with a distinct `provider_id`, so mark a tool as requiring it by subclassing the `Microsoft` auth class and overriding `provider_id` to `microsoft-powerbi`. This routes authorization to your dedicated Power BI provider and keeps the connection on Power BI Service tokens only. The `context.authorization.token` field will be automatically populated with the user's Power BI token: + +```python {8-11,15-19,26} +from typing import Annotated + +import httpx + +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import Microsoft + + +class MicrosoftPowerBI(Microsoft): + """Microsoft OAuth bound to the dedicated `microsoft-powerbi` provider.""" + + provider_id: str = "microsoft-powerbi" + + +@tool( + requires_auth=MicrosoftPowerBI( + scopes=["https://analysis.windows.net/powerbi/api/Dataset.Read.All"], + ) +) +async def list_datasets( + context: ToolContext, + group_id: Annotated[str, "The ID of the workspace to list datasets from"], +) -> Annotated[dict, "The datasets in the workspace"]: + """List the datasets in a Power BI workspace.""" + url = f"https://api.powerbi.com/v1.0/myorg/groups/{group_id}/datasets" + headers = {"Authorization": f"Bearer {context.authorization.token}"} + + async with httpx.AsyncClient() as client: + response = await client.get(url=url, headers=headers) + response.raise_for_status() + return response.json() +``` diff --git a/app/en/references/auth-providers/page.mdx b/app/en/references/auth-providers/page.mdx index edbdfaa0c..907eb9ece 100644 --- a/app/en/references/auth-providers/page.mdx +++ b/app/en/references/auth-providers/page.mdx @@ -99,6 +99,13 @@ For more information on how to customize your auth provider, select an auth prov link="/references/auth-providers/microsoft" category="Auth" /> + Date: Wed, 8 Jul 2026 21:47:19 +0000 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=A4=96=20Regenerate=20LLMs.txt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- public/llms.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/public/llms.txt b/public/llms.txt index bd4c1058e..1edc542c5 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -1,4 +1,4 @@ - + # Arcade @@ -39,6 +39,7 @@ Arcade delivers three capabilities. Enforce (Agent Authorization): deploy agents - [LinkedIn](https://docs.arcade.dev/en/references/auth-providers/linkedin): This documentation page provides guidance on configuring and using the LinkedIn authentication provider within Arcade, enabling applications and custom tools to access LinkedIn APIs on behalf of users. It outlines the necessary steps to create a LinkedIn app, set up app credentials, and - [Mailchimp](https://docs.arcade.dev/en/references/auth-providers/mailchimp): This documentation page provides guidance on configuring the Mailchimp authentication provider for use with Arcade, enabling users to access Mailchimp Marketing APIs through OAuth 2.0. It includes steps for creating a Mailchimp app, registering it, and integrating it with Arcade - [Microsoft](https://docs.arcade.dev/en/references/auth-providers/microsoft): This documentation page provides guidance on how to create and configure a custom Microsoft Auth Provider for use with Arcade, enabling applications and tools to access the Microsoft Graph API on behalf of users. It outlines the steps for registering a Microsoft app, setting necessary permissions, +- [Microsoft Power BI](https://docs.arcade.dev/en/references/auth-providers/microsoft-powerbi): Documentation page - [Middleware](https://docs.arcade.dev/en/references/mcp/python/middleware): This documentation page provides an overview of middleware in the Arcade MCP Python framework, detailing how to intercept and modify requests and responses during processing. It introduces the base `Middleware` class for creating custom middleware, explains the `MiddlewareContext` for managing message data - [Miro](https://docs.arcade.dev/en/references/auth-providers/miro): This documentation page provides guidance on configuring the Miro authentication provider using OAuth 2.0, enabling users to integrate Miro APIs into their applications or tools. It outlines the steps for creating a Miro app, obtaining necessary credentials, and setting up - [Notion](https://docs.arcade.dev/en/references/auth-providers/notion): This documentation page provides guidance on configuring and using the Notion authentication provider with Arcade, enabling users to call Notion APIs on behalf of their users. It outlines the steps to create a Notion app, configure OAuth settings in the Arcade dashboard, and From 80f55b364c719538b715606103e3fcbbf41ca606 Mon Sep 17 00:00:00 2001 From: jottakka Date: Fri, 10 Jul 2026 16:03:26 -0300 Subject: [PATCH 3/3] docs: move OAuth internals to an advanced section at the bottom Keep the setup path simple: the intro, Entra-app steps, and dashboard steps now state what to do in plain language, while token audiences, AADSTS70011, resource URIs, and connection-reset troubleshooting move to a clearly flagged 'Advanced' section at the end of the page. Co-Authored-By: Claude Fable 5 --- .../auth-providers/microsoft-powerbi/page.mdx | 69 +++++++++++-------- 1 file changed, 42 insertions(+), 27 deletions(-) diff --git a/app/en/references/auth-providers/microsoft-powerbi/page.mdx b/app/en/references/auth-providers/microsoft-powerbi/page.mdx index 109bc80a8..e32972243 100644 --- a/app/en/references/auth-providers/microsoft-powerbi/page.mdx +++ b/app/en/references/auth-providers/microsoft-powerbi/page.mdx @@ -8,15 +8,15 @@ import { Tabs, Callout, Steps } from "nextra/components"; # Microsoft Power BI - Microsoft Power BI is a **dedicated** Microsoft auth provider, separate from the - general-purpose [Microsoft](/references/auth-providers/microsoft) (Graph) provider. - To use it, create a custom auth provider of type **Microsoft Power BI** with your + Microsoft Power BI is a **dedicated** auth provider, separate from the + general-purpose [Microsoft](/references/auth-providers/microsoft) provider. To + use it, create a custom auth provider of type **Microsoft Power BI** with your own Microsoft Entra (Azure AD) OAuth 2.0 credentials as described below. The Microsoft Power BI auth provider enables tools and agents to call the [Power BI REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/) on behalf of a user. -It authorizes against the **Power BI Service** resource (`https://analysis.windows.net/powerbi/api`) and reuses Microsoft's Entra ID endpoints, but on its own connection. Keeping Power BI on a dedicated provider means its resource scopes never mix with the Microsoft Graph scopes used by the general-purpose Microsoft provider. Requesting Power BI and Graph scopes together in a single authorize request mixes token audiences and causes Microsoft Entra to reject the sign-in with **AADSTS70011** (`The provided value for the input parameter scope is not valid`). +Power BI has its own provider so that its permissions stay separate from the Microsoft Graph permissions used by the general-purpose Microsoft provider. Mixing the two breaks authorization — if you want to know why, see [Advanced: token audiences and troubleshooting](#advanced-token-audiences-and-troubleshooting) at the end of this page. ### What's documented here @@ -28,14 +28,6 @@ This auth provider is used by: - Your [app code](#using-microsoft-power-bi-auth-in-app-code) that needs to call Power BI REST APIs - Or, your [custom tools](#using-microsoft-power-bi-auth-in-custom-tools) that need to call Power BI REST APIs - - **Power BI Service scopes only.** The Entra app behind this provider must carry - Power BI Service delegated permissions and nothing else. Do not add a Microsoft - Graph permission (e.g. `User.Read`) or a Microsoft Fabric permission - (`api.fabric.microsoft.com`). Any non–Power BI scope mixes token audiences on the - Power BI connection and triggers **AADSTS70011** at authorize time. - - ## Configuring Microsoft Power BI auth @@ -54,19 +46,20 @@ Before showing how to configure your Power BI app credentials, let's go through - Follow Microsoft's guide to [registering an app with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). - Set the redirect URL to the redirect URL generated by Arcade (see below). -- Under **API permissions**, add the **Power BI Service** delegated permissions listed in the [section below](#power-bi-service-scopes) — and only those. Then **Grant admin consent** for the permissions. +- Under **API permissions**, add the **Power BI Service** delegated permissions listed in the [section below](#power-bi-service-scopes). Then **Grant admin consent** for the permissions. - Copy the client ID and client secret to use below. - Do not add any Microsoft Graph or Microsoft Fabric permission to this app. If you - previously added one (or changed any permission), delete and recreate the user's - connection in Arcade after fixing the app so a fresh, single-resource token is - minted. + Add **only** the Power BI Service permissions listed below to this app — do + not add permissions from other Microsoft APIs, such as Microsoft Graph's + `User.Read`. Mixing permissions from different Microsoft APIs on this app + causes sign-in failures (see the [Advanced + section](#advanced-token-audiences-and-troubleshooting)). ### Power BI Service scopes -Add the following **Power BI Service** (`https://analysis.windows.net/powerbi/api`) delegated permissions to your Entra app. These cover the permissions used by the Arcade Power BI MCP Server: +Add the following **Power BI Service** delegated permissions to your Entra app. These cover the permissions used by the Arcade Power BI MCP Server: | Permission | Used for | | ----------------------- | ------------------------------------------------- | @@ -77,13 +70,6 @@ Add the following **Power BI Service** (`https://analysis.windows.net/powerbi/ap In addition, add the standard OpenID Connect permissions `openid`, `profile`, and `offline_access` (the last is required to issue refresh tokens). - - Individual tools request only the specific Power BI scope each endpoint needs at - call time. You do not configure scopes on the Arcade provider itself (see below). - Write capability is governed entirely by the user's OAuth scopes: a user without a - `*.ReadWrite.All` permission receives a `403` from the API on a write call. - - To enable schema inspection and DAX queries, an administrator must also turn on the **Dataset Execute Queries REST API** tenant setting (a.k.a. _Semantic Model Execute Queries_) in the Power BI admin portal. Next, add the Power BI app to Arcade. @@ -113,7 +99,7 @@ To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://a - Choose a unique **ID** for your provider (e.g. "my-powerbi-provider"). - Optionally enter a **Description**. - Enter the **Client ID** and **Client Secret** from your Microsoft Entra app. -- **Leave the Scopes field empty.** Each tool requests its own Power BI scopes at call time; the provider carries only the client ID and secret. Entering scopes here can send Entra a mixed or invalid scope set in one authorize request and trigger **AADSTS70011**. +- **Leave the Scopes field empty.** Each tool requests the scopes it needs when it runs, so the provider only carries your credentials (see [why](#advanced-token-audiences-and-troubleshooting)). - Note the **Redirect URL** generated by Arcade. This must be set as your Microsoft Entra app's redirect URL. #### Create the provider @@ -203,7 +189,7 @@ const token = authResponse.context.token; You can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Power BI REST API. -Power BI is a Microsoft provider with a distinct `provider_id`, so mark a tool as requiring it by subclassing the `Microsoft` auth class and overriding `provider_id` to `microsoft-powerbi`. This routes authorization to your dedicated Power BI provider and keeps the connection on Power BI Service tokens only. The `context.authorization.token` field will be automatically populated with the user's Power BI token: +Power BI is a Microsoft provider with its own `provider_id`, so mark a tool as requiring it by subclassing the `Microsoft` auth class and overriding `provider_id` to `microsoft-powerbi`. The `context.authorization.token` field will be automatically populated with the user's Power BI token: ```python {8-11,15-19,26} from typing import Annotated @@ -238,3 +224,32 @@ async def list_datasets( response.raise_for_status() return response.json() ``` + +## Advanced: token audiences and troubleshooting + + + **For advanced users.** You do not need this section to complete the setup + above. Read it if you want to understand why Power BI needs a dedicated + provider, or if you are troubleshooting an authorization error such as + **AADSTS70011**. + + +### Why Power BI needs its own provider + +The Power BI provider authorizes against the **Power BI Service** resource (`https://analysis.windows.net/powerbi/api`). It reuses Microsoft's Entra ID endpoints, but on its own connection, separate from the general-purpose [Microsoft](/references/auth-providers/microsoft) provider. + +A Microsoft Entra access token is issued for a single resource (its _audience_). Power BI Service and Microsoft Graph are different resources, so a single authorize request cannot mix scopes from both: Entra rejects the sign-in with **AADSTS70011** (`The provided value for the input parameter scope is not valid`). Keeping Power BI on a dedicated provider guarantees every authorize request on that connection carries Power BI Service scopes only. + +For the same reason, the Entra app behind this provider must carry Power BI Service delegated permissions and nothing else. Do not add a Microsoft Graph permission (e.g. `User.Read`) or a Microsoft Fabric permission (`api.fabric.microsoft.com`) — any non–Power BI scope mixes token audiences on the Power BI connection and triggers **AADSTS70011** at authorize time. + +### Why the provider's Scopes field stays empty + +Individual tools request only the specific Power BI scope each endpoint needs at call time, so the Arcade provider itself carries only the client ID and secret. Entering scopes on the provider can send Entra a mixed or invalid scope set in one authorize request and trigger **AADSTS70011**. + +Write capability is governed entirely by the user's OAuth scopes: a user without a `*.ReadWrite.All` permission receives a `403` from the API on a write call. + +### Troubleshooting + +- **AADSTS70011 at authorize time.** The scope set in the authorize request mixes resources or is malformed. Check that the Entra app carries only Power BI Service permissions and that the provider's Scopes field is empty. +- **Errors after changing the Entra app's permissions.** If you added or removed a permission on the Entra app (including removing a stray Graph or Fabric permission), delete and recreate the user's connection in Arcade so a fresh, single-resource token is minted. +- **`403` on a write call.** The user's token is missing the corresponding `*.ReadWrite.All` scope. Re-authorize with the required scope.