Azure AI Foundry

Permission model

A single service principal carries both control-plane and data-plane access:

Which data-plane role to assign — and which not to

Microsoft’s Foundry RBAC roles were renamed in early 2026: Foundry User is the current name for what was previously called Azure AI User. The role ID and permissions did not change. To make role assignments stable across the rename, prefer assigning by role ID 53ca6127-db72-4b80-b1b0-d745d6d5456d rather than by name.

Do not use Cognitive Services User for this connector. Microsoft’s Foundry RBAC documentation explicitly states that Cognitive Services-prefixed roles “are designed for accessing AI Services resources directly and don’t apply to Foundry scenarios.” Cognitive Services User does not grant the Microsoft.CognitiveServices/accounts/AIServices/agents/* data actions that the Foundry data plane requires for /api/projects/<project>/assistants. Cognitive Services Contributor and Azure AI Developer are similarly out of scope — Azure AI Developer applies to AML workspaces and legacy Foundry hubs, not to Foundry projects.

If a tenant is partway through the rename (the Azure Portal can lag the documentation by a release), Azure AI User will still resolve to the same role ID; both names are accepted while the rename rolls out. The az CLI examples below assign by role ID for that reason.

Why subscription-wide read-only

Foundry resources are not always inventoried up front, and new projects are often spun up by application teams. Subscription-scoped Reader lets Arrakis pick up new resources automatically, with no per-resource onboarding step. Reader is read-only on the control plane and grants no data-plane access on its own — agent and tool reads still require Foundry User on each project. Write access is never granted.

Least-privilege caveats

• Reader at subscription scope grants enumeration of every resource type in that subscription, not only AI resources. If the subscription contains workloads outside Foundry, scope Reader to a management group that contains only the AI subscription, or split AI workloads into their own subscription.
• Reader does not grant access to keys or secrets (no listKeys action). Data-plane reads remain gated by Foundry User on each project.
• Foundry User inherits down the Azure resource hierarchy: assigned at subscription scope it covers every Foundry resource and project (existing and future) under that subscription — the simplest, future-proof setup. Assign at Foundry resource scope to cover all projects under one account, or at individual project scope for tighter segmentation. All three scopes work; pick whichever matches your governance posture.

Prerequisites

• An Azure subscription with at least one Foundry resource (kind AIServices or AIFoundry).
• Permission to create app registrations in Microsoft Entra ID and assign Azure RBAC roles, or coordination with an admin who can.
• Your tenantId and subscriptionId to hand.

Azure Portal walkthrough

The Portal click-path. UI labels match the Azure Portal at the time of writing.

1. Register an Entra ID app

1. Microsoft Entra ID → App registrations → New registration.
2. Name: arrakis-foundry-reader. Supported account types: single tenant. Redirect URI: leave blank.
3. Register. On the resulting overview page, copy Application (client) ID → this is your clientId. Copy Directory (tenant) ID → this is your tenantId.

Screenshot: App registrations → Overview, with Application (client) ID and Directory (tenant) ID fields highlighted.

2. Create a client secret

1. On the same app, Certificates & secrets → Client secrets → New client secret.
2. Description: arrakis-connector. Expires: per your rotation policy (recommend 6 or 12 months).
3. Add. Copy the Value column immediately — this is your clientSecret. It is shown once.

Screenshot: Certificates & secrets → Client secrets, with the Value column highlighted and the warning that it cannot be retrieved later.

3. Grant Reader at subscription scope

1. Subscriptions → <your subscription> → Access control (IAM) → Add → Add role assignment.
2. Role: Reader. Next.
3. Members: select User, group, or service principal, click Select members, search for arrakis-foundry-reader, select, click Select. Next.
4. Review + assign.

Screenshot: Subscription IAM → Add role assignment → Role tab with Reader selected.

For tighter scoping, repeat against a Management group (Management groups → <group> → Access control (IAM)) instead of an individual subscription. The same service principal works at either scope.

4. Grant Foundry User at subscription scope (recommended)

Foundry User inherits down the Azure resource hierarchy, so a single assignment at the subscription scope covers every Foundry resource and project under that subscription — including any new ones spun up later. This is the simplest, most future-proof option.

1. Subscriptions → <your subscription> → Access control (IAM) → Add → Add role assignment.
2. Role: Foundry User. (If your tenant still shows the previous name, Azure AI User resolves to the same role ID and is equivalent.)
3. Members: same arrakis-foundry-reader service principal.
4. Review + assign.

Screenshot: Subscription IAM → Add role assignment → Foundry User selected.

Do not pick a Cognitive Services-prefixed role here. Cognitive Services User does not grant the data actions Arrakis needs to read agents on the Foundry data plane.

When to scope tighter instead

Assign Foundry User at one of the narrower scopes if your governance posture requires it:

• Foundry resource (account) scope — Foundry resource page → Access control (IAM) → Add role assignment. Covers all projects under that account.
• Individual project scope — Foundry project page → Access control (IAM) → Add role assignment. Per-project segmentation; you’ll repeat for every project.

az CLI alternative

The same flow as a script. Substitute <sub-id> and the per-project resource IDs.

# 1. Sign in
az login
 
# 2. Create the app + service principal + client secret in one shot
SP_JSON=$(az ad sp create-for-rbac \
  --name arrakis-foundry-reader \
  --role Reader \
  --scopes /subscriptions/<sub-id>)
 
APP_ID=$(echo "$SP_JSON"   | jq -r .appId)
TENANT=$(echo "$SP_JSON"   | jq -r .tenant)
PASSWORD=$(echo "$SP_JSON" | jq -r .password)
 
echo "tenantId:       $TENANT"
echo "clientId:       $APP_ID"
echo "clientSecret:   $PASSWORD"
echo "subscriptionId: <sub-id>"
 
# 3. Assign Foundry User at subscription scope (recommended). Use the role ID
#    (53ca6127-db72-4b80-b1b0-d745d6d5456d) so the assignment is stable across
#    the Azure AI User → Foundry User rename. Subscription-scoped Foundry User
#    inherits to every Foundry resource and project, including future ones.
FOUNDRY_USER_ROLE_ID="53ca6127-db72-4b80-b1b0-d745d6d5456d"
 
az role assignment create \
  --assignee "$APP_ID" \
  --role "$FOUNDRY_USER_ROLE_ID" \
  --scope "/subscriptions/<sub-id>"
 
# Optional sanity check — list the Foundry resources the principal can now reach:
az cognitiveservices account list \
  --query "[?kind=='AIServices' || kind=='AIFoundry'].{name:name, rg:resourceGroup, id:id}" \
  -o table

If your governance posture requires a tighter scope, swap the --scope argument for a Foundry account resource ID (covers all projects under that account) or a project resource ID (single project):

# Foundry resource (account) scope
ACCOUNT_ID="/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>"
az role assignment create --assignee "$APP_ID" --role "$FOUNDRY_USER_ROLE_ID" --scope "$ACCOUNT_ID"
 
# Per-project scope
PROJECT_ID="$ACCOUNT_ID/projects/<project>"
az role assignment create --assignee "$APP_ID" --role "$FOUNDRY_USER_ROLE_ID" --scope "$PROJECT_ID"

Configure the connector in Arrakis

1. Sign in to Arrakis. Settings → Integrations → Add integration → Azure AI Foundry.
2. Paste the four fields:

3. Test connection. The test endpoint posts an OAuth2 client_credentials grant against https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token with scope https://management.azure.com/.default and confirms a token is returned.
4. Save. Arrakis schedules the first sync.

Verify the connection

After the first sync completes:

• The Agents view lists every Foundry agent across every project under the subscription, grouped by Foundry resource.
• Each agent shows its build type (prompt_agent for declarative agents, hosted_agent for hosted/code agents), model backbone (from the project’s model deployments), and tools (one Step per tool — see the Appendix for the full list).
• Resource and project counts should match az cognitiveservices account list output for the subscription.

If the first sync returns no agents, walk through Troubleshooting.

Troubleshooting

Security considerations

• Client secret rotation. Rotate on the cadence required by your policy (recommend 6 or 12 months). After issuing a new secret, paste it into Arrakis (Settings → Integrations → Edit Azure AI Foundry); the existing connection record is updated and the encrypted blob re-saved.
• Encrypted at rest. Only clientSecret is encrypted; tenantId, clientId, and subscriptionId are stored in plain text. This matches the Salesforce connector pattern.
• Least privilege. Reader is the lowest built-in subscription-scoped read role and grants no access to keys, secrets, or data-plane reads. Data reads remain gated by Foundry User per project. Foundry User itself is documented by Microsoft as the “least privilege access role in Foundry” — it grants reader plus the data actions for the project’s agents and nothing more.
• No write paths. Neither role grants write access. Arrakis cannot create, modify, or delete Foundry resources, projects, agents, or deployments — by design.
• Network egress. Outbound only, to login.microsoftonline.com, management.azure.com, and <resourceName>.services.ai.azure.com for each Foundry resource.

Appendix

Required roles

Do not substitute Cognitive Services User, Cognitive Services Contributor, or Azure AI Developer for Foundry User. Microsoft’s Foundry RBAC documentation calls out that Cognitive Services-prefixed roles do not apply to Foundry projects, and Azure AI Developer is scoped to AML workspaces and legacy Foundry hubs (not projects).

OAuth2 token audiences

API versions

Supported tools

Each tool a Foundry agent has configured becomes a Step on that agent in Arrakis:

code_interpreter, file_search, web_search, azure_ai_search, azure_functions, function, mcp, openapi, image_generation, browser_automation, computer_use, sharepoint, fabric.

Build-type detection

Endpoint reference

Limitations

• The Foundry agent API does not expose creator info — contributors is empty for every agent.
• Arrakis does not consume an execution-trace API for Foundry; runtime traces are sourced from Azure Monitor + Event Grid where customers have those configured.
• Per-resource, per-project, and per-agent errors are isolated during sync — one failed project does not abort the rest.