Skip to content

Foundry IQ prerequisites

This is the shared baseline for every Foundry IQ knowledge source in GPT-RAG. Read this once before you enable your first Foundry IQ knowledge source. Each per-source how-to page lists only its own extra prerequisites on top of what is covered here.

If you have not read the Grounding sources overview yet, start there. It explains what a Knowledge Base and a Knowledge Source are and how GPT-RAG uses them.

Preview API

Foundry IQ uses the Azure AI Search agentic retrieval API. GPT-RAG pins the 2026-05-01-preview version. Preview features are provided without a service-level agreement and may change without notice. Do not depend on them for production workloads until they are generally available. See the Microsoft preview terms.

What GPT-RAG does for you

azd provision on GPT-RAG v3.0.2+ with AI Landing Zone v2.1.2+ handles the common Foundry IQ setup: it deploys a Foundry project, an Azure AI Search service with the knowledgeRetrieval billing plan enabled, assigns the RBAC roles listed below, creates the Knowledge Base, and seeds all the Foundry IQ App Configuration keys under the gpt-rag label.

If you used the default deployment path, most of this page is background information. The parts you may still need to act on yourself are:

  • Region selection before azd provision.
  • Feature flags gated by Microsoft (Work IQ, Web).
  • Per-source authorization steps for on-behalf-of (OBO) knowledge sources.
  • Choosing whether to enable a query planning LLM on the Knowledge Base.

Everything else on this page is what your deployment already has.

Before you start

  • An Azure subscription where you will deploy GPT-RAG.
  • Local roles on that subscription:
    • Contributor and User Access Administrator for the identity that runs azd provision. This is the deploy guide baseline.
  • A region that supports Azure AI Search agentic retrieval. See Azure AI Search regions list and pick a region with the "Agentic retrieval" column set. GPT-RAG's regional preflight will flag your choice before deployment starts.
  • Azure AI Search tier: Basic or higher. The Free tier does not support managed identity, which Foundry IQ needs to read the Knowledge Base and optionally to call the query planning LLM. See tier and pricing.

Foundry project and preview API

  • A Foundry project in the same subscription and region as your Search service. GPT-RAG deploys one for you through AI Landing Zone. To create one manually, see Create a Foundry project.
  • Preview API version FOUNDRY_IQ_API_VERSION=2026-05-01-preview. This is required for per-user permissions on native knowledge sources and for filterAddOn on the searchIndex knowledge source. See Foundry IQ documents for the full key list.

RBAC and permissions

Two distinct identities need permissions for Foundry IQ to work end to end:

  • The executor identity that provisions and manages Knowledge Bases and Knowledge Sources.
  • The runtime identities that call the Knowledge Base at query time: the GPT-RAG orchestrator managed identity and the Foundry project managed identity.

GPT-RAG's provisioning assigns these roles automatically. The table is here so you can verify them in the Azure portal or reproduce them in a locked-down subscription where you deploy manually.

Assignee Role Scope Why
Executor (user or SP running azd provision) Search Service Contributor Azure AI Search service Create and update the Knowledge Base and Knowledge Sources.
Executor Search Index Data Contributor Azure AI Search service Populate indexes generated by indexed knowledge sources.
Executor App Configuration Data Owner App Configuration store Write the gpt-rag-labeled keys.
Foundry project managed identity Search Index Data Reader Azure AI Search service Read Knowledge Base results.
Foundry project managed identity Search Service Contributor Azure AI Search service Create the AI Search connection used by the Knowledge Base.
Foundry project managed identity Storage Blob Data Reader GenAI storage account Read the documents container for the default Blob path.
Azure AI Search service managed identity Cognitive Services User Foundry account Call the Foundry model account (vectorizers and, if configured, the query planning LLM). Assigned by default.
Orchestrator container app managed identity Search Index Data Reader Azure AI Search service Query the Knowledge Base at runtime.
Orchestrator container app managed identity Cognitive Services OpenAI User Foundry account Call the model that generates the final answer.

Full role tables for every GPT-RAG component are in Deployment guide: role assignments.

For the underlying Microsoft-documented roles, see Create a Knowledge Base: prerequisites and Connect a Foundry IQ Knowledge Base to Foundry Agent Service: authentication and permissions.

Authorization model per knowledge source

Foundry IQ has two authorization patterns. Which one applies determines whether the source can serve anonymous chat and whether your users need to sign in.

Knowledge source kind Auth pattern Signed-in user required
azureBlob (Documents, default) App-only. Foundry IQ reads Blob using its own identity, with optional rbacScope or Purview labels for trimming. No.
searchIndex (custom ingestion path) App-only. Optional filterAddOn for GPT-RAG security fields. No.
indexedOneLake App-only. Foundry IQ managed identity reads the lakehouse. No.
indexedSharePoint App-only. Microsoft Graph Sites.Selected or Sites.Read.All on a registered Entra app. No per-user ACL trimming in this preview. No.
web (Grounding with Bing) App-only. No ACL. Billed per call. No.
mcpServer (generic MCP server) Registration is app-only. Endpoint authentication is separate and requires a compatible runtime for query-time headers. App-only managed identity and per-user OBO are distinct runtime token-acquisition options. See Generic MCP server. Only if you choose OBO for per-user endpoint authorization.
workIq On-behalf-of (OBO). Orchestrator forwards the user's delegated token in x-ms-query-source-authorization. Yes.
remoteSharePoint OBO through the Microsoft 365 Copilot Retrieval API. Yes.
fabricOntology OBO to Microsoft Fabric. Yes.
fabricDataAgent OBO to Microsoft Fabric. Yes.

For every OBO knowledge source, the orchestrator front end must be configured to forward a delegated token. This is the same plumbing that Auth and Doc Security describes for GPT-RAG's own security-trimmed retrieval. Each per-source page lists the specific tenant consent, delegated permissions, and licensing you need.

For mcpServer, do not confuse the orchestrator's managed identity with an OBO token. Managed identity is app-only and gives every user the same MCP authorization scope. OBO preserves the signed-in user's identity and only works when the MCP endpoint validates that delegated token. The optional queryHeaders metadata selects how a compatible orchestrator resolves the header and requires an explicit, non-secret scope for either mode. The provisioning change stores this metadata in App Configuration but never renders it into Search registration or retrieve parameters. Runtime resolution still requires a compatible orchestrator. See Generic MCP server.

Feature flags gated by Microsoft

Two knowledge sources require Microsoft-controlled enrollment before you can use them. GPT-RAG cannot enable these for you.

Knowledge source Gate Where to enable
Work IQ (workIq) Gated public preview. Requires the EnableFoundryIQWithWorkIQ subscription feature and one-time tenant admin consent for the Work IQ service principal. See Work IQ prerequisites.
Web (web) Requires the Microsoft.Search/WebKnowledgeSource subscription feature. Billed per Bing call. See Web grounding prerequisites.

Optional: query planning LLM

The Knowledge Base can call an Azure OpenAI model to plan queries and choose which knowledge sources to hit. GPT-RAG does not require you to configure this: at retrievalReasoningEffort=minimal (the current default) the Knowledge Base skips LLM planning entirely. Configure a planning model when:

  • You enable the web knowledge source. Web requires an LLM.
  • You enable one or more generic MCP server (mcpServer) sources. MCP requires low or medium reasoning so the planner can select a tool and generate its arguments. A compatible orchestrator must also use a messages-based retrieve request; see Generic MCP server.
  • You want low or medium reasoning effort so the Knowledge Base can select and blend across multiple sources.

Supported planning models on 2026-05-01-preview include gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.1, gpt-5.2, and the gpt-5.4 family. The authoritative list moves; check Supported models before pinning one.

The GPT-RAG orchestrator uses its own model for the final answer, configured through CHAT_DEPLOYMENT_NAME in App Configuration. That is separate from the Knowledge Base planning model. See Azure Direct Models for how to change it.

Configuration

Every Foundry IQ toggle lives in Azure App Configuration under the gpt-rag label, or as container environment variables when the deployment runs in containerEnv mode. GPT-RAG seeds the shared keys and each source's per-source keys, so you rarely start from an empty store. The lever that picks the default Blob path versus the custom searchIndex ingestion path is documented in Foundry IQ: Documents.

Common shared keys (defaults set by GPT-RAG):

Key Default Purpose
RETRIEVAL_BACKEND foundry_iq Select the Foundry IQ backend. Set to ai_search to roll back.
KNOWLEDGE_BASE_NAME Generated Foundry IQ Knowledge Base name.
KNOWLEDGE_BASE_ENDPOINT Generated Azure AI Search endpoint that hosts the Knowledge Base.
KNOWLEDGE_BASE_CONNECTION_ID Generated Foundry connection ID dedicated to the Knowledge Base.
FOUNDRY_IQ_API_VERSION 2026-05-01-preview Preview API version required for per-user permissions and filterAddOn.
FOUNDRY_IQ_KNOWLEDGE_RETRIEVAL_BILLING_PLAN free free or standard for the Azure AI Search agentic retrieval billing plan.
FOUNDRY_IQ_MAX_OUTPUT_DOCUMENTS 5 Cap on documents returned by the Knowledge Base per call.
FOUNDRY_IQ_MAX_RUNTIME_SECONDS 120 Per-request retrieval budget. OBO sources such as Work IQ can approach this budget.

Each per-source page documents its own keys in full.

Verify your baseline

Before you enable any Foundry IQ knowledge source, confirm the four items below on your deployment.

  1. RETRIEVAL_BACKEND=foundry_iq is set in App Configuration under the gpt-rag label.
  2. FOUNDRY_IQ_API_VERSION=2026-05-01-preview is set.
  3. The Foundry project, the Azure AI Search service, and the GenAI storage account are all in the same subscription and Entra tenant. In the Azure portal, open each resource and check the Subscription and Directory (tenant) properties match.
  4. The Search region shows "Agentic retrieval" in the Azure AI Search regions list.

If any of those are missing, fix them before you turn on a knowledge source.

© 2025 GPT-RAG — powered by ❤️ and coffee ☕