permission-least-privilege-review

name	permission-least-privilege-review
description	Step-by-step playbook for auditing a Microsoft Graph app's permission scope list: delegated vs application decision, narrowing over-broad scopes, finding resource-scoped alternatives, and the escalation criteria for ravenclaude-core/security-reviewer. Owned by graph-identity-engineer.

Permission Least-Privilege Review

When to invoke

• Selecting permissions for a new Graph app registration.
• Auditing an existing app's scope list before a security review or compliance audit.
• A call is returning 403 Forbidden and the scope is unclear.
• The app currently uses .ReadWrite.All or .All permissions and needs narrowing.

Step 1 — Delegated vs application: make the decision explicit

Type	When to use	Identity at runtime
Delegated	A signed-in user is present; the action is on behalf of that user	The user + the app (both must consent)
Application	No user; daemon, background job, scheduled task, service	The app only (admin consent required)

Never default to application permissions "because it's simpler." Application permissions grant the app access to ALL users' data in the tenant (e.g., Mail.Read application reads every mailbox). Delegated limits the blast radius to the signed-in user's data.

Decision rule:

Is a user interactively signed in?
├── YES → delegated
└── NO  → application (proceed to Step 2 with extra scrutiny)

Step 2 — Scope narrowing checklist

For each scope in the app's manifest:

Check	Action
Is it *.ReadWrite.All when only read is needed?	Replace with *.Read.All
Is it *.All when a resource-scoped permission exists?	Find the narrower permission (see table below)
Is it an application permission when a delegated one would work?	Downgrade to delegated
Is it Directory.ReadWrite.All?	Escalate to security-reviewer — this is near-tenant-admin
Is it Mail.ReadWrite application when only read is needed?	Replace with Mail.Read

Common resource-scoped alternatives:

Broad scope	Narrower alternative	Tradeoff
Files.ReadWrite.All	Files.ReadWrite (delegated, signed-in user's files only)	User must be signed in
Calendars.ReadWrite (application)	Calendars.ReadWrite (delegated)	Scoped to signed-in user
Group.ReadWrite.All	Group.Read.All + GroupMember.ReadWrite.All	Split read vs membership write
Sites.ReadWrite.All	Sites.Selected (application, site-specific consent)	Requires Site admin to grant; preferred for service apps

Step 3 — Sites.Selected for SharePoint/OneDrive daemon apps

If the app is a daemon accessing specific SharePoint sites:

1. Register the app with Sites.Selected (application permission).
2. Have a SharePoint site admin grant the app access to specific sites via the Graph API or SharePoint admin center.
3. The app can only read/write those specific sites — not the entire tenant.

This is the least-privilege choice for SharePoint service integrations. Sites.ReadWrite.All on a daemon app is a high-blast anti-pattern.

Step 4 — Verify consent state

A 403 Forbidden from Graph is almost always one of:

1. Missing admin consent for an application permission (use GET /servicePrincipals/{id}/appRoleAssignments to verify granted roles).
2. Missing user consent for a delegated permission (the user hasn't seen the consent dialog).
3. Correct permission but wrong type (delegated permission granted but app is using client-credentials flow → application context; vice versa).
4. Scope missing from the access token (the permission is granted in Entra but not included in the token's scp claim — check token with jwt.ms).

import jwt  # PyJWT
import base64, json

# Decode token (no verification — for debugging only)
parts = access_token.split(".")
payload = json.loads(base64.b64decode(parts[1] + "=="))
print("scp:", payload.get("scp"))    # delegated scopes
print("roles:", payload.get("roles"))  # application roles

Step 5 — Escalation criteria

Always escalate to ravenclaude-core/security-reviewer when:

• Any application permission that grants tenant-wide data access (Mail.Read, User.Read.All, Files.ReadWrite.All, Directory.* as application).
• Directory.ReadWrite.All — this is effectively a Tier 0 / tenant admin scope.
• The app will be granted admin consent by an Entra Global Admin (document why each scope is necessary; security-reviewer signs off on the justification).
• A client secret is used instead of certificate credentials for an application-permission app.
• The app handles regulated data (PHI, PII, financial) even with narrow scopes.

Pitfalls

• Requesting offline_access without a stated reason — this enables long-lived refresh tokens; document the session duration requirement.
• Using User.Read.All (application) when User.Read (delegated) plus the signed-in user's profile is sufficient.
• Testing with a Global Admin account and concluding "it works" — admins bypass consent and some permission checks; always test with a standard user account.
• Adding permissions "just in case" — every unused permission is a blast radius waiting to be exploited; audit quarterly and remove unused scopes.