# Microsoft Graph API Permissions

> **Status:** Reference  
> **Last reviewed:** 2026-04-30  
> **Use for:** Current repo-based Microsoft Graph permission reference for implemented platform features  
> **Do not use for:** Future roadmap permissions or final tenant-specific grant truth without checking the repo and the live tenant posture

This document summarizes the permission registry currently defined in:

- `apps/platform/config/intune_permissions.php`
- `apps/platform/config/entra_permissions.php`

These config files are the repo source of truth for currently implemented permission requirements.

## Scope Rules

- The list below describes the current repo-required Microsoft Graph permissions for implemented features.
- This document does not promote roadmap or research-only permissions to required status.
- `granted_stub` values in `intune_permissions.php` are display aids for the UI, not the canonical required-permission list.
- Unless stated otherwise, these are application permissions.

## Current Required Permissions

### Intune Configuration, Backup, Restore, and Drift

| Permission | Why the repo requires it |
|---|---|
| `DeviceManagementConfiguration.Read.All` | Read Intune device configuration policies for inventory, backup, settings normalization, and drift flows |
| `DeviceManagementConfiguration.ReadWrite.All` | Execute restore and other write flows for Intune device configuration policies |
| `DeviceManagementApps.Read.All` | Read Intune app configuration and assignments for sync and backup |
| `DeviceManagementApps.ReadWrite.All` | Restore and manage Intune app configuration and assignments |
| `DeviceManagementServiceConfig.Read.All` | Read enrollment restrictions, Autopilot, ESP, and related service configuration |
| `DeviceManagementServiceConfig.ReadWrite.All` | Restore and manage enrollment restrictions, Autopilot, ESP, and related service configuration |
| `DeviceManagementScripts.Read.All` | Read device management scripts and remediations for sync and backup |
| `DeviceManagementScripts.ReadWrite.All` | Restore and manage device management scripts and remediations |

### Conditional Access And Policy Coverage

| Permission | Why the repo requires it |
|---|---|
| `Policy.Read.All` | Read Conditional Access and related identity policy surfaces used for backup, preview, and versioning |
| `Policy.ReadWrite.ConditionalAccess` | Manage Conditional Access policies for controlled restore or admin-managed write paths |

### Directory, Groups, And Intune RBAC Foundations

| Permission | Why the repo requires it |
|---|---|
| `Directory.Read.All` | Directory lookups and tenant-health-oriented checks |
| `Group.Read.All` | Assignment name resolution, group mapping, group directory cache, backup metadata enrichment, and drift context |
| `DeviceManagementRBAC.Read.All` | Read Intune RBAC settings and scope tags for metadata enrichment and assignment-aware flows |
| `DeviceManagementRBAC.ReadWrite.All` | Manage scope tags for foundation backup and restore workflows |

### Entra Admin Roles Evidence

| Permission | Why the repo requires it |
|---|---|
| `RoleManagement.Read.Directory` | Read directory role definitions and assignments for Entra admin roles evidence and findings |

## Not Currently Required By Implemented Features

These permissions may appear in research, roadmap ideas, or tenant-specific grants, but they are not part of the current required-permission registry:

- `SharePointTenantSettings.Read.All` is a roadmap or research permission until SharePoint tenant settings are actually implemented.
- Exchange Online or Defender for Office 365 PowerShell permissions are not current repo requirements because those integrations are not implemented as production features.
- `DeviceManagementManagedDevices.ReadWrite.All` may appear in fixtures or grant stubs, but it is not listed in the current required-permission registry.

## Grant And Verify

1. In Entra ID, open the TenantPilot app registration.
2. Add the required Microsoft Graph application permissions from the tables above.
3. Grant admin consent for the tenant.
4. In the application, use the required-permissions or permission-posture surfaces to compare granted versus required permissions.
5. If the platform still shows stale permission state, clear caches with:

```bash
cd apps/platform && ./vendor/bin/sail artisan cache:clear
```

## Least-Privilege Notes

- Read-only evaluation or inventory-focused setups can often begin with the read permissions only.
- Any real restore or write lane needs the corresponding `ReadWrite` permission set.
- Conditional Access write access should be treated as a higher-risk permission and granted only when the restore or admin-write lane is intentionally enabled.
- Scope-tag restore paths require `DeviceManagementRBAC.ReadWrite.All`, not just the read permission.

## References

- [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)
- [Microsoft Intune Graph overview](https://learn.microsoft.com/en-us/graph/api/resources/intune-graph-overview)
- [App registration security best practices](https://learn.microsoft.com/en-us/azure/active-directory/develop/security-best-practices-for-app-registration)
