Add a Foundry IQ (Azure AI Search) service to a network security perimeter

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.

A network security perimeter is a logical network boundary around your platform as a service (PaaS) resources that you deploy outside of a virtual network. It establishes a perimeter for controlling public network access to resources like Foundry IQ (Azure AI Search), Azure Storage, and Azure OpenAI in Microsoft Foundry Models.

This article explains how to join a Foundry IQ service to a network security perimeter to control network access to your Foundry IQ service. By joining a network security perimeter, you can:

  • Log all access to your Foundry IQ service in context with other Azure resources in the same perimeter.
  • Block any data exfiltration from a Foundry IQ service to other services outside the perimeter.
  • Allow access to your Foundry IQ service by using the inbound and outbound access capabilities of the network security perimeter.

You can add a Foundry IQ service to a network security perimeter in the Azure portal, as described in this article. Alternatively, use the Search Management REST APIs to view and synchronize the configuration settings.

Prerequisites

  • An existing network security perimeter. You can create one to associate with your Foundry IQ service.

  • Foundry IQ on a supported Dedicated tier or the Serverless tier, in any region.

  • Azure role assignments: Network Security Perimeter Contributor on the perimeter (or its resource group or subscription) to create and manage the perimeter, profiles, access rules, and associations. Search Service Contributor (or Contributor) on the Foundry IQ service to associate it with a perimeter. For more information, see What is a network security perimeter?.

  • If you plan to use indexers, configure the Foundry IQ service with a system- or user-assigned managed identity and assign the identity an appropriate data-plane role on each data source.

Limitations

The network security perimeter controls public-endpoint access. It isn't an outbound shared private link and doesn't enable shared private links on S3 HD or Serverless. An inbound private endpoint to Search is a separate control. See Network security for agentic retrieval.

Outbound access to Microsoft Foundry resources

A network security perimeter can govern supported outbound calls between your Foundry IQ service and a Microsoft Foundry resource. Perimeter access rules don't by themselves establish a Private Link route. Review the requirements for each workload that calls the resource:

To configure perimeter access:

  1. Add both your Foundry IQ service and the Foundry resource to the same network security perimeter, or to perimeters that allow communication between them.

  2. If both resources are in the same perimeter and the Foundry IQ service authenticates to the Foundry resource by using a managed identity, you don't need to add an outbound rule. Intra-perimeter traffic is allowed implicitly. If the resources are in different perimeters, or the Foundry IQ service authenticates with API keys, add an outbound FQDN access rule on the perimeter associated with your Foundry IQ service that targets the Foundry resource's hostname. For guidance on the Foundry side of the configuration, see Add Microsoft Foundry to a network security perimeter.

  3. Validate access in two stages:

    1. With the perimeter in learning mode, run a skillset, vectorizer query, or agentic retrieval call that invokes the Foundry resource. Review the perimeter logs to confirm the expected access path.

    2. Switch to enforced mode and rerun the same operation. Confirm success in indexer execution history and in the perimeter's outbound allow logs.

Network security perimeter (NSP) support for Microsoft.CognitiveServices resources of kind AIServices (Microsoft Foundry) is generally available. NSP support for resources of kind OpenAI (Azure OpenAI Service) is in public preview. For the current support list, see Onboarded private link resources.

On eligible Search tiers and workloads, shared private link to the Foundry resource is a separate private-endpoint option. Don't infer a private route or a fallback policy for every model provider from perimeter membership.

Assign a Foundry IQ service to a network security perimeter

Associate your Foundry IQ service with a perimeter so that all indexing and query traffic is governed by perimeter rules.

Tip

For automation, use the Search Management REST APIs instead of the portal. For more information, see Manage your Foundry IQ service using REST APIs.

  1. In the Azure portal, find the network security perimeter service for your subscription.

  2. From the left pane, select Settings > Associated resources.

    Screenshot of the network security perimeter left-hand menu.

  3. Select Add > Associate resources with an existing profile.

    Screenshot of network security perimeter associate resource button.

  4. Select the profile you created when you created the network security perimeter for Profile.

  5. Select Add, and then select your Foundry IQ service.

    Screenshot of network security perimeter associate resource button with the select resource screen.

  6. Select Associate in the lower-left corner to create the association.

Remove a Foundry IQ service from a network security perimeter

To disassociate a Foundry IQ service from a perimeter:

  1. Go to your network security perimeter resource in the Azure portal.

  2. From the left pane, select Settings > Associated resources.

  3. Find your Foundry IQ service in the table, select the three dots at the end of the row, and then select Remove association.

  4. Confirm the removal. After the association is removed, perimeter rules no longer apply to the Foundry IQ service, and the publicNetworkAccess setting on the Foundry IQ service again controls inbound traffic.

Network security perimeter access modes

Network security perimeter supports two different access modes for associated resources:

Mode Description
Learning mode This is the default access mode. In learning mode, network security perimeter logs all traffic to the Foundry IQ service that would be denied if the perimeter is in enforced mode. This access mode allows network administrators to understand the existing access patterns of the Foundry IQ service before implementing enforcement of access rules.
Enforced mode In enforced mode, network security perimeter logs and denies all traffic that isn't explicitly allowed by access rules.

Network security perimeter and Foundry IQ service networking settings

The publicNetworkAccess setting determines Foundry IQ service association with a network security perimeter.

  • In learning mode, the publicNetworkAccess setting controls public access to the resource.

  • In enforced mode, the network security perimeter rules override the publicNetworkAccess setting. For example, if a Foundry IQ service with a publicNetworkAccess setting of enabled is associated with a network security perimeter in enforced mode, access to the Foundry IQ service is still controlled by network security perimeter access rules.

Change the network security perimeter access mode

  1. Go to your network security perimeter resource in the Azure portal.

  2. From the left pane, select Settings > Associated resources.

    Screenshot of the network security perimeter left-hand menu.

  3. Find your Foundry IQ service in the table.

  4. Select the three dots at the end of the row, and then select Change access mode.

    Screenshot of the change access mode button in the network security perimeter portal.

  5. Select your desired access mode, and then select Apply.

    Screenshot of the change access mode button in the network security perimeter portal with the access modes displayed.

Enable logging network access

  1. Go to your network security perimeter resource in the Azure portal.

  2. From the left pane, select Monitoring > Diagnostic settings.

    Screenshot of left-hand menu in the network security perimeter portal.

  3. Select Add diagnostic setting.

  4. Enter any name, such as diagnostic, for Diagnostic setting name.

  5. Under Logs, select allLogs. allLogs ensures all inbound and outbound network access to resources in your network security perimeter is logged.

  6. Under Destination details, select Archive to a storage account or Send to Log Analytics workspace. The storage account must be in the same region as the network security perimeter. You can either use an existing storage account or create a new one. A Log Analytics workspace can be in a different region than the one used by the network security perimeter. You can also select any of the other applicable destinations.

    Screenshot of a filled out diagnostic settings in the network security perimeter portal.

  7. Select Save to create the diagnostic setting and start logging network access.

  8. To verify logging is active, generate traffic to the Foundry IQ service (for example, run a query). Within about 10 minutes, query the NSPAccessLogs table in Log Analytics or check the corresponding insights-logs-* container in the storage account.

Read network access logs

Network security perimeter logs are delivered to the destinations you selected in Diagnostic settings. The most common destinations are a Log Analytics workspace and a storage account.

Log Analytics workspace

The NSPAccessLogs table contains all the logs for every log category, such as NspPublicInboundPerimeterRulesAllowed. Each log contains a record of the network security perimeter network access that matches the log category.

Here's an example of the NspPublicInboundPerimeterRulesAllowed log format:

Column name Meaning Example value
ResultDescription Name of the network access operation. POST /indexes/my-index/docs/search
Profile Which network security perimeter the Foundry IQ service was associated with. defaultProfile
ServiceResourceId Resource ID of the Foundry IQ service. search-service-resource-id
Matched Rule JSON description of the rule that the log matched. { "accessRule": "IP firewall" }
SourceIPAddress Source IP of the inbound network access, if applicable. 192.0.2.1
AccessRuleVersion Version of the network security perimeter access rules used to enforce the network access rules. 0

Storage account

The storage account has containers for every log category, such as insights-logs-nsppublicinboundperimeterrulesallowed. The folder structure inside the container matches the resource ID of the network security perimeter and the time the logs were taken. Each line on the JSON log file contains a record of the network security perimeter network access that matches the log category.

For example, the inbound perimeter rules allowed category log uses the following format:

{
    "properties": {
        "ServiceResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/network-security-perimeter/providers/Microsoft.Search/searchServices/network-security-perimeter-search",
        "Profile": "defaultProfile",
        "MatchedRule": {
            "AccessRule": "myaccessrule"
        },
        "Source": {
            "IpAddress": "192.0.2.1"
        }
    }
}

Add an access rule for your Foundry IQ service

A network security perimeter profile specifies rules that allow or deny access through the perimeter.

Within the perimeter, all resources have mutual access at the network level. You must still set up authentication and authorization, but at the network level, connection requests from inside the perimeter are accepted.

For resources outside of the network security perimeter, you must specify inbound and outbound access rules. Inbound rules specify which connections to allow in, and outbound rules specify which requests are allowed out.

A Foundry IQ service accepts inbound requests from apps like the Microsoft Foundry portal and any app that sends indexing or query requests. A Foundry IQ service sends outbound requests during indexer-based indexing and skillset execution. This section explains how to set up inbound and outbound access rules for Foundry IQ scenarios.

Note

When the Foundry IQ service authenticates by using a managed identity and Microsoft Entra-based role assignments, traffic between resources in the same network security perimeter is allowed implicitly at the network level. If the Foundry IQ service authenticates with API keys, the perimeter can't identify the traffic as intra-perimeter, so you must add explicit inbound and outbound access rules even when both resources are in the same perimeter.

Add an inbound access rule

Inbound access rules can allow the internet and resources outside the perimeter to connect with resources inside the perimeter.

Network security perimeter supports two types of inbound access rules:

  • IP address ranges. IP addresses or ranges must be in the Classless Inter-Domain Routing (CIDR) format. An example of CIDR notation is 192.0.2.0/24, which represents the IPs that range from 192.0.2.0 to 192.0.2.255. This type of rule allows inbound requests from any IP address within the range.

  • Subscriptions. This type of rule allows inbound access authenticated by using any managed identity from the subscription. The rule controls the network path only; the caller still needs an Azure RBAC role assignment on the Foundry IQ service.

To add an inbound access rule in the Azure portal:

  1. Go to your network security perimeter resource in the Azure portal.

  2. From the left pane, select Settings > Profiles.

    Screenshot of the left hand menu with profiles selected.

  3. Select the profile you're using with your network security perimeter.

    Screenshot of selecting the profile from network security perimeter.

  4. From the left pane, select Settings > Inbound access rules.

    Screenshot of the left hand menu with inbound access rules selected.

  5. Select Add.

    Screenshot of add inbound network security perimeter access rule button.

  6. Enter or select the following values:

    Setting Value
    Rule name The name for the inbound access rule, such as MyInboundAccessRule.
    Source type Valid values are IP address ranges or Subscriptions.
    Allowed sources If you selected IP address ranges, enter the IP address range in CIDR format that you want to allow inbound access from. Download the Azure IP Ranges and Service Tags file. If you selected Subscriptions, use the subscription you want to allow inbound access from.
  7. Select Add to create the inbound access rule.

    Screenshot of add inbound network security perimeter access rule screen filled out.

  8. To verify the rule, switch the association to enforced mode in a test profile. Confirm matching requests appear in the NspPublicInboundPerimeterRulesAllowed log category and non-matching requests appear in the NspPublicInboundPerimeterRulesDenied category.

Add an outbound access rule

A Foundry IQ service makes outbound calls during indexer-based indexing and skillset execution. If your indexer data sources, an attached Microsoft Foundry resource for Foundry Tools billing skills, or custom skill logic is outside the network security perimeter, create an outbound access rule that allows your Foundry IQ service to make the connection.

Within the security perimeter, indexers can connect to Azure Blob Storage, Azure Cosmos DB for NoSQL, and Azure SQL Database. If your indexers use other data sources, you need an outbound access rule to support that connection.

The network security perimeter supports outbound access rules based on the Fully Qualified Domain Name (FQDN) of the destination. For example, you can allow outbound access from any service associated with your network security perimeter to an FQDN such as mystorageaccount.blob.core.windows.net.

To add an outbound access rule in the Azure portal:

  1. Go to your network security perimeter resource in the Azure portal.

  2. From the left pane, select Settings > Profiles.

    Screenshot of the left hand menu with profiles option selected.

  3. Select the profile you're using with your network security perimeter.

    Screenshot of selecting the profile from network security perimeter.

  4. From the left pane, select Settings > Outbound access rules.

    Screenshot of selecting the outbound access rules in the left-hand menu.

  5. Select Add.

    Screenshot of adding the outbound access rule in network security perimeter.

  6. Enter or select the following values:

    Setting Value
    Rule name The name for the outbound access rule, such as MyOutboundAccessRule.
    Destination type Leave as FQDN.
    Allowed destinations Enter a comma-separated list of FQDNs you want to allow outbound access to.
  7. Select Add to create the outbound access rule.

    Screenshot of adding the outbound access rule in network security perimeter with filled out options.

  8. To verify the rule, switch the association to enforced mode in a test profile. Confirm matching outbound requests appear in the NspPublicOutboundPerimeterRulesAllowed log category.

Test your connection through network security perimeter

To test your connection through network security perimeter, you need access to a web browser, either on a local computer with an internet connection or an Azure VM.

  1. Change your network security perimeter association to enforced mode to start enforcing network security perimeter requirements for network access to your Foundry IQ service.

  2. Choose a client:

    1. For a local computer, get your public IP address.

    2. For an Azure VM, use private link or find the IP address in the Azure portal.

  3. Create an inbound access rule for that IP address to allow access.

  4. In the Azure portal, open your Foundry IQ service and view its indexes.

    • Expected success: The index list loads and you can run a test query. The inbound IP rule is working.

    • If you see a 403 or "Public network access is disabled" error: Your client IP or the Azure portal isn't covered by an inbound rule. Check the inbound access rules.

Troubleshoot common issues

Symptom Likely cause Mitigation
Indexer fails after switching to enforced mode. The Foundry IQ service identity lacks a data-plane role on the data source, or the data source isn't supported within the perimeter. Confirm the Foundry IQ service uses a managed identity and has the required role on the data source. For unsupported data sources, add an outbound access rule.
Skill, vectorizer, or agentic retrieval calls to a Foundry resource are denied. The Foundry resource is in a different perimeter, or the Foundry IQ service authenticates with API keys, so the channel isn't implicit. Add both resources to the same perimeter and use managed identity, or add an outbound FQDN rule that targets the Foundry resource's hostname. For more information, see Outbound access to Microsoft Foundry resources.
Diagnostic logs don't appear in Log Analytics or Storage. Ingestion latency, or the storage account isn't in the same region as the perimeter. Wait up to 10 minutes after generating traffic, then query the NSPAccessLogs table or check the matching insights-logs-* storage container. Verify the storage account region.
Portal access to the Foundry IQ service is denied after enforcement. Your client IP isn't covered by any inbound rule. Add an inbound access rule for your client IP, or revert to learning mode while you finish configuration.

View and manage network security perimeter configuration

Use the Network Security Perimeter Configuration REST APIs to review and reconcile perimeter configurations on a Foundry IQ service.

For example, list the current perimeter configurations on a Foundry IQ service:

az rest --method get \
  --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service-name>/networkSecurityPerimeterConfigurations?api-version=2026-11-01"

If the configuration is out of sync with the perimeter, trigger a reconcile:

az rest --method post \
  --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service-name>/networkSecurityPerimeterConfigurations/<association-name>/reconcile?api-version=2026-11-01"

Use the latest stable version of the Search Management REST APIs. For more information, see Manage your Foundry IQ service using REST APIs.