Configure your Foundry IQ (Azure AI Search) service in the Azure portal

Note

Foundry IQ (Azure AI Search) provides direct indexing and query APIs alongside higher-level knowledge source and knowledge base APIs for managed retrieval. Use the Azure portal, REST APIs, or Azure SDKs to configure these capabilities, or connect agents to knowledge bases in the Microsoft Foundry portal.

Configuring your new Foundry IQ (Azure AI Search) service involves several tasks to optimize security, access, and performance. This article provides a day-one checklist to help you set up your service in the Azure portal.

After you create a Foundry IQ service, we recommend that you:

Configure role-based access

Portal access is based on role assignments. By default, new Foundry IQ services have at least one service administrator or owner. Service administrators, co-administrators, and owners have permission to create more administrators and assign other roles. They also have access to all portal pages and operations on default Foundry IQ services.

Tip

By default, any administrator or owner can create or delete services. To prevent accidental deletions, consider locking your resources.

Each Foundry IQ service comes with API keys and uses key-based authentication by default. However, we recommend using Microsoft Entra ID and role-based access control (RBAC) for improved security. RBAC eliminates the need to store and pass API keys in plain text.

When you switch from key-based authentication to keyless authentication, service administrators must assign themselves data plane roles for full access to objects and data. These roles include Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader.

To configure role-based access:

  1. Enable roles on your Foundry IQ service. We recommend using both API keys and roles.

  2. Assign data plane roles to replace the functionality lost when you disable API keys. An owner only needs Search Index Data Reader, but developers need more roles.

    Role assignments can take several minutes to take effect. Until then, portal pages used for data plane operations display the following message:

    Screenshot of the portal message indicating insufficient permissions.

  3. Assign more roles for solution developers and apps.

Configure a managed identity

If you plan to use indexers for automated indexing, applied AI, or integrated vectorization, you should configure your Foundry IQ service to use a managed identity. You can then assign roles on other Azure services that authorize your Foundry IQ service to access data and operations.

For integrated vectorization, your Foundry IQ service identity needs the following roles:

  • Storage Blob Data Reader on Azure Storage
  • Cognitive Services Data User on a Microsoft Foundry resource

Role assignments can take several minutes to take effect.

Before you move on to network security, consider testing all points of connection to validate role assignments. Run an import wizard to test permissions.

Configure network security

By default, a Foundry IQ service accepts authenticated and authorized requests over public internet connections. You have two options for enhancing network security:

To learn about inbound and outbound calls in Foundry IQ, see Understand network traffic patterns.

Check capacity and understand billing

By default, a Foundry IQ service is created with one replica and one partition. You can add capacity by adding replicas and partitions, but we recommend waiting until volumes require it. Many customers run production workloads on the minimum configuration.

Semantic ranker and agentic retrieval are premium features that default to the free plan. If you need paid usage beyond the free allowance, see Enable or disable semantic ranker billing and Enable or disable agentic retrieval billing.

To learn about other features that affect billing, see Plan and manage costs of a Foundry IQ service.

Enable diagnostic logging

Enable diagnostic logging to track user activity. If you skip this step, you still get activity logs and platform metrics automatically. However, if you want index and query usage information, you should enable diagnostic logging and choose a destination for logged operations. We recommend Log Analytics Workspace for durable storage so that you can run system queries in the Azure portal.

Internally, Microsoft collects telemetry data about your service and the platform. To learn more about data retention, see Retention of metrics.

To learn more about data location and privacy, see Data residency.

Provide connection information to developers

To connect to Foundry IQ, developers need:

  • An endpoint or URL from the Overview page.
  • An API key from the Keys page or a role assignment. We recommend Search Service Contributor, Search Index Data Contributor, and Search Index Data Reader.

We recommend portal access for the Import data wizard and Search explorer. You must be a Contributor or higher to run the wizard.

For programmatic support for service administration, see the following APIs and modules:

You can also use the management client libraries in the Azure SDKs for .NET, Python, Java, and JavaScript.

There's feature parity across all modalities and languages, except for preview management features. As a general rule, preview management features are released through the Management REST API first.