Role-based access control for Microsoft Foundry

In this article, you learn core role-based access control (RBAC) concepts for Microsoft Foundry, including scopes, built-in roles, and common enterprise assignment patterns.

Tip

RBAC roles apply when you authenticate using Microsoft Entra ID. If you use key-based authentication instead, the key grants full access without role restrictions. Microsoft recommends using Entra ID authentication for improved security and granular access control.

For more information about authentication and authorization in Microsoft Foundry, see Authentication and Authorization.

Minimum role assignments to get started

For new users to Azure and Microsoft Foundry, start with these minimum assignments so both your user principal and project managed identity can access Foundry features.

You can verify current assignments by using Check access for a user to a single Azure resource.

Assign the Foundry User role on your Foundry resource to your user principal.

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
Assign the Foundry User role on your Foundry resource to your project's managed identity.

If the user who created the project can assign roles (for example, by having the Azure Owner role at subscription or resource group scope), both assignments are added automatically.

Tip

If a user or service principal only needs to interact with agents (for example, calling the Responses API) without creating or modifying them, assign Foundry Agent Consumer instead of Foundry User. This role provides least-privilege access for agent consumers.

To assign these roles manually, use the following quick steps.

Assign a role to your user principal

In the Azure portal, open your Foundry resource and go to Access control (IAM). Create a role assignment for Foundry User, set Members to User, group, or service principal, select your user principal, and then select Review + assign.

Assign a role to your project's managed identity

In the Azure portal, open your Foundry project and go to Access control (IAM). Create a role assignment for Foundry User, set Members to Managed identity, select your project's managed identity, and then select Review + assign.

Terminology for role-based access control in Foundry

To understand role-based access control in Microsoft Foundry, consider two questions for your enterprise.

What permissions do I want my team to have when building in Microsoft Foundry?
At what scope do I want to assign permissions to my team?

To help answer these questions, here are descriptions of some terminology used throughout this article.

Permissions: Allowed or denied actions that an identity can perform on a resource, such as reading, writing, deleting, or managing both control plane and data plane operations.
Scope: The set of Azure resources to which a role assignment applies. Typical scopes include subscription, resource group, Foundry resource, or Foundry project.
Role: A named collection of permissions that defines which actions can be performed on Azure resources at a given scope.

An identity gets a role with specific permissions at a selected scope based on your enterprise requirements.

In Microsoft Foundry, consider two scopes when completing role assignments.

Foundry resource: The top-level scope that defines the administrative, security, and monitoring boundary for a Microsoft Foundry environment.
Foundry project: A sub-scope within a Foundry resource used to organize work and enforce access control for Foundry APIs, tools, and developer workflows.

Built-in roles

A built-in role in Foundry is a role created by Microsoft that covers common access scenarios that you can assign to your team members. Key built-in roles used across Azure include Owner, Contributor, and Reader. These roles aren't specific to Foundry resource permissions.

For Foundry resources, use additional built-in roles to follow least-privilege access principles. The following table lists key built-in roles for Foundry and links to the exact role definitions in AI + Machine Learning built-in roles.

Role	Description
Foundry Agent Consumer	Grants access to interact with agent endpoints in a Foundry project. Least-privilege access role for principals that only need to interact with agents.
Foundry User	Grants reader access to Foundry project, Foundry resource, and data actions for your Foundry project. If you can assign roles, this role is assigned to you automatically. Otherwise, your subscription Owner or a user with role assignment permissions grants it. Least-privilege access role for developers building and testing agents.
Foundry Project Manager	Lets you perform management actions on Foundry projects, build and develop with projects, and conditionally assign the Foundry User role to other user principals.
Foundry Account Owner	Grants full access to manage projects and resources, and lets you conditionally assign the Foundry User, ACR, and monitoring roles to other user principals.
Foundry Owner	Grants full access to manage projects and resources and build and develop with projects. Lets you conditionally assign the Foundry User, ACR, and monitoring roles. Highly privileged self-serve role designed for digital natives.

Note

Don't assign built-in roles that start with Cognitive Services. These roles are designed for accessing AI Services resources directly and don't apply to Foundry scenarios. Similarly, don't use the Azure AI Developer role for Foundry work. Despite the name, this role is scoped to Azure Machine Learning workspaces and Foundry hubs, not to Foundry projects or Foundry hosted agents. For Foundry project access, use Foundry User or Foundry Owner instead.

Permissions for each built-in role

Use the following table to see the permissions allowed for each built-in role in Microsoft Foundry.

Built-in role	Create Foundry projects	Create Foundry accounts	Build and develop in a project (data actions)	Complete role assignments	Reader access to projects and accounts	Manage models	Publish agents	Interact with agent endpoints
Foundry Agent Consumer	✘	✘	✘	✘	✘	✘	✘	✔
Foundry User	✘	✘	✔	✘	✔	✘	✘	✔
Foundry Project Manager	✘	✘	✔	✔ (only assign Foundry User role)	✔	✘	✔	✔
Foundry Account Owner	✔	✔	✘	✔ (assign Foundry User, ACR, and monitoring roles)	✔	✔	✘	✘
Foundry Owner	✔	✔	✔	✔ (assign Foundry User, ACR, and monitoring roles)	✔	✔	✔	✔

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Use the following table to see the permissions allowed for each key Azure built-in roles (Owner, Contributor, Reader).

Built-in role	Create Foundry projects	Create Foundry accounts	Build and develop in a project (data actions)	Complete role assignments	Reader access to projects and accounts	Manage models	Publish agents	Interact with agent endpoints
Owner	✔	✔	✘	✔ (assign any role to any user)	✔	✔	✔	✘
Contributor	✔	✔	✘	✘	✔	✔	✘	✘
Reader	✘	✘	✘	✘	✔	✘	✘	✘

To publish agents, you need the Foundry Project Manager role (minimum) on the Foundry resource scope. For more information, see Agent applications in Microsoft Foundry.

Use these tabs to explore the differences between the built-in roles, assigned at the Foundry resource level (except for Owner, which is assigned at the subscription level)

Diagram shows access for Owner.

Sample enterprise RBAC mappings for projects

Here's an example of how to implement role-based access control (RBAC) for an enterprise Foundry resource.

Persona	Role and Scope	Purpose
IT admin	Owner on subscription scope	The IT admin ensures the Foundry resource meets enterprise standards. Assign managers the Foundry Account Owner role on the resource to let them create new Foundry accounts. Assign managers the Foundry Project Manager role on the resource to let them create projects within an account.
Managers	Foundry Account Owner on Foundry resource scope	Managers manage the Foundry resource, deploy models, audit compute resources, audit connections, and create shared connections. They can't build in projects, but they can assign the Foundry User role to themselves and others to start building.
Team lead or lead developer	Foundry Project Manager on Foundry resource scope	Lead developers create projects for their team and start building in those projects. After you create a project, project owners invite other members and assign the Foundry User role.
Team members or developers	Foundry User on Foundry project scope and Reader on the Foundry resource scope	Developers build agents in a project with pre-deployed Foundry models and pre-built connections.
Agent consumers or end users	Foundry Agent Consumer on Foundry project scope (or agent scope for per-agent control)	Users and service principals that only need to interact with agents through their endpoints. This role provides least-privilege access without granting broader development capabilities.

Manage role assignments

To manage roles in Foundry, you must have permission to assign and remove roles in Azure. The Azure built-in Owner role includes that permission. You can assign roles through the Foundry portal (Admin page), Azure portal IAM, or Azure CLI. You can remove roles by using Azure portal IAM or Azure CLI.

Foundry portal
Azure portal

In the Foundry portal, manage permissions by:

Open the Admin page in Foundry, then select Operate > Admin.
Select your project name.
Select Add user to manage project access. This action is available only if you have role-assignment permissions.
Apply the same flow for Foundry resource-level access.

You can manage permissions in the Azure portal under Access Control (IAM).

For example, the following command assigns the Foundry User role to joe@contoso.com for resource group this-rg in subscription 00000000-0000-0000-0000-000000000000:

az role assignment create --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --assignee "joe@contoso.com" --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/this-rg

Note

Because the Foundry RBAC roles were recently renamed, use the role definition ID (GUID) instead of the role name in your code to avoid issues during the rename rollout:

Foundry User: 53ca6127-db72-4b80-b1b0-d745d6d5456d
Foundry Owner: c883944f-8b7b-4483-af10-35834be79c4a
Foundry Account Owner: e47c6f54-e4a2-4754-9501-8e0985b135e1
Foundry Project Manager: eadc314b-1a2d-4efa-be10-5d325db5065e

Agent-scope role assignments

Roles can be assigned at the scope of a specific agent rather than the entire project. This approach lets you grant access to one agent without granting access to all agents in the project. The scope URI for an agent follows this pattern:

/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<accountName>/projects/<projectName>/agents/<agentName>

For example, to assign the Foundry Agent Consumer role to a service principal at the scope of a specific agent using the Azure CLI:

az role assignment create \
    --assignee "<principalId>" \
    --role "Foundry Agent Consumer" \
    --scope "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<accountName>/projects/<projectName>/agents/<agentName>"

Agent-scope assignments follow the same RBAC model as project-scope assignments. Any role that can be assigned at the project scope can also be assigned at the agent scope.

Create custom roles for projects

If the built-in roles don't meet your enterprise requirements, create a custom role that allows for precise control over allowed actions and scopes. Here's an example subscription-level custom role definition:

{
  "properties": {
    "roleName": "My Enterprise Foundry User",
    "description": "Custom role for Foundry at my enterprise to only allow building Agents. Assign at subscription level.",
    "assignableScopes": ["/subscriptions/<your-subscription-id>"],
    "permissions": [ { 
        "actions": ["Microsoft.CognitiveServices/*/read", "Microsoft.Authorization/*/read", "Microsoft.CognitiveServices/accounts/listkeys/action","Microsoft.Resources/deployments/*"], 
        "notActions": [], 
        "dataActions": ["Microsoft.CognitiveServices/accounts/AIServices/agents/*"], 
        "notDataActions": []     
    } ]
  }
}

For more information on creating a custom role, see the following articles.

Azure portal
Azure CLI
Azure PowerShell
Disable preview features in Microsoft Foundry. This article provides more details on specific permissions in Foundry across control and data plane which you can utilize when building custom roles.

Notes and limitations

To view and purge deleted Foundry accounts, you must have the Contributor role assigned at the subscription scope.
Users with the Contributor role can deploy models in Foundry.
You need the Owner role on a resource's scope to create custom roles in the resource.
If you have permissions to role assign in Azure (for example, the Owner role assigned on the account scope) to your user principal, and you deploy a Foundry resource from the Azure portal or Foundry portal UI, then the Foundry User role gets automatically assigned to your user principal. This assignment doesn't apply when deploying Foundry from SDK or CLI.

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
When you create a Foundry resource, the built-in role-based access control (RBAC) permissions give you access to the resource. To use resources created outside Foundry, ensure the resource has permissions that let you access it. Here are some examples:
- To use a new Azure Blob Storage account, add the Foundry account resource's managed identity to the Storage Blob Data Reader role on that storage account.
- To use a new Azure AI Search source, add Foundry to the Azure AI Search role assignments.
To fine-tune a model in Foundry, you need both data plane and control plane permissions. Deploying a fine-tuned model is a control plane permission. Therefore, the only built-in role with both data plane and control plane permissions is the Foundry Owner role. Or, if you prefer, you can also assign the Foundry User role for data plane permissions and the Foundry Account Owner role for control plane permissions.

Deployment type–specific permissions

The following sections cover the permission surface for specific deployment types. Use them alongside the built-in role tables in Permissions for each built-in role when planning role assignments for a particular workload.

Managed compute control-plane operations

Managed compute deployments (Preview) are governed by their own set of Azure resource provider operations under the Microsoft.CognitiveServices provider. These operations control who can create, read, update, and delete a managed compute deployment, and who can read the available accelerator capacity and quota usage for a Foundry account.

This section lists the five required control-plane operations, the built-in roles that grant them, and how the role-to-permission mapping differs from standard (pay-per-token and PTU) deployments.

Note

The operations in this section govern the control plane — creating, configuring, and deleting deployments. To call a deployment at inference time, assign the Foundry User role on the Foundry account scope (or use the account API key). See Authentication and Authorization in Foundry.

Required operations

Five operations are required to fully manage managed compute deployments on a Foundry account:

Operation	Description
`Microsoft.CognitiveServices/accounts/managedComputeDeployments/read`	Read or list managed compute deployments on a Foundry account.
`Microsoft.CognitiveServices/accounts/managedComputeDeployments/write`	Create or update a managed compute deployment.
`Microsoft.CognitiveServices/accounts/managedComputeDeployments/delete`	Delete a managed compute deployment.
`Microsoft.CognitiveServices/locations/managedComputeCapacities/read`	List available accelerator capacity by region.
`Microsoft.CognitiveServices/locations/usages/read`	Read accelerator usage and quota consumption.

Important

A root-level operation Microsoft.CognitiveServices/capacities/read does not exist. Custom roles that grant capacity reads must use the location-scoped locations/managedComputeCapacities/read operation (or managedComputeCapacities/read if scoped at the root of the provider). A wildcard such as Microsoft.CognitiveServices/locations/*/read matches locations/usages/read but does not match locations/managedComputeCapacities/read. List the operation explicitly when authoring a custom role.

Role-to-permission mapping

The following table shows which built-in roles grant each of the five managed compute control-plane operations.

Role	`managedComputeDeployments/read`	`managedComputeDeployments/write`	`managedComputeDeployments/delete`	`managedComputeCapacities/read`	`usages/read`
Cognitive Services Contributor	✔	✔	✔	✔	✔
Cognitive Services User	✔	✘	✘	✔	✔
Foundry Owner	✔	✔	✔	✔	✔
Foundry Account Owner	✔	✔	✔	✔	✔
Foundry Project Manager	✔	✘	✘	✔	✔
Foundry User	✔	✘	✘	✔	✔

The Azure built-in Owner and Contributor roles grant all five operations through their wildcard action grant on the subscription or resource group.

Comparison: standard deployments vs managed compute deployments

The control-plane permission surface for managed compute deployments mirrors the surface for standard (pay-per-token and PTU) deployments; the operation names differ only by the resource type segment (deployments vs managedComputeDeployments, and modelCapacities vs managedComputeCapacities).

The following table summarizes how each role's CRUD coverage compares across the two deployment families:

Role	Standard deployments CRUD	Managed compute deployments CRUD	Difference
Cognitive Services Contributor	Full	Full	Same
Cognitive Services User	Read-only	Read-only	Same
Foundry Owner	Full	Full	Same
Foundry Account Owner	Full	Full	Same
Foundry Project Manager	Read + capacities + usages	Read + capacities + usages	Same
Foundry User	Read + capacities + usages	Read + capacities + usages	Same

Note

If you author a custom role that uses a locations/*/read wildcard to grant capacity reads for standard deployments, that wildcard does not cover managedComputeCapacities/read. Add Microsoft.CognitiveServices/locations/managedComputeCapacities/read to the custom role explicitly to grant capacity reads on the managed compute control plane.

Recommended role assignments

Use the following starting points when assigning access for these operations with managed compute:

Deploy and operate managed compute deployments: assign Cognitive Services Contributor on the Foundry account scope.
Read-only viewer for deployments and quota: assign Cognitive Services User or Foundry User on the Foundry account scope.
Manage a Foundry project but not deploy models: assign Foundry Project Manager on the Foundry account scope. Project Managers can read deployments and quota but cannot create or delete them.
Call a managed compute deployment with Microsoft Entra ID at inference time: assign Foundry User on the Foundry account scope, in addition to whatever control-plane role the user holds (or with no control-plane role at all for inference-only users).

For the end-to-end deployment workflow, see Deploy open-source models with managed compute.

Elevated-role tasks in Microsoft Foundry — role requirements for all admin tasks, including role assignment and agent infrastructure.
Create a project.
Check access for a user to a single Azure resource.
Authentication and Authorization in Foundry.
Disable preview features in Microsoft Foundry.
Hosted agent permissions reference.

Appendix

Access Isolation Examples

Each organization may have different access isolation requirements depending on the user personas in their enterprise. Access isolation refers to which users in your enterprise are given what role assignments for either a separation of permissions using our built-in roles or a unified, highly permissive role. There are three access isolation options for Foundry that you can select for your organization depending on your access isolation requirements.

No access isolation. This means in your enterprise, you don't have any requirements separating permissions between a developer, project manager, or an admin. The permissions for these roles can be assigned across teams.

Therefore, you should...

Grant all users in your enterprise the Foundry Owner role on the resource scope

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Partial access isolation. This means the project manager in your enterprise should be able to develop within projects as well as create projects. But your admins shouldn't be able to develop within Foundry, only create Foundry projects and accounts.

Therefore, you should...

Grant your admin with Foundry Account Owner on the resource scope
Grant your developer and project managers with Foundry Project Manager role on the resource

Full access isolation. This means your admins, project managers, and developers have clear permissions assigned that don't overlap for their different functions within an enterprise.

Therefore you should...

Grant your admin the Foundry Account Owner on resource scope
Grant your developer the Reader role on Foundry resource scope and Foundry User on project scope
Grant your project manager the Foundry Project Manager role on resource scope
Grant your agent consumers the Foundry Agent Consumer role on project scope (or agent scope for per-agent control)

Use Microsoft Entra groups with Foundry

Microsoft Entra ID provides several ways to manage access to resources, applications, and tasks. By using Microsoft Entra groups, you can grant access and permissions to a group of users instead of to each individual user. Enterprise IT admins can create Microsoft Entra groups in the Azure portal to simplify the role assignment process for developers. When you create a Microsoft Entra group, you can minimize the number of role assignments required for new developers working on Foundry projects by assigning the group the required role assignment on the necessary resource.

Complete the following steps to use Microsoft Entra ID groups with Foundry:

Create a Security group in Groups in the Azure portal.
Add an owner and the user principals in your organization who need shared access.
Open the target resource and go to Access control (IAM).
Assign the required role to User, group, or service principal, and select the new security group.
Select Review + assign so the role assignment applies to all members of the group.

Common examples:

To build agents, run traces, and use core Foundry capabilities, assign Foundry User to the Microsoft Entra group.
To allow interaction with agents without broader development access, assign Foundry Agent Consumer to the Microsoft Entra group.
To use Tracing and Monitoring features, assign Reader on the connected Application Insights resource to the same group.

To learn more about Microsoft Entra ID groups, prerequisites, and limitations, refer to:

Feedback

Was this page helpful?

Last updated on 2026-06-03

Role-based access control for Microsoft Foundry

Minimum role assignments to get started

Assign a role to your user principal

Assign a role to your project's managed identity

Terminology for role-based access control in Foundry

Built-in roles

Permissions for each built-in role

Sample enterprise RBAC mappings for projects

Manage role assignments

Feedback

Additional resources