RBAC Permissions Reference

Overview

The Mastra Agent Framework uses System-Assigned Managed Identities for passwordless authentication to all tenant-hosted services. Each compute resource (App Service and Function App) gets its own system-assigned identity, which is automatically assigned specific RBAC (Role-Based Access Control) roles to access each resource without managing credentials.

The template configures System-Assigned Managed Identity as the primary authentication mechanism, with appropriate RBAC roles assigned automatically during deployment.

Role Assignments Summary

Both App Service and Function App have system-assigned managed identities with identical RBAC roles (except storage).

note

Key difference - Storage permissions:

App Service: Blob Data Contributor only
Function App: Blob + Queue + Table + File Data Contributor (required for Azure Functions runtime)

All other permissions are identical between the two identities.

Complete Role Reference

Container Registry

Role	Role Definition ID	Permissions
AcrPull	`7f951dda-4ed3-4680-a7ca-43fe172d538d`	Pull images from ACR

Use case: App Service and Function App pull container images from ACR using this role.

Key Vault

Role	Role Definition ID	Permissions
Key Vault Secrets User	`4633458b-17de-408a-b874-0445c86b69e6`	Read secrets

Use case: App reads SQL connection strings and other secrets from Key Vault.

note

Key Vault is configured with RBAC authorization (not access policies). The enableRbacAuthorization: true setting is applied automatically.

Storage Account

Role	Role Definition ID	Permissions
Storage Blob Data Contributor	`ba92f5b4-2d11-453d-a403-e96b0029c9fe`	Read, write, delete blobs
Storage Queue Data Contributor	`974c5e8b-45b9-4653-ba55-5f855dd0fb88`	Read, write, delete queue messages
Storage Table Data Contributor	`0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3`	Read, write, delete table entities
Storage File Data SMB Share Contributor	`0c867c2a-1d8c-454a-a3db-ab2ea1bdc8bb`	Read, write, delete files

Use case:

App Service: Blob storage for documents, logs, AI training data
Function App: All four data types (blob, queue, table, file) for triggers, state, and background processing

note

Queue, Table, and File storage roles are assigned to the Function App only, as it requires these for Azure Functions triggers and internal state management. App Service only receives Blob storage access.

AI Services

AI Foundry (Azure OpenAI)

Role	Role Definition ID	Permissions
Cognitive Services OpenAI User	`5e0bd9bd-7b93-4f28-af87-19fc36ad61bd`	Use OpenAI models (chat, embeddings)

Use case: App calls LLMs, embeddings models deployed in AI Foundry.

note

For model deployment management, use Cognitive Services OpenAI Contributor (a001fd3d-188f-4b5d-821b-7da978bf7442) instead. The template uses the User role for least-privilege access.

Content Safety

Role	Role Definition ID	Permissions
Cognitive Services User	`a97b65f3-24c7-4388-baec-2e87135dc908`	Use cognitive services APIs

Use case: TAP workflows call Content Safety for moderation/flagging.

Form Recognizer (Document Intelligence)

Role	Role Definition ID	Permissions
Cognitive Services User	`a97b65f3-24c7-4388-baec-2e87135dc908`	Use cognitive services APIs

Use case: Document analysis, text extraction, form processing.

AI Search

Role	Role Definition ID	Permissions
Search Index Data Contributor	`8ebe5a00-799e-43f5-93ac-243d3dce84a7`	Read, write index data
Search Service Contributor	`7ca78c08-252a-4471-8644-bb5ff32d4ba0`	Manage indexes, indexers

Use case:

Index documents for vector search
Query indexes for RAG (Retrieval-Augmented Generation)
Manage index schemas

SQL Server

Role	Role Definition ID	Permissions
SQL DB Contributor	`9b7fa17d-e63e-47b0-bb0a-15c516ac86ec`	Manage databases (not server)

Use case: Both App Service and Function App connect to SQL database for workflow state, telemetry, configuration.

warning

For SQL database access via System-Assigned Managed Identity, additional configuration is required in SQL Server for each identity:

-- For App Service identity
CREATE USER [aitools-prod-app] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [aitools-prod-app];
ALTER ROLE db_datawriter ADD MEMBER [aitools-prod-app];

-- For Function App identity
CREATE USER [aitools-prod-func] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [aitools-prod-func];
ALTER ROLE db_datawriter ADD MEMBER [aitools-prod-func];

Environment Configuration

Configure these environment variables to enable managed identity authentication for tenant-hosted services:

Azure AI Inference / AI Foundry

AZURE_FOUNDRY_USE_MANAGED_IDENTITY=true
AZURE_INFERENCE_ENDPOINT=https://<ai-foundry-name>.cognitiveservices.azure.com

Content Safety

AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY=true
AZURE_CONTENT_SAFETY_ENDPOINT=https://<content-safety-name>.cognitiveservices.azure.com

SQL Server

# System-assigned identity doesn't require CLIENT_ID - uses the resource's own identity
AZURE_SQL_USE_MANAGED_IDENTITY=true
AZURE_SQL_SERVER=<sql-server-name>.database.windows.net
AZURE_SQL_DATABASE=<database-name>

Storage Account (Function App)

The Function App uses managed identity for storage automatically when configured with:

AzureWebJobsStorage__accountName=<storage-account-name>
AzureWebJobsStorage__credential=managedidentity

RBAC Module Reference

The RBAC assignments are defined in azure_template/modules/identity/rbac-assignments.bicep (../../azure_template/modules/identity/rbac-assignments.bicep).

The module accepts both App Service and Function App principal IDs and assigns roles to both identities:

// Role definition IDs (built-in Azure roles)
var roleDefinitions = {
  // Container Registry
  acrPull: '7f951dda-4ed3-4680-a7ca-43fe172d538d'

  // Key Vault
  keyVaultSecretsUser: '4633458b-17de-408a-b874-0445c86b69e6'

  // Storage Account - all data types
  storageBlobDataContributor: 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'
  storageQueueDataContributor: '974c5e8b-45b9-4653-ba55-5f855dd0fb88'
  storageTableDataContributor: '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'
  storageFileDataSmbShareContributor: '0c867c2a-1d8c-454a-a3db-ab2ea1bdc8bb'

  // Cognitive Services
  cognitiveServicesUser: 'a97b65f3-24c7-4388-baec-2e87135dc908'
  cognitiveServicesOpenAIUser: '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd'
  cognitiveServicesOpenAIContributor: 'a001fd3d-188f-4b5d-821b-7da978bf7442'

  // AI Search
  searchIndexDataContributor: '8ebe5a00-799e-43f5-93ac-243d3dce84a7'
  searchServiceContributor: '7ca78c08-252a-4471-8644-bb5ff32d4ba0'

  // SQL - for Azure AD authentication scenarios
  sqlDbContributor: '9b7fa17d-e63e-47b0-bb0a-15c516ac86ec'
}

Troubleshooting RBAC

Common Issues

Error	Cause	Solution
`AuthorizationFailed`	Missing role assignment	Verify role is assigned in Azure Portal > Resource > Access control (IAM)
`ForbiddenByRbac`	Role exists but wrong scope	Check role is assigned at resource level, not subscription
`IdentityNotFound`	System-assigned identity not enabled	Verify identity is enabled on App Service/Function App

Verify Role Assignments

# Get App Service principal ID
APP_PRINCIPAL_ID=$(az webapp identity show \
  --name <app-service-name> \
  --resource-group <rg> \
  --query principalId -o tsv)

# Get Function App principal ID
FUNC_PRINCIPAL_ID=$(az functionapp identity show \
  --name <function-app-name> \
  --resource-group <rg> \
  --query principalId -o tsv)

# List all role assignments for App Service identity
az role assignment list \
  --assignee $APP_PRINCIPAL_ID \
  --output table

# List all role assignments for Function App identity
az role assignment list \
  --assignee $FUNC_PRINCIPAL_ID \
  --output table

# Check specific resource
az role assignment list \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<name> \
  --output table

Manual Role Assignment

If automated RBAC fails, assign roles manually in the Azure Portal or via Azure CLI:

# Get principal IDs
APP_PRINCIPAL_ID=$(az webapp identity show --name <app-name> --resource-group <rg> --query principalId -o tsv)
FUNC_PRINCIPAL_ID=$(az functionapp identity show --name <func-name> --resource-group <rg> --query principalId -o tsv)

# Example: Assign Storage Blob Data Contributor to both identities
az role assignment create \
  --assignee $APP_PRINCIPAL_ID \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<name>

az role assignment create \
  --assignee $FUNC_PRINCIPAL_ID \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<name>

Role Assignment Propagation

RBAC role assignments can take up to 10 minutes to propagate. If the app fails immediately after deployment, wait and retry.

Overview​

Role Assignments Summary​

Complete Role Reference​

Container Registry​

Key Vault​

Storage Account​

AI Services​

AI Foundry (Azure OpenAI)​

Content Safety​

Form Recognizer (Document Intelligence)​

AI Search​

SQL Server​

Environment Configuration​

Azure AI Inference / AI Foundry​

Content Safety​

SQL Server​

Storage Account (Function App)​

RBAC Module Reference​

Troubleshooting RBAC​

Common Issues​

Verify Role Assignments​

Manual Role Assignment​

Role Assignment Propagation​

Overview

Role Assignments Summary

Complete Role Reference

Container Registry

Key Vault

Storage Account

AI Services

AI Foundry (Azure OpenAI)

Content Safety

Form Recognizer (Document Intelligence)

AI Search

SQL Server

Environment Configuration

Azure AI Inference / AI Foundry

Content Safety

SQL Server

Storage Account (Function App)

RBAC Module Reference

Troubleshooting RBAC

Common Issues

Verify Role Assignments

Manual Role Assignment

Role Assignment Propagation