Skip to content
⚠️ Before You Start
Risk: High
Duration: 2-4 hours plus approval lead time
Last Validated: Not yet validated (draft)
Kind: Runbook
Risk Note: High (an over-broad grant exposes every system the identity can reach)

Change an agent's permissions safely

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-11-13). Author: Prasanna · dry-run: Devadharshini Raja · sign-off: Sivaraj. Work items: AGT-08-T09, AGT-08-T10, AGT-08-T11, AGT-08-T12.

1. Summary

When an agent needs a new tool, a wider data scope, a new role assignment or a new Graph permission. Also when removing permissions after a scope reduction.

Risk: High (an over-broad grant exposes every system the identity can reach). Typical duration: 2-4 hours plus approval lead time.

2. When to use and when not to

Use it when: When an agent needs a new tool, a wider data scope, a new role assignment or a new Graph permission. Also when removing permissions after a scope reduction.

Do not use it when: to be written by the author.

3. What you must know first

  • Assign roles to the agent identity at the narrowest scope that works
  • Role assignments can take several minutes to take effect; check current behaviour in the docs
  • Built-in data-plane roles (for example Storage Blob Data Reader) are narrower than control-plane roles
  • Code allow-lists and cloud roles must change together

4. Prerequisites and access

  • Approved change ticket with the updated envelope file
  • Rights to manage role assignments at the target scope
  • Object id of the agent's managed identity or agent identity
  • Rollback plan agreed with the business owner

5. Steps

Outline of the steps; the author adds the commands and a check after each one.

  1. Export the current role assignments for the agent identity to the change ticket.
  2. Diff the new envelope against the current one and confirm only the approved change is present.
  3. Apply the role assignment at the narrowest scope.
  4. Deploy the updated envelope policy file with the code allow-list change.
  5. Verify with a scripted call that the new action works.
  6. Verify that a neighbouring resource outside the scope is still denied.
  7. Run the agent regression gate (PB-AGT-07-02) for tool accuracy.
  8. Close the ticket with before and after exports attached.
  9. Rollback: delete the new assignment and redeploy the previous envelope file.

Draft snippet: Grant one data-plane role at container scope with rollback record

#!/usr/bin/env bash
set -euo pipefail
# Inputs come from the approved change ticket
SCOPE="/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RG}/providers/Microsoft.Storage/storageAccounts/${STORAGE}/blobServices/default/containers/${CONTAINER}"

# 1. Record current state for rollback
az role assignment list --assignee "${AGENT_PRINCIPAL_ID}" --all -o json > "before-${CHANGE_ID}.json"

# 2. Apply the approved change at the narrowest scope
az role assignment create \
  --assignee-object-id "${AGENT_PRINCIPAL_ID}" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Reader" \
  --scope "$SCOPE"

# 3. Verify
az role assignment list --assignee "${AGENT_PRINCIPAL_ID}" --scope "$SCOPE" -o table

# Rollback:
# az role assignment delete --assignee "${AGENT_PRINCIPAL_ID}" --role "Storage Blob Data Reader" --scope "$SCOPE"

Snippets to add:

  • snippets/ops/agent-grant.sh: Export, grant and verify role assignments for an agent identity (bash)
  • snippets/ops/role-changes.kql: Activity log query for role assignment changes on agent identities (kql)

6. Monitoring and alerts

Signal Alert when Action
Activity log: role assignment write for agent identities Any change outside an approved change window Security engineer reviews within 1 hour and reverts if unapproved
403 errors from agent tools Spike after a permission change Check the new assignment scope and token refresh

7. Rollback

To be written by the author: how to undo each risky step.

8. Known issues and fixes

Symptom Likely cause Fix
New tool still gets 403 after the grant Role propagation delay or token cached before the grant Wait and retry, then restart the agent to refresh its token
Grant works but is wider than intended Assignment made at resource group or subscription scope Delete it and reassign at the resource scope
Agent uses the new tool for unrelated tasks Prompt and tool description too broad Tighten the tool description and add negative evaluation cases
Envelope file and cloud roles disagree Only one side was changed Make the pipeline apply both from the same change

9. AWS and open-source equivalents

On AWS, the equivalent is editing the agent's IAM role policy with IAM Access Analyzer checks, plus AgentCore Policy changes for tool access. Kubernetes-hosted open-source agents use workload identity and namespaced RBAC.

10. Validation record

Pending. Planned dry-run scenario: A second engineer grants the sandbox agent read access to one container, proves access to a second container is denied, then rolls back. Pass: before and after exports match the ticket and the rollback leaves the original assignments unchanged.

11. Sources