Merge pull request #49677 from MicrosoftDocs/NEW-intro-azure-ai-agent-security-controls

New intro azure ai agent security controls

Author: JamesJBarnett

learn-pr/advocates/intro-ai-agent-service-security-controls/1-understand-azure-ai-agent-service.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.understand-azure-ai-agent-service
+title: Understand the Azure AI Agent Service
+metadata:
+  title: Understand the Azure AI Agent Service
+  description: Learn about the Azure AI Agent Service.
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 3
+content: |
+  [!include[](includes/1-understand-azure-ai-agent-service.md)]

learn-pr/advocates/intro-ai-agent-service-security-controls/2-secure-azure-ai-agent-service.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.secure-azure-ai-agent-service
+title: Securing the Azure AI Agent Service
+metadata:
+  title: Securing the Azure AI Agent Service
+  description: Understand the security controls that can be applied to the Azure AI Agent Service.
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 3
+content: |
+  [!include[](includes/2-secure-azure-ai-agent-service.md)]

learn-pr/advocates/intro-ai-agent-service-security-controls/3-azure-ai-agent-service-role-based-access-control.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.azure-ai-agent-service-role-based-access-control
+title: Azure AI Agent Service Role Based Access Control
+metadata:
+  title: Azure AI Agent Service Role Based Access Control
+  description: Learn to configure role-based access control for the Azure AI Agent Service.
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 7
+content: |
+  [!include[](includes/3-azure-ai-agent-service-role-based-access-control.md)]

learn-pr/advocates/intro-ai-agent-service-security-controls/4-agent-service-and-network-access.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.agent-service-network-access
+title: Agent Service and Network Access
+metadata:
+  title: Agent Service and Network Access
+  description: Learn to configure network access for the Azure AI Agent Service.
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 3
+content: |
+  [!include[](includes/4-agent-service-network-access.md)]

learn-pr/advocates/intro-ai-agent-service-security-controls/5-knowledge-check.yml

@@ -0,0 +1,47 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.knowledge-check
+title: Knowledge Check
+metadata:
+  title: Knowledge Check
+  description: Check your knowledge of the Azure AI Agent Service security controls.
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 3
+content: Choose the best response for each question. 
+quiz:
+  questions:
+    - content: "You want to configure an AI Agent Service agent so that outbound data movement is restricted to approved locations. On what resource should you configure this restriction?"
+      choices:
+        - content: "Azure AI Hub."
+          isCorrect: true
+          explanation: "Correct. You configure network restrictions for Azure Agents at the Azure AI Hub level"
+        - content: "Virtual Network"
+          isCorrect: false
+          explanation: "Incorrect. You configure network restrictions for Azure Agents at the Azure AI Hub level"
+        - content: "Private Endpoint."
+          isCorrect: false
+          explanation: "Incorrect. You configure network restrictions for Azure Agents at the Azure AI Hub level"
+    - content: "You have disabled public network access to your Azure AI Hub. What steps can you take to configure and interact with the AI Agents deployed in one of the Hub's projects?"
+      choices:
+        - content: "Create a network security group."
+          isCorrect: false
+          explanation: "Incorrect. Network security groups aren't used to mediate access to Azure AI Hub."
+        - content: "Deploy Azure Bastion."
+          isCorrect: false
+          explanation: "Incorrect. Azure bastion provides secure access to virtual machines. You would need to configure a private endpoint to allow access from the virtual machine to the Azure AI Hub and the projects and AI agents it hosts."
+        - content: "Create a private endpoint."
+          isCorrect: true
+          explanation: "Correct. By creating a private endpoint, you can specify a virtual network and subnet through which you're able to access the Azure AI Hub, the projects it hosts, and AI Agents associated with those projects."
+    - content: "Which role based access control role is the Azure AI Hub's system assigned managed identity assigned to by default?"
+      choices:
+        - content: "Azure AI Administrator."
+          isCorrect: true
+          explanation: "Correct. The Azure AI Hub's system assigned managed identity is assigned to the Azure AI Administrator role by default."
+        - content: "Reader."
+          isCorrect: false
+          explanation: "Incorrect. The Azure AI Hub's system assigned managed identity is assigned to the Azure AI Administrator role by default."
+        - content: "Azure AI Developer."
+          isCorrect: false
+          explanation: "Incorrect. The Azure AI Hub's system assigned managed identity is assigned to the Azure AI Administrator role by default."

learn-pr/advocates/intro-ai-agent-service-security-controls/6-summary.yml

@@ -0,0 +1,13 @@
+### YamlMime:ModuleUnit
+uid: learn.introduction-ai-agent-service-security-controls.summary
+title: Summary
+metadata:
+  title: Summary
+  description: Module summary
+  ms.date: 03/21/2025
+  author: Orin-Thomas
+  ms.author: orthomas
+  ms.topic: unit
+durationInMinutes: 1
+content: |
+  [!include[](includes/6-summary.md)]

learn-pr/advocates/intro-ai-agent-service-security-controls/includes/1-understand-azure-ai-agent-service.md

@@ -0,0 +1,11 @@
+Azure AI Agent Service is a fully managed service designed to empower developers to securely build, deploy, and scale high-quality, and extensible AI agents without needing to manage the underlying compute and storage resources. Tasks that can take hundreds of lines of code to support client side function calling can now be achieved with just a few lines of code with Azure AI Agent Service.
+
+An AI Agent acts as a "smart" microservice that can be used to answer questions (Retrieval Augmented Generation), perform actions, or completely automate workflows. AI agents achieve this by combining the power of generative AI models to understand information resources with tools that allow that model to access and interact with real-world data sources.
+
+Because Azure AI Agent Service is a service fully managed by Microsoft, you can focus on building workflows and the agents that power them without needing to worry about scaling, security, or management of the underlying infrastructure for individual agents.
+
+As Azure AI Agent Service is a service managed by Microsoft and you don't need to worry about the underlying security of its moving parts, you should still apply standard security principals when you use the AI agent service. These principles include:
+
+- Restrict access to the service using role based access control. Ensure that only appropriate security principals can interact with the AI agent service.
+- Restrict the access of the AI Agent service. The AI Agent service is interacting with sensitive resources, such as organizational data. Ensure that the scope of this access is limited and that the AI Agent service and its tools only have necessary visibility of resources such as data stores.
+- Restrict network access to the AI Agent service and the network access of the AI agent service. Limit which network hosts can interact with the AI Agent service and control which network hosts the AI Agent service and it's associated tools are able to reach.

learn-pr/advocates/intro-ai-agent-service-security-controls/includes/2-secure-azure-ai-agent-service.md

@@ -0,0 +1,11 @@
+In Azure AI Foundry, Agents are associated with projects and projects are located within hubs. Hubs are the primary top-level Azure resource for Azure AI Foundry and provide a central way for a team to govern security, connectivity, and computing resources across playgrounds and projects. Typically, an IT Admin or technical lead manages a hub. These IT Admins or technical leads can use hubs to govern infrastructure, including virtual network setup, customer-managed keys, managed identities, and policies, and configure relevant Azure AI services. Once a hub is created, developers can create projects from it and access shared company resources without needing an IT administrator's repeated help.
+
+Projects function as isolated development spaces, allowing developers and data scientists to build, test, and deploy AI systems. Each time a new project gets created within a hub, it automatically inherits that hub's security settings. Agents, being part of projects, can leverage the resources and configurations set at both the hub and project levels.
+
+You can apply security controls through the Azure AI Foundry interface or by applying security controls through the Azure portal. When you deploy a hub and project, these resources are stored within a resource group in your Azure subscription. The Azure AI Foundry provides an abstracted way of interacting with these security controls without requiring an understanding of Azure administration principles. Azure AI Foundry allows you to configure role based access control roles. Within the Azure portal, you can configure the following security settings at the Azure AI Hub level:
+
+- Role based access control
+- Network access
+- Monitoring alerts, metrics and logs
+
+At the Azure AI project level, you can configure role based access control, monitoring alerts, metrics, and logs, but can't configure network access restrictions. In the majority of scenarios, you configure security controls related to Azure AI Agents Service agents at the hub level. When you need to have different sets of security controls, you host Azure AI Agent Service agents in different Azure AI hubs.

learn-pr/advocates/intro-ai-agent-service-security-controls/includes/3-azure-ai-agent-service-role-based-access-control.md

@@ -0,0 +1,36 @@
+Azure role-based access control (Azure RBAC) is used to manage access to Azure resources, such as the ability to create new resources or use existing ones. Users in your Microsoft Entra ID are assigned specific roles, which grant access to resources. Azure RBAC allows you to configure access to Azure AI Foundry hubs and projects and by extension agents that exist within those projects.
+
+The Azure AI Foundry hub has built-in roles that are available by default.
+
+| **Role** | **Description** |
+|---|---|
+| **Owner** | Full access to the hub, including the ability to manage and create new hubs and assign permissions. This role is automatically assigned to the hub creator |
+| **Contributor** | User has full access to the hub, including the ability to create new hubs, but isn't able to manage hub permissions on the existing resource. |
+| **Azure AI Administrator** | This role is automatically assigned to the system-assigned managed identity for the hub. The Azure AI Administrator role has the minimum permissions needed for the managed identity to perform its tasks. |
+| **Azure AI Developer** | Perform all actions except create new hubs and manage the hub permissions. For example, users can create projects, compute, and connections. Users can assign permissions within their project. Users can interact with existing Azure AI resources such as Azure OpenAI, Azure AI Search, and Azure AI services. |
+| **Azure AI Inference Deployment Operator** | Perform all actions required to create a resource deployment within a resource group. |
+| **Reader** | Read only access to the hub. This role is automatically assigned to all project members within the hub. |
+
+Hubs have the system-assigned managed identity assigned to the Azure AI Administrator role. This role is more narrowly scoped to the minimum permissions needed for the managed identity to perform its tasks. This system-assigned managed identity is inherited at the project level. Depending on how an Azure AI Agent is configured, the process will use the system-assigned managed identity when accessing data sources or performing actions such as running code, running a custom function or an Azure function with the user's identity.  
+
+When a user is granted access to a project (for example, through the Azure AI Foundry portal permission management), two more roles are automatically assigned to the user. The first role is Reader on the hub. The second role is the Inference Deployment Operator role, which allows the user to create deployments on the resource group that the project is in.
+
+The following table is an example of how to set up role-based access control for your Azure AI Foundry for an enterprise.
+
+| **Persona** | **Role** | **Purpose** |
+|---|---|---|
+| **IT admin** | Owner of the hub | The IT admin can ensure the hub is set up to their enterprise standards. They can assign managers the Contributor role on the resource if they want to enable managers to make new hubs. Or they can assign managers the Azure AI Developer role on the resource to not allow for new hub creation. |
+| **Managers** | Contributor or Azure AI Developer on the hub | Managers can manage the hub, audit compute resources, audit connections, and create shared connections. |
+| **Team lead/Lead developer** | Azure AI Developer on the hub | Lead developers can create projects for their team and create shared resources (such as compute and connections) at the hub level. After project creation, project owners can invite other members. |
+| **Team members/developers** | Contributor or Azure AI Developer on the project | Developers can build and deploy AI models within a project and create assets that enable development such as computes and connections. |
+
+You can add users and assign roles directly from Azure AI Foundry at either the hub or project level. In the management center, select Users in either the hub or project section, then select New user to add a user.
+
+![A screenshot Role Based Access Control configuration for an Azure AI Foundary hub in the Azure portal.](../media/hub-user-role.png)
+
+When you create a hub, the built-in role-based access control permissions grant you access to use the resource. However, if you wish to use resources outside of what was created on your behalf, you need to ensure both:
+
+- The resource you're trying to use has permissions set up to allow you to access it.
+- Your hub is allowed to access it.
+
+For example, if you're trying to consume a new Blob storage that isn't hosted within the associated Azure AI hub. In this circumstance, you need to ensure that hub's managed identity is added to the Blob Storage Reader role for the Blob. You'll also need to ensure that you have configured workplace managed outbound access to allow network communication to the endpoint associated with the blob storage. Network access configuration is covered in more detail by the next unit.

learn-pr/advocates/intro-ai-agent-service-security-controls/includes/4-agent-service-network-access.md

@@ -0,0 +1,16 @@
+You configure network access for an Azure AI Agent associated with an Azure Foundry project at the Hub level. You can only configure network settings for a hub in the Azure portal and can't configure network settings in Azure Foundry.
+
+You have the following options when configuring network access:
+
+- Public access. Either allow public access from all networks including the internet or disable public access. If you disable public access, you need to access the hub, project, and AI Agent service through a private endpoint.
+- Private endpoint connections. Allows you to add private endpoints to access the hub, projects, and Azure AI Agents. When configuring private endpoint access, you can allow access from specific virtual networks and subnets. Private endpoints require a DNS address that can be hosted in a private DNS zone.
+- Workspace managed outbound access. When configuring outbound access for the Azure AI hub associated with the project that hosts the Azure AI Agent, you can choose 
+  - Disabled: Compute can access public resources and outbound data movement is unrestricted.
+  - Allow Internet Outbound: Compute can access private resources and outbound data movement is unrestricted.
+  - Allow Only Approved Outbound. Compute can access resources that specifically allowlisted and outbound data movement is restricted to approved addresses.
+
+![Screenshot of Azure AI Hub networking configuraiton in Azure portal.](../media/networking-configuration.png)
+
+To access your non-Azure resources located in a different virtual network or located entirely on-premises from your Azure AI Foundry's managed virtual network, you need to configure and deploy an Application Gateway. Through this Application Gateway, you can configure full end to end access to your resources. Once you configure the Application Gateway, you can create a private endpoint from the Azure AI Foundry hub's managed virtual network to the Application Gateway. With the private endpoint, the full end to end path is secured and not routed through the Internet.
+
+![Architecture diagram of Application Gateway connection from Azure AI Foundary to external resources.](../media/ai-foundry-app-gateway.png)