infra: assign least-privilege Cognitive Services User when ASSIGN_RBAC=true

Replaces the two-role assignment (Foundry User + Foundry Project Manager) with a single Cognitive Services User assignment on the Foundry account. This is the smallest built-in role whose data actions cover Microsoft.CognitiveServices/accounts/MaaS/* (the Claude inference path).

Preserves the issue #38 / #39 serialization: all three Claude deployments still dependsOn the role-assignment resource, so the model-deployment LRO absorbs RBAC propagation lag.

Verified end-to-end with ASSIGN_RBAC=true: azd up succeeded, verifier 10/10 PASS including live claude -p round trip, python src/hello_claude.py succeeded on first call with no retries.

Closes #40.

Author: achandmsft

.env.sample

@@ -22,8 +22,10 @@ CLAUDE_MODEL_NAME=claude-sonnet-4-6
 CLAUDE_MODEL_VERSION=1
 CLAUDE_MODEL_CAPACITY=25
 
-# Grant Foundry User + Foundry Project Manager to AZURE_PRINCIPAL_ID during `azd up`.
-# Requires Microsoft.Authorization/roleAssignments/write on the deployer.
+# Grant `Cognitive Services User` (least-privilege inference role, GUID
+# a97b65f3-24c7-4388-baec-2e87135dc908) to AZURE_PRINCIPAL_ID on the Foundry
+# account during `azd up`. Requires Microsoft.Authorization/roleAssignments/write
+# on the deployer.
 # ASSIGN_RBAC=true
 
 # Let the postprovision hook run the official Claude Code installer if `claude` isn't on PATH.

.github/copilot-instructions.md

@@ -28,7 +28,7 @@ This is the **Claude on Foundry Starter Kit** ([`Azure-Samples/claude`](https://
 | `CLAUDE_OPUS_MODEL` | no | empty | e.g. `claude-opus-4-8`. Empty = skip family. |
 | `CLAUDE_HAIKU_CAPACITY` / `CLAUDE_SONNET_CAPACITY` / `CLAUDE_OPUS_CAPACITY` | no | `25` | TPM ÷ 1000 per family |
 | `CLAUDE_MODEL_NAME` | no | `claude-sonnet-4-6` | **Legacy** single-deployment fallback (only used when all three `CLAUDE_*_MODEL` are empty) |
-| `ASSIGN_RBAC` | no | `false` | `true` grants Foundry User + Foundry Project Manager to `AZURE_PRINCIPAL_ID` |
+| `ASSIGN_RBAC` | no | `false` | `true` grants `Cognitive Services User` (least-privilege inference role) on the Foundry account to `AZURE_PRINCIPAL_ID` |
 | `CLAUDE_CODE_AUTO_INSTALL` | no | `false` | `true` installs the Claude Code CLI in the postprovision hook |
 | `CLAUDE_WRITE_VSCODE_SETTINGS` | no | `false` | `true` opts in to having the postprovision hook write `.vscode/settings.json` for the [Anthropic Claude Code VS Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). Default skips it — the CLI / SDK don't need workspace settings. |
 

README.md

@@ -240,7 +240,7 @@ Rows marked **Attest** below are the three `modelProviderData` fields sent to An
 | `CLAUDE_MODEL_VERSION` | no | `1` | Applies to all deployed families. |
 | `CLAUDE_MODEL_NAME` | no | `claude-sonnet-4-6` | **Legacy.** Only used when all three `CLAUDE_*_MODEL` vars are empty (single-deployment fallback). |
 | `CLAUDE_MODEL_CAPACITY` | no | `25` | **Legacy.** Capacity for the legacy single-deployment fallback. |
-| `ASSIGN_RBAC` | no | `false` | `true` to grant `Foundry User` + `Foundry Project Manager` to `AZURE_PRINCIPAL_ID` (needs `roleAssignments/write`) |
+| `ASSIGN_RBAC` | no | `false` | `true` to grant `Cognitive Services User` (least-privilege inference role) on the Foundry account to `AZURE_PRINCIPAL_ID` (needs `roleAssignments/write`) |
 | `CLAUDE_CODE_AUTO_INSTALL` | no | `false` | `true` to let the postprovision hook run the official Claude Code installer ([`install.ps1`](https://claude.ai/install.ps1) / [`install.sh`](https://claude.ai/install.sh)) when `claude` isn't already on PATH |
 
 ### Choosing which models to deploy
@@ -426,9 +426,9 @@ If the Anthropic SDK ever accepts a callable for `auth_token`, this shim becomes
 - **Microsoft Foundry** account (`Microsoft.CognitiveServices/accounts`, kind `AIServices`, SKU `S0`, `allowProjectManagement = true`)
 - **Foundry project**
 - One **Claude deployment per requested family** (`GlobalStandard`, with the required `modelProviderData` block) — set `CLAUDE_HAIKU_MODEL` / `CLAUDE_SONNET_MODEL` / `CLAUDE_OPUS_MODEL` to control which families. Sonnet/Opus deployments chain on the prior to avoid Foundry's per-account 409s on concurrent create.
-- *Optional* RBAC: *Foundry User* + *Foundry Project Manager* on the deploying principal (set `ASSIGN_RBAC=true`). *(These roles were previously called `Azure AI User` / `Azure AI Project Manager`; Azure renamed them — the underlying role GUIDs are unchanged.)*
+- *Optional* RBAC: a single `Cognitive Services User` assignment on the Foundry account for the deploying principal (set `ASSIGN_RBAC=true`). This is the [least-privilege role the MS Learn doc recommends](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/configure-entra-id?tabs=python&pivots=ai-foundry-portal#for-making-authenticated-api-calls) for keyless inference — it grants exactly the `Microsoft.CognitiveServices/accounts/MaaS/*` data action this template's runtime needs and nothing else. If you want broader access (project-scoped APIs, agents, etc.), grant `Foundry User` or `Azure AI Developer` yourself afterwards — see the [permissions matrix](#required-permissions) below.
   - **Heads up:** without this (or a manual post-deploy grant), the Python SDK and `claude` CLI will return `401 PermissionDenied` even though `azd up` succeeded. See [Granting data-plane roles after `azd up`](#granting-data-plane-roles-after-azd-up).
-  - When `ASSIGN_RBAC=true`, the model deployments are ordered to run *after* both role assignments. The role-assignment PUTs return fast (~5 s) but Foundry data-plane RBAC takes a few minutes to propagate; the slow model-deployment LRO (30 s–20 min) absorbs that propagation time so the first call after `azd up` succeeds without retries.
+  - When `ASSIGN_RBAC=true`, the model deployments are ordered to run *after* the role assignment. The role-assignment PUT returns fast (~5 s) but Foundry data-plane RBAC takes a few minutes to propagate; the slow model-deployment LRO (30 s–20 min) absorbs that propagation time so the first call after `azd up` succeeds without retries.
 
 </details>
 
@@ -478,7 +478,7 @@ claude/
 | Preflight: `Marketplace offer ... not found` | `CLAUDE_MODEL_NAME` is misspelled, the model isn't in the Anthropic-on-Foundry catalog yet, or Anthropic changed the plan-name convention. |
 | Preflight: `Quota insufficient` (exit 6) | Requested `CLAUDE_*_CAPACITY` plus existing usage exceeds the per-region quota limit. Lower the requested capacity, free up quota by deleting unused deployments, or [purge soft-deleted accounts](#free-quota-held-by-soft-deleted-accounts) that may still be holding TPM. |
 | Quota looks full but you have no live deployments (`az cognitiveservices usage list` shows `currentValue > 0`, deployment still fails with `715-123420` / `InsufficientQuota`) | **Soft-deleted Cognitive Services accounts still reserve quota for 48 h.** A previous `azd down` (or any RG / account delete) puts the AIServices account in a recoverable state that keeps holding TPM. **Fix:** list and purge them: `az cognitiveservices account list-deleted -o table` then `az cognitiveservices account purge --name <name> --location <region> --resource-group <rg>` for each. See [Free quota held by soft-deleted accounts](#free-quota-held-by-soft-deleted-accounts). |
-| `401 PermissionDenied: Principal does not have access to API/Operation` intermittently &mdash; same code passes seconds later | Data-plane RBAC propagation lag on a freshly-granted role (`Cognitive Services User` / `Foundry User` / `Azure AI Developer`). The grant can take a few minutes to land on the Foundry data plane even after `az role assignment create` returns. When `ASSIGN_RBAC=true`, this kit serializes the model deployments after the role assignments so the deployment LRO absorbs the propagation wait &mdash; the first call after `azd up` should just work. If you granted the role manually *after* `azd up`, wait a minute and retry; verify the assignment with `az role assignment list --assignee <oid> --scope <foundry-account-id> -o table`. |
+| `401 PermissionDenied: Principal does not have access to API/Operation` intermittently &mdash; same code passes seconds later | Data-plane RBAC propagation lag on a freshly-granted role (`Cognitive Services User` / `Foundry User` / `Azure AI Developer`). The grant can take a few minutes to land on the Foundry data plane even after `az role assignment create` returns. When `ASSIGN_RBAC=true`, this kit serializes the model deployments after the role assignment so the deployment LRO absorbs the propagation wait &mdash; the first call after `azd up` should just work. If you granted the role manually *after* `azd up`, wait a minute and retry; verify the assignment with `az role assignment list --assignee <oid> --scope <foundry-account-id> -o table`. |
 | `claude -p` returns `The model claude-<family>-... is not available on your foundry deployment. Try --model to switch to ...` | Your user-global `~/.claude/settings.json` has `"model"` set to a family this workspace didn't deploy. The postprovision hook writes a workspace `.claude/settings.json` with `"model"` pinned to a deployed family, which overrides the global &mdash; but if you re-ran `azd up` *before* the hook update, or your global has a per-project override, the workspace pin won't apply. Either re-run `pwsh -File scripts/configure-claude-code.ps1` to regenerate `.claude/settings.json`, pick the family explicitly via `claude -p --model <sonnet\|opus\|haiku>`, or edit `~/.claude/settings.json` to remove the `"model"` line. |
 | Windows: `UnicodeEncodeError: 'charmap' codec can't encode character '\U0001f60a'` printing the model's response | The Foundry sample apps happily return emoji and other non-CP1252 characters; the default Windows console (cp1252) can't render them. Either set `$env:PYTHONIOENCODING = "utf-8"` before running, or switch the console to UTF-8 with `chcp 65001`. The Python samples already handle this gracefully, but third-party tooling may not. |
 | `check_claude_quota.py` exits with `Could not resolve a subscription id ... [WinError 2] The system cannot find the file specified` | The script falls back to `az account show` to find a subscription, but the Azure CLI isn't on `PATH` in the active shell. Either set `$env:AZURE_SUBSCRIPTION_ID = "<sub-id>"` or pass `--subscription <sub-id>` explicitly. |
@@ -640,7 +640,7 @@ Notes on the output:
 |---|---|---|
 | Provision Foundry + Claude deployment | `Contributor` (or `Cognitive Services Contributor`) | Resource group / subscription |
 | Assign RBAC inside this template (`ASSIGN_RBAC=true`) | `User Access Administrator` or `Owner` | Resource group / subscription |
-| Call the Messages API with Entra ID | `Foundry User` *(or `Azure AI Developer` &mdash; see note)* | Foundry account |
+| Call the Messages API with Entra ID | `Cognitive Services User` *(template default; see note for broader alternatives)* | Foundry account |
 
 If you do not have `Microsoft.Authorization/roleAssignments/write`, leave `ASSIGN_RBAC=false` (the default) and ask an admin to grant one of the roles below on the Foundry account afterwards.
 
@@ -672,8 +672,8 @@ Wait 1–3 minutes for the role to propagate to the Foundry data plane before re
 
 | Role | Data action(s) | Notes |
 |---|---|---|
-| `Cognitive Services User` | `Microsoft.CognitiveServices/*/read` + inference action | The minimum role recommended by [the official docs](https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/use-foundry-models-claude#troubleshooting). |
-| `Foundry User` | `Microsoft.CognitiveServices/*` | Broadest data-plane access; what this template assigns when `ASSIGN_RBAC=true`. **Previously named `Azure AI User`** &mdash; Azure renamed it, GUID `53ca6127-db72-4b80-b1b0-d745d6d5456d` is unchanged. |
+| `Cognitive Services User` | `Microsoft.CognitiveServices/*/read` + inference action | The minimum role recommended by [the official docs](https://learn.microsoft.com/en-us/azure/foundry/foundry-models/how-to/configure-entra-id?tabs=python&pivots=ai-foundry-portal#for-making-authenticated-api-calls), and what this template assigns when `ASSIGN_RBAC=true`. GUID `a97b65f3-24c7-4388-baec-2e87135dc908`. |
+| `Foundry User` | `Microsoft.CognitiveServices/*` | Broader data-plane access; useful if you plan to add project-scoped samples (agents, knowledge, evaluators) on top of this template. **Previously named `Azure AI User`** &mdash; Azure renamed it, GUID `53ca6127-db72-4b80-b1b0-d745d6d5456d` is unchanged. |
 | `Azure AI Developer` | includes `Microsoft.CognitiveServices/accounts/MaaS/*` | Sufficient for Claude because Claude routes through the **MaaS** data path as a partner/marketplace model. (It is **not** sufficient for first-party Foundry models that route through `accounts/AIServices/*`.) |
 
 > The role `Azure AI Developer` was historically called out as *insufficient* for Foundry inference. That guidance still applies to first-party `AIServices` models, but Claude/Anthropic deployments dispatch through `Microsoft.CognitiveServices/accounts/MaaS/*`, which `Azure AI Developer` already grants. Verified against `claude-sonnet-4-6` on `2025-10-01-preview`.

infra-bicep/infra/foundry.bicep

@@ -31,12 +31,14 @@ var haikuDeploymentNameVar  = empty(haikuModel)  ? '' : '${haikuModel}-${nameSuf
 var sonnetDeploymentNameVar = empty(sonnetModel) ? '' : '${sonnetModel}-${nameSuffix}'
 var opusDeploymentNameVar   = empty(opusModel)   ? '' : '${opusModel}-${nameSuffix}'
 
-// Built-in role definition IDs.
-// NOTE: Azure renamed these roles. The GUIDs are stable.
-//   53ca6127-... : "Azure AI User" -> "Foundry User" (data-plane access)
-//   eadc314b-... : "Azure AI Project Manager" -> "Foundry Project Manager"
-var foundryUserRoleId = '53ca6127-db72-4b80-b1b0-d745d6d5456d'
-var foundryProjectManagerRoleId = 'eadc314b-1a2d-4efa-be10-5d325db5065e'
+// Built-in role definition ID for the documented least-privilege inference
+// role on a Foundry account. See:
+//   https://learn.microsoft.com/azure/foundry/foundry-models/how-to/configure-entra-id#for-making-authenticated-api-calls
+// `Cognitive Services User` grants exactly the data action this template's
+// runtime needs (`Microsoft.CognitiveServices/accounts/MaaS/*`) and nothing
+// else. The broader `Foundry User` / `Azure AI Developer` roles also work
+// and are documented in README.md for users who deliberately want more.
+var cognitiveServicesUserRoleId = 'a97b65f3-24c7-4388-baec-2e87135dc908'
 
 resource account 'Microsoft.CognitiveServices/accounts@2025-10-01-preview' = {
   name: accountName
@@ -68,28 +70,18 @@ resource project 'Microsoft.CognitiveServices/accounts/projects@2025-10-01-previ
   properties: {}
 }
 
-// Role assignments are declared BEFORE the model deployments so each
-// deployment can dependsOn them. The model-deployment LRO can take
-// 30s-20min depending on region and family; chaining the role grants
+// Role assignment is declared BEFORE the model deployments so each
+// deployment can dependsOn it. The model-deployment LRO can take
+// 30s-20min depending on region and family; chaining the role grant
 // first turns that wait into free RBAC propagation time and makes the
 // first call after `azd up` succeed without the usual 5-min lag.
-// When rbacEnabled is false, both resources are `if(false)` and Bicep
+// When rbacEnabled is false, the resource is `if(false)` and Bicep
 // drops the dependsOn edge automatically.
-resource foundryUserAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (rbacEnabled) {
-  name: guid(account.id, principalId, foundryUserRoleId)
+resource cognitiveServicesUserAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (rbacEnabled) {
+  name: guid(account.id, principalId, cognitiveServicesUserRoleId)
   scope: account
   properties: {
-    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', foundryUserRoleId)
-    principalId: principalId
-    principalType: 'User'
-  }
-}
-
-resource foundryProjectManagerAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (rbacEnabled) {
-  name: guid(account.id, principalId, foundryProjectManagerRoleId)
-  scope: account
-  properties: {
-    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', foundryProjectManagerRoleId)
+    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', cognitiveServicesUserRoleId)
     principalId: principalId
     principalType: 'User'
   }
@@ -118,8 +110,7 @@ resource haikuDeployment 'Microsoft.CognitiveServices/accounts/deployments@2025-
   }
   dependsOn: [
     project
-    foundryUserAssignment
-    foundryProjectManagerAssignment
+    cognitiveServicesUserAssignment
   ]
 }
 
@@ -145,13 +136,12 @@ resource sonnetDeployment 'Microsoft.CognitiveServices/accounts/deployments@2025
     raiPolicyName: 'Microsoft.DefaultV2'
   }
   // Foundry serializes deployments under one account; chain them to avoid
-  // 409s on concurrent create. Role assignments are listed too so the
+  // 409s on concurrent create. The role assignment is listed too so the
   // first inference call after `azd up` doesn't hit RBAC propagation lag.
   dependsOn: [
     project
     haikuDeployment
-    foundryUserAssignment
-    foundryProjectManagerAssignment
+    cognitiveServicesUserAssignment
   ]
 }
 
@@ -179,8 +169,7 @@ resource opusDeployment 'Microsoft.CognitiveServices/accounts/deployments@2025-1
   dependsOn: [
     project
     sonnetDeployment
-    foundryUserAssignment
-    foundryProjectManagerAssignment
+    cognitiveServicesUserAssignment
   ]
 }
 

infra-bicep/infra/main.bicep

@@ -34,7 +34,7 @@ param location string
 @description('Object id of the deploying user/SP. Empty disables RBAC.')
 param principalId string = ''
 
-@description('Whether to assign Foundry User + Foundry Project Manager (formerly Azure AI User / Project Manager) to principalId. Set to "true" to enable.')
+@description('Whether to assign Cognitive Services User (least-privilege inference role) to principalId on the Foundry account. Set to "true" to enable.')
 param assignRbac string = 'false'
 
 @description('Short prefix for resource names.')

infra-terraform/infra/main.tf

@@ -138,11 +138,10 @@ resource "azapi_resource" "claude_haiku" {
   # but Foundry data-plane RBAC propagation can take 5+ min. Waiting on the
   # model-deployment LRO (30s-20min) in the meantime makes the first call
   # after `azd up` work without retries. When ASSIGN_RBAC is false, the
-  # collections are empty and depends_on is satisfied immediately.
+  # collection is empty and depends_on is satisfied immediately.
   depends_on = [
     azapi_resource.project,
-    azurerm_role_assignment.foundry_user,
-    azurerm_role_assignment.foundry_project_manager,
+    azurerm_role_assignment.cognitive_services_user,
   ]
 }
 
@@ -178,8 +177,7 @@ resource "azapi_resource" "claude_sonnet" {
   depends_on = [
     azapi_resource.project,
     azapi_resource.claude_haiku,
-    azurerm_role_assignment.foundry_user,
-    azurerm_role_assignment.foundry_project_manager,
+    azurerm_role_assignment.cognitive_services_user,
   ]
 }
 
@@ -215,25 +213,20 @@ resource "azapi_resource" "claude_opus" {
   depends_on = [
     azapi_resource.project,
     azapi_resource.claude_sonnet,
-    azurerm_role_assignment.foundry_user,
-    azurerm_role_assignment.foundry_project_manager,
+    azurerm_role_assignment.cognitive_services_user,
   ]
 }
 
 # --- Optional RBAC --------------------------------------------------------
-# NOTE: Azure renamed "Azure AI User" -> "Foundry User" and
-# "Azure AI Project Manager" -> "Foundry Project Manager". The GUIDs are
-# unchanged, but azurerm matches by name, so we use the current names.
-resource "azurerm_role_assignment" "foundry_user" {
+# Least-privilege role for Foundry inference, per:
+#   https://learn.microsoft.com/azure/foundry/foundry-models/how-to/configure-entra-id#for-making-authenticated-api-calls
+# `Cognitive Services User` grants exactly the data action this template's
+# runtime needs (`Microsoft.CognitiveServices/accounts/MaaS/*`) and nothing
+# else. Broader roles (`Foundry User`, `Azure AI Developer`) also work and
+# are documented in README.md for users who deliberately want more.
+resource "azurerm_role_assignment" "cognitive_services_user" {
   count                = lower(var.assign_rbac) == "true" && var.principal_id != "" ? 1 : 0
   scope                = azapi_resource.foundry.id
-  role_definition_name = "Foundry User"
-  principal_id         = var.principal_id
-}
-
-resource "azurerm_role_assignment" "foundry_project_manager" {
-  count                = lower(var.assign_rbac) == "true" && var.principal_id != "" ? 1 : 0
-  scope                = azapi_resource.foundry.id
-  role_definition_name = "Foundry Project Manager"
+  role_definition_name = "Cognitive Services User"
   principal_id         = var.principal_id
 }