MSP Tenant Setup - Required Microsoft Tenant Permissions

When an MSP onboards a new TATER client, the technician needs specific Entra ID directory roles in the client tenant to complete the setup. This page documents exactly which roles are required, how to grant them, and how to revoke them when setup is complete.

Audience: MSP technicians setting up TATER for a new client. If you are the client's IT administrator and you are setting up TATER for your own organization, you are likely already a Global Administrator and don't need this page - just run the per-client provisioning script.

Why specific roles are needed

TATER's per-client setup creates resources in the client's Entra ID tenant and grants the TATER scanner app a specific set of permissions:

Create an Entra ID app registration ("TATER-{ClientName}-ComplianceScanner")
Configure 13 Microsoft Graph application permissions on the new app (User.Read.All, Group.Read.All, Directory.Read.All, Policy.Read.All, Reports.Read.All, AuditLog.Read.All, RoleManagement.Read.Directory, IdentityRiskyUser.Read.All, UserAuthenticationMethod.Read.All, Organization.Read.All, plus 3 Intune device-management permissions)
Grant tenant-wide admin consent for those permissions
Assign Exchange.ManageAsApp to the new app on the Exchange Online service principal
Add the scanner app to Global Reader for read-only Exchange/Defender queries; certificate authentication is also required
Grant the new app three Microsoft Defender for Endpoint application permissions (Machine.Read.All, Vulnerability.Read.All, Software.Read.All) - for endpoint scanning

For initial scanner app creation, application-permission consent and the read-only role assignment, use Global Administrator, or Application Administrator + Privileged Role Administrator in the client tenant. Security Administrator alone is insufficient. The service administrator roles below concern separate management tasks, not a requirement to grant Graph application permissions.

Initial provisioning roles and optional service tasks

Role	Why it's needed
Application Administrator	Create the TATER scanner app registration. Manage its API permissions, certificates, and properties.
Privileged Role Administrator	Assign the read-only scanner Global Reader role and grant application admin consent. This is separate from the technician's own Exchange or Intune task roles.
Exchange Administrator (optional service tasks)	Needed for separately authorized Exchange administration tasks; not required solely to grant the scanner Graph app-role consent. Grant Exchange.ManageAsApp plus read-only RBAC through the documented setup path.
Security Administrator (optional service tasks)	Needed for separate Defender administration when that task requires it. Granting application permissions is an admin-consent operation; Privileged Role Administrator can grant that consent.
Intune Administrator (optional service tasks)	Needed for separate Intune administration when that task requires it. It is not a substitute for the Privileged Role Administrator needed to consent Microsoft Graph application permissions.

Separate the identities: the technician needs provisioning authority temporarily. The scanner app receives Global Reader for read-only Exchange/Defender queries, plus its application permissions and certificate. Do not grant Global Administrator to the scanner. Review any Exchange write-capable role separately.

Plus: Azure subscription permissions (separate from Entra)

If the client wants TATER to host their scanning Automation Account inside their own Azure subscription (rather than relying on TATER Security's shared scanning infrastructure), the MSP technician also needs Owner or Contributor on the target Azure subscription. This is an Azure RBAC assignment, separate from Entra ID directory roles, and is granted through the Azure portal's Subscription → Access Control (IAM) blade.

Legacy PowerShell helper: broader technician-role bundle

The existing helper grants the broader five-role technician bundle (or Global Administrator with its explicit flag). It is not the minimum required for scanner provisioning. Review which separate management tasks need that bundle before running it. The helper prompts for a technician UPN; it does not configure the scanner app's Global Reader role.

Download

Download Grant-TATERSetupRoles.ps1

Usage

Clear-Host
# Legacy broader five-role bundle for separately authorized management tasks
.\Grant-TATERSetupRoles.ps1 -UserPrincipalName 'tech_msp.com#EXT#@acme.onmicrosoft.com'

# Or grant Global Administrator instead (simpler, broader)
.\Grant-TATERSetupRoles.ps1 -UserPrincipalName 'tech_msp.com#EXT#@acme.onmicrosoft.com' -UseGlobalAdmin

# After setup is complete, revoke everything you granted
.\Grant-TATERSetupRoles.ps1 -UserPrincipalName 'tech_msp.com#EXT#@acme.onmicrosoft.com' -Revoke

# Preview without making changes
.\Grant-TATERSetupRoles.ps1 -UserPrincipalName 'tech_msp.com#EXT#@acme.onmicrosoft.com' -WhatIf

What the script does

Installs the Microsoft.Graph PowerShell modules if missing (CurrentUser scope)
Prompts you to sign in interactively as a Global Administrator of the client tenant
Looks up the target user by UPN
Activates each directory role in its broader bundle (idempotent - no-op if already active)
Adds the user to each role (skips if already assigned)
Prints a summary and reminds you to revoke after setup

Requirements

PowerShell 7+ (recommended) or 5.1
An account with Global Administrator on the client tenant (the connecting account, not the target user)
Network access to login.microsoftonline.com and graph.microsoft.com

Auditing

Every role assignment shows up in the Entra ID audit log under the connecting admin's identity (Activity: Add member to role / Remove member from role). The script also outputs a per-role status line so you can copy the result into your engagement notes.

If the technician is a B2B guest

Most MSPs invite their techs as B2B guests in the client tenant rather than creating a native account. The UPN format for B2B guests has a quirk:

tech_msp.com#EXT#@acme.onmicrosoft.com

The #EXT# marker and the underscore (instead of @) in the home email are required. You can find the exact UPN in the client's Entra portal under Users → filter "External users only" → click the guest.

GDAP / Delegated Admin alternative

If your MSP relationship uses Granular Delegated Admin Privileges (GDAP) rather than guest invites, you can establish a GDAP relationship that includes these roles. For the initial provisioning flow, the GDAP relationship needs Application Administrator + Privileged Role Administrator. Add service roles only when separately authorized management tasks require them:

Application Administrator
Privileged Role Administrator
Exchange Administrator (optional Exchange management)
Security Administrator (optional Defender management)
Intune Administrator (optional Intune management)

The customer approves the relationship from their tenant; thereafter your MSP staff can elevate into the customer tenant via the Partner Center with these specific roles, without being a guest in the directory at all. This is the cleanest approach for MSPs that frequently onboard and offboard.

Clean-up after setup

Once TATER setup is complete, remove the elevated role assignments from the technician's account. These are technician assignments. Preserve the scanner app's own Global Reader assignment, application consent and certificate; those are still needed by unattended read-only scans.

.\Grant-TATERSetupRoles.ps1 -UserPrincipalName 'tech_msp.com#EXT#@acme.onmicrosoft.com' -Revoke

The script removes the same set it granted. Run it twice (idempotent) if you also passed -UseGlobalAdmin - once with the flag, once without - to be sure both code paths are cleaned up.

Troubleshooting

"Insufficient privileges to complete the operation": The connecting account (not the target) needs Global Administrator. Application Administrator alone cannot grant directory roles to other users.
"User not found": For B2B guests, double-check the UPN format - the #EXT# form is mandatory. Pull it from the Entra portal.
"Role assignment created but the user still can't perform action X": Sign the user out and back in. Entra ID role assignments take effect on next token issuance.
"Module install failed": Run elevated and try Install-Module Microsoft.Graph -Scope AllUsers -Force. Some corporate machines block CurrentUser-scope installs.

Last reviewed: 2026-05-15 · Applies to: TATER Security & TATER Ops · Have questions? Talk to sales.