TontonTools products that interact with Microsoft Entra ID or Microsoft Intune authenticate to Microsoft Graph through an App Registration that you create and control in your own tenant. This page lists the exact permissions each product needs and explains why.
Creating the App Registration
Most TontonTools products can share a single App Registration, scoped to the union of permissions they need. The minimum setup:
- 1
New registration
In the Azure portal, go to Microsoft Entra ID → App registrations → New registration.
- 2
Name and scope
Name the application (for example, "TontonTools Admin"). Leave Supported account types on "Accounts in this organizational directory only" and the Redirect URI empty for now.
- 3
Copy IDs
After creation, note the Application (client) ID and the Directory (tenant) ID from the Overview blade. You will enter these in the TontonTools credentials dialog.
- 4
Choose authentication method
Either upload a .cer public key under Certificates & secrets → Certificates (recommended for production), or create a secret under Certificates & secrets → Client secrets (simpler for testing). For certificates, keep the matching private key in Cert:\CurrentUser\My on the administrator workstation.
- 5
Add permissions
Under API permissions → Add a permission → Microsoft Graph, add the application permissions required by the products you intend to use (see the matrix below).
- 6
Grant admin consent
Click "Grant admin consent for <your tenant>". This is required for application permissions to take effect.
Permission matrix by product
Each TontonTools product that talks to Microsoft Graph has its own mini-table below, listing the exact application (app-only) permissions it requires and why. If you use Interactive authentication instead (delegated permissions), the equivalent delegated scopes apply with the same naming pattern.
| Permission | Why |
|---|---|
| Device.ReadWrite.All | Read and delete device objects in Entra ID. |
| DeviceManagementManagedDevices.PrivilegedOperations.All | Delete (retire/wipe) managed devices in Intune. |
| Permission | Why |
|---|---|
| Device.Read.All | Enumerate Entra ID devices and read approximateLastSignInDateTime. |
| DeviceManagementManagedDevices.Read.All | Enumerate Intune managed devices and read lastSyncDateTime. |
| Device.ReadWrite.All | Delete stale Entra ID devices (optional, for cleanup actions). |
| DeviceManagementManagedDevices.PrivilegedOperations.All | Delete stale Intune devices (optional, for cleanup actions). |
| Permission | Why |
|---|---|
| Device.Read.All | Enumerate Entra ID devices to identify duplicates. |
| DeviceManagementManagedDevices.Read.All | Enumerate Intune devices to identify duplicates. |
| Device.ReadWrite.All | Delete duplicate Entra ID records (optional, for cleanup actions). |
| Permission | Why |
|---|---|
| Device.Read.All | Enumerate Entra ID devices to find orphans (no recent sign-in, no Intune record). |
| DeviceManagementManagedDevices.Read.All | Cross-reference against Intune managed devices to confirm orphan status. |
| Device.ReadWrite.All | Delete confirmed orphan devices from Entra ID (optional, for cleanup actions). |
| Permission | Why |
|---|---|
| User.Read.All | Look up user objects by UPN or display name. |
| Device.Read.All | Enumerate user-device assignments in Entra ID. |
| DeviceManagementManagedDevices.Read.All | Retrieve the primary user assignment from Intune managed devices. |
| Permission | Why |
|---|---|
| Device.Read.All | Look up device objects by display name. |
| DeviceManagementManagedDevices.Read.All | Retrieve the primary user assignment from Intune managed devices. |
| User.Read.All | Resolve the primary user email address. |
| Permission | Why |
|---|---|
| DeviceManagementApps.Read.All | Read Intune mobile app inventory (Update Manager, HTML audit report, drift checks). |
| DeviceManagementApps.ReadWrite.All | Create Win32 LOB / Web Link / winget apps; commit content versions; declare supersedence relationships. |
| Group.Read.All | Enumerate Entra security-enabled groups for per-row assignment in the Migration Cart. |
| Organization.Read.All | Auto-detect the active tenant primary domain via /v1.0/organization (v1.2). |
Delegated permissions (Interactive mode)
If your security policy forbids app-only permissions, all TontonTools products that talk to Graph also support Interactive authentication. In this mode, the administrator signs in with their own Microsoft 365 account through a browser, and Graph calls execute under their delegated permissions.
The delegated scopes follow the same naming pattern (Device.ReadWrite.All, DeviceManagementManagedDevices.PrivilegedOperations.All, etc.) but apply to the signed-in user's effective permissions rather than the application identity. The administrator must hold a role such as Intune Administrator, Cloud Device Administrator, or Global Administrator, depending on the operation.
Interactive mode uses PKCE (Proof Key for Code Exchange) and a loopback redirect — no client secret is stored in TontonTools when this mode is selected.
Verifying permissions are correctly granted
After granting consent, you can verify the configuration:
- 1
Check status
In the Azure portal, open the App Registration → API permissions. Every permission should show "Granted for <your tenant>" in the Status column.
- 2
Open credentials dialog
Run any TontonTools product and open the credentials dialog. Fill in Tenant ID, Client ID, and either Client Secret or Certificate Thumbprint.
- 3
Test connection
Click "Test connection". The product will request a token from Graph and call a minimal endpoint to confirm the permissions are usable.
Common causes of failure
- Admin consent not granted Re-check the Status column in the API permissions blade.
- Wrong permission type Application permissions and delegated permissions are listed separately; make sure you added the right kind for your chosen authentication mode.
- Conditional Access blocks the app Look for "AADSTS50105" or "AADSTS53003" in the error message. Adjust your Conditional Access policies to allow the App Registration.
- Certificate not found Verify the certificate is in Cert:\CurrentUser\My on the workstation where TontonTools is running, and that the thumbprint matches the one configured in the App Registration.
Audit and revocation
Every Graph operation performed by TontonTools is attributed to your App Registration (in app-only mode) or to the signed-in user (in interactive mode). All operations appear in:
- Entra ID → Audit logs for directory changes such as device deletion.
- Entra ID → Sign-in logs for the authentication itself.
- Microsoft Intune → Audit logs for managed device operations.
To revoke TontonTools' access entirely, delete the App Registration or remove its API permissions. The product will lose Graph access immediately.