Merge pull request #307443 from cephalin/openapi-secure

v-ccolin · web-flow · commit a181380170e0 · 2025-11-05T11:33:51.000Z
add foundry agent secure auth doc
diff --git a/articles/app-service/configure-authentication-ai-foundry-openapi-tool.md b/articles/app-service/configure-authentication-ai-foundry-openapi-tool.md
@@ -0,0 +1,129 @@
+---
+title: Secure OpenAPI tool calls from Azure AI Foundry Agent Service
+description: Configure Microsoft Entra authentication to secure Azure AI Foundry tool calls with managed identity, step by step.
+ms.topic: how-to
+ms.date: 10/28/2025
+author: cephalin
+ms.author: cephalin
+ms.service: azure-app-service
+ms.collection: ce-skilling-ai-copilot
+---
+
+# Secure OpenAPI endpoints for Azure AI Foundry Agent Service
+
+This article shows you how to secure your App Service OpenAPI endpoints when they're called by Azure AI Foundry Agent Service. When you add your App Service app as an OpenAPI tool in Azure AI Foundry, you can configure it to call your APIs anonymously without authentication, which is easier for development and testing. However, for production environments, you should use Microsoft Entra authentication with managed identity. This guide walks you through configuring managed identity authentication to enable secure, token-based communication between Azure AI Foundry and your app.
+
+## Prerequisites
+
+- An App Service app with OpenAPI endpoints. If you need to add OpenAPI functionality to your app, see one of the following tutorials:
+  - [Add an App Service app as a tool in Azure AI Foundry Agent Service (.NET)](tutorial-ai-integrate-azure-ai-agent-dotnet.md)
+  - [Add an App Service app as a tool in Azure AI Foundry Agent Service (Java)](tutorial-ai-integrate-azure-ai-agent-java.md)
+  - [Add an App Service app as a tool in Azure AI Foundry Agent Service (Python)](tutorial-ai-integrate-azure-ai-agent-python.md)
+  - [Add an App Service app as a tool in Azure AI Foundry Agent Service (Node.js)](tutorial-ai-integrate-azure-ai-agent-node.md)
+
+- An Azure AI Foundry project where you'll add your app as an OpenAPI tool.
+
+## Find your Azure AI Foundry project's managed identity IDs
+
+You need both the object ID and the application ID of your Azure AI Foundry project's managed identity to configure App Service authentication. A system-assigned managed identity is automatically created for your Azure AI Foundry project when you create it. This identity is what Azure AI Foundry Agent Service uses to authenticate with your app.
+
+1. In the [Azure AI Foundry portal](https://ai.azure.com), navigate to your project and select **Overview**.
+
+1. In the **Project details** section on the right, select the link next to **Resource group** to open the resource group in the Azure portal.
+
+1. In the resource group, find and select your AI Foundry project resource.
+
+1. In the project resource's left menu, select **Resource Management** > **Identity**.
+
+1. Under **System assigned**, copy the value of **Object (principal) ID** for later.
+
+1. In the Azure portal, search for and select **Microsoft Entra ID**.
+
+1. In the search box, search for the object ID you copied and select it in the search results.
+
+1. On the **Overview** page, copy the value of **Application ID**. 
+
+    Note the **Object ID** is the same as the one shown in the system-assigned managed identity. You need both the application ID and the object ID for configuring App Service authentication.
+
+## Configure Microsoft Entra authentication for your app
+
+1. In the Azure portal, navigate to your App Service app.
+
+1. On your app's left menu, select **Settings** > **Authentication**, and then select **Add identity provider**.
+
+1. On the **Add an identity provider** page, select **Microsoft** as the **Identity provider** to create a new app registration.
+
+1. Under **Additional checks**, for **Client application requirement**, select **Allow requests from specific client applications**.
+
+1. Select the pencil widget and add the **application ID** that you copied in [Find your Azure AI Foundry project's managed identity IDs](#find-your-azure-ai-foundry-projects-managed-identity-ids).
+
+1. For **Identity requirement**, select **Allow requests from specific identities**.
+
+1. Select the pencil widget and add the **object ID** that you copied in [Find your Azure AI Foundry project's managed identity IDs](#find-your-azure-ai-foundry-projects-managed-identity-ids).
+
+1. For **Tenant requirement** accept the default value. If not, be sure to select the tenant where your Azure AI Foundry project (or rather its identity) is created.
+
+1. For **Unauthenticated requests**, select **HTTP 401 Unauthorized: recommended for APIs**.
+
+1. Select **Add** to create the identity provider.
+
+   :::image type="content" source="media/configure-authentication-ai-foundry-openapi-tool/entra-auth-configuration.png" alt-text="Screenshot showing the configuration of a new Microsoft authentication provider in the App Service.":::
+
+## Update the app registration Application ID URI
+
+After enabling authentication, you need to update the app registration's Application ID URI to match your App Service app's URL.
+
+1. After the Microsoft provider configuration completes, select it in the **Identity provider** column to open the app registration page.
+
+1. In the left menu, select **Manage** > **Expose an API**.
+
+1. Next to **Application ID URI**, select **Edit**.
+
+1. Change the value to your App Service app's URL in the following format: `https://<suffix>.azurewebsites.net`.
+
+    You can find the app's hostname on the **Overview** page in **Default domain**.
+
+1. Select **Save**.
+
+> [!WARNING]
+> If you delete your App Service app, you must also delete the app registration and clean up any authentication resources that reference the Application ID URI. Failing to do so creates a security vulnerability: if someone else creates an app with the same URL, they could potentially gain unauthorized access to resources that trust the orphaned app registration. Always remove app registrations and their associated permissions when decommissioning an app.
+
+## Configure the OpenAPI tool in Azure AI Foundry
+
+> [!NOTE]
+> This section assumes you already completed one of the tutorials in the [Prerequisites](#prerequisites) section, where you added your app as an OpenAPI tool in Azure AI Foundry using anonymous authentication. You now update the tool to use managed identity authentication.
+
+1. Back in the [Azure AI Foundry portal](https://ai.azure.com), select your agent.
+
+1. Find the OpenAPI tool and select it to edit.
+
+1. In the **Define the schema for this tool** page:
+
+   1. Paste your OpenAPI schema. For more information, see [How to use OpenAPI with Azure AI Foundry Agent Service](/azure/ai-services/agents/how-to/tools/openapi-spec).
+   
+   1. For **Authentication method**, select **Managed Identity**.
+   
+   1. For **Audience**, enter your App Service app's URL. This URL must match the **Application ID URI** that you configured earlier.
+
+   > [!TIP]
+   > Azure AI Foundry Agent Service uses the system-assigned managed identity to authenticate with your app. Because you added the identity's client ID as an allowed client application and an allowed identity in your app's authentication provider configuration, the agent service is authorized to call your app's APIs.
+
+1. Review and save the tool.
+
+## Test the agent
+
+1. In the Azure AI Foundry portal, select your agent and select **Try in playground**.
+
+1. Chat with the agent to test your OpenAPI endpoints. For example:
+
+   - Show me all the tasks.
+   - Create a task called "Buy groceries."
+   - Update that task to "Buy groceries and cook dinner."
+
+If the authentication is configured correctly, the agent successfully calls your app's APIs through the OpenAPI tool.
+
+## Related content
+
+- [Configure your App Service or Azure Functions app to use Microsoft Entra sign-in](configure-authentication-provider-aad.md)
+- [Integrate AI into your Azure App Service applications](overview-ai-integration.md)
+- [What is Azure AI Foundry Agent Service?](/azure/ai-services/agents/overview)
diff --git a/articles/app-service/media/configure-authentication-ai-foundry-openapi-tool/entra-auth-configuration.png b/articles/app-service/media/configure-authentication-ai-foundry-openapi-tool/entra-auth-configuration.png
diff --git a/articles/app-service/toc.yml b/articles/app-service/toc.yml
@@ -416,8 +416,8 @@ items:
       href: configure-authentication-api-version.md
     - name: Use file-based configuration
       href: configure-authentication-file-based.md
-    - name: MCP server authorization
-      href: configure-authentication-mcp.md
+    - name: Authenticate AI Foundry tool calls
+      href: configure-authentication-ai-foundry-openapi-tool.md
 - name: Security and networking
   items:
     - name: Security overview
diff --git a/articles/app-service/tutorial-ai-integrate-azure-ai-agent-dotnet.md b/articles/app-service/tutorial-ai-integrate-azure-ai-agent-dotnet.md
@@ -3,7 +3,7 @@ title: Integrate web app with OpenAPI in Azure AI Foundry Agent Service (.NET)
 description: Empower your existing .NET web apps by integrating their capabilities into Azure AI Foundry Agent Service with OpenAPI, enabling AI agents to perform real-world tasks.
 author: cephalin
 ms.author: cephalin
-ms.date: 06/16/2025
+ms.date: 10/28/2025
 ms.topic: tutorial
 ms.custom:
   - devx-track-dotnet
@@ -180,6 +180,9 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 1. In the **Define schema** page, paste the schema that you copied earlier. Review and save the action.
 
+> [!TIP]
+> In this tutorial, the OpenAPI tool is configured to call your app anonymously without authentication. For production scenarios, you should secure the tool with managed identity authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md).
+
 ## Test the agent
 
 1. If the agents playground isn't already opened in the foundry portal, select the agent and select **Try in playground**.
@@ -198,7 +201,7 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 When exposing APIs via OpenAPI in Azure App Service, follow these security best practices:
 
-- **Authentication and Authorization**: Protect your OpenAPI endpoints in App Service behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
+- **Authentication and Authorization**: Protect your OpenAPI endpoints with Microsoft Entra authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md). You can also protect your endpoints behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
 - **Validate input data:** The sample code checks `ModelState.IsValid` in the `CreateTodo` method, which ensures that the incoming data matches the model's validation attributes. For more information, see [Model validation in ASP.NET Core](/aspnet/core/mvc/models/validation).
 - **Use HTTPS:** The sample relies on Azure App Service, which enforces HTTPS by default and provides free TLS/SSL certificates to encrypt data in transit.
 - **Limit CORS:** Restrict Cross-Origin Resource Sharing (CORS) to trusted domains only. For more information, see [Enable CORS](app-service-web-tutorial-rest-api.md#enable-cors).
diff --git a/articles/app-service/tutorial-ai-integrate-azure-ai-agent-java.md b/articles/app-service/tutorial-ai-integrate-azure-ai-agent-java.md
@@ -3,7 +3,7 @@ title: Integrate web app with OpenAPI in Azure AI Foundry Agent Service (Java)
 description: Empower your existing Java web apps by integrating their capabilities into Azure AI Foundry Agent Service with OpenAPI, enabling AI agents to perform real-world tasks.
 author: cephalin
 ms.author: cephalin
-ms.date: 07/16/2025
+ms.date: 10/28/2025
 ms.topic: tutorial
 ms.custom:
   - devx-track-java
@@ -132,6 +132,9 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 1. In the **Define schema** page, paste the schema that you copied earlier. Review and save the action.
 
+> [!TIP]
+> In this tutorial, the OpenAPI tool is configured to call your app anonymously without authentication. For production scenarios, you should secure the tool with managed identity authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md).
+
 ## Test the agent
 
 1. If the agents playground isn't already opened in the foundry portal, select the agent and select **Try in playground**.
@@ -150,7 +153,7 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 When exposing APIs via OpenAPI in Azure App Service, follow these security best practices:
 
-- **Authentication and Authorization**: Protect your OpenAPI endpoints in App Service behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
+- **Authentication and Authorization**: Protect your OpenAPI endpoints with Microsoft Entra authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md). You can also protect your endpoints behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
 - **Validate and sanitize input data:** The example code in this tutorial omits input validation and sanitization for simplicity and clarity. In production scenarios, always implement proper validation and sanitization to protect your application. For Spring, see [Spring: Validating Form Input](https://spring.io/guides/gs/validating-form-input).
 - **Use HTTPS:** The sample relies on Azure App Service, which enforces HTTPS by default and provides free TLS/SSL certificates to encrypt data in transit.
 - **Limit CORS:** Restrict Cross-Origin Resource Sharing (CORS) to trusted domains only. For more information, see [Enable CORS](app-service-web-tutorial-rest-api.md#enable-cors).
diff --git a/articles/app-service/tutorial-ai-integrate-azure-ai-agent-node.md b/articles/app-service/tutorial-ai-integrate-azure-ai-agent-node.md
@@ -3,7 +3,7 @@ title: Integrate web app with OpenAPI in Azure AI Foundry Agent Service (Node.js
 description: Empower your existing Node.js web apps by integrating their capabilities into Azure AI Foundry Agent Service with OpenAPI, enabling AI agents to perform real-world tasks.
 author: cephalin
 ms.author: cephalin
-ms.date: 07/21/2025
+ms.date: 10/28/2025
 ms.topic: tutorial
 ms.custom:
   - devx-track-javascript
@@ -237,6 +237,9 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 1. In the **Define schema** page, paste the schema that you copied earlier. Review and save the action.
 
+> [!TIP]
+> In this tutorial, the OpenAPI tool is configured to call your app anonymously without authentication. For production scenarios, you should secure the tool with managed identity authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md).
+
 ## Test the agent
 
 1. If the agents playground isn't already opened in the foundry portal, select the agent and select **Try in playground**.
@@ -255,7 +258,7 @@ At a minimum, open the [sample application](https://github.com/Azure-Samples/msd
 
 When exposing APIs via OpenAPI in Azure App Service, follow these security best practices:
 
-- **Authentication and Authorization**: Protect your OpenAPI endpoints in App Service behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
+- **Authentication and Authorization**: Protect your OpenAPI endpoints with Microsoft Entra authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md). You can also protect your endpoints behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
 - **Validate input data:** Always validate incoming data to prevent invalid or malicious input. For Node.js apps, use libraries such as [express-validator](https://express-validator.github.io/docs/) to enforce data validation rules. Refer to their documentation for best practices and implementation details.
 - **Use HTTPS:** The sample relies on Azure App Service, which enforces HTTPS by default and provides free TLS/SSL certificates to encrypt data in transit.
 - **Limit CORS:** Restrict Cross-Origin Resource Sharing (CORS) to trusted domains only. For more information, see [Enable CORS](app-service-web-tutorial-rest-api.md#enable-cors).
diff --git a/articles/app-service/tutorial-ai-integrate-azure-ai-agent-python.md b/articles/app-service/tutorial-ai-integrate-azure-ai-agent-python.md
@@ -3,7 +3,7 @@ title: Integrate web app with OpenAPI in Azure AI Foundry Agent Service (Python)
 description: Empower your existing Python web apps by integrating their capabilities into Azure AI Foundry Agent Service with OpenAPI, enabling AI agents to perform real-world tasks.
 author: cephalin
 ms.author: cephalin
-ms.date: 08/21/2025
+ms.date: 10/28/2025
 ms.topic: tutorial
 ms.custom:
   - devx-track-python
@@ -147,6 +147,9 @@ FasAPI already contains OpenAPI functionality at the default path `/openapi.json
 
 1. In the **Define schema** page, paste the schema that you copied earlier. Review and save the action.
 
+> [!TIP]
+> In this tutorial, the OpenAPI tool is configured to call your app anonymously without authentication. For production scenarios, you should secure the tool with managed identity authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md).
+
 ## Test the agent
 
 1. If the agents playground isn't already opened in the foundry portal, select the agent and select **Try in playground**.
@@ -163,7 +166,7 @@ FasAPI already contains OpenAPI functionality at the default path `/openapi.json
 
 When exposing APIs via OpenAPI in Azure App Service, follow these security best practices:
 
-- **Authentication and Authorization**: Protect your OpenAPI endpoints in App Service behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
+- **Authentication and Authorization**: Protect your OpenAPI endpoints with Microsoft Entra authentication. For step-by-step instructions, see [Secure OpenAPI endpoints for Azure AI Foundry Agent Service](configure-authentication-ai-foundry-openapi-tool.md). You can also protect your endpoints behind [Azure API Management with Microsoft Entra ID](/azure/api-management/api-management-howto-protect-backend-with-aad) and ensure only authorized users or agents can access the tools.
 - **Validate input data:** Always validate incoming data to prevent invalid or malicious input. For Python apps, use libraries such as [Pydantic](https://pypi.org/project/pydantic/) to enforce data validation rules with dedicated request schema models (such as RestaurantCreate and ReviewCreate). Refer to their documentation for best practices and implementation details.
 - **Use HTTPS:** The sample relies on Azure App Service, which enforces HTTPS by default and provides free TLS/SSL certificates to encrypt data in transit.
 - **Limit CORS:** Restrict Cross-Origin Resource Sharing (CORS) to trusted domains only. For more information, see [Enable CORS](app-service-web-tutorial-rest-api.md#enable-cors).
