Microsoft Partner Center

​

Overview

If you manage client tenants through Microsoft Partner Center, you can connect Petra directly to your CSP account. This lets you see all of your GDAP-managed tenants in one place, onboard them to Petra without needing each client’s Global Admin to approve individually, and manage permissions across tenants from a single table. Partner Center integration is available at app.petrasecurity.com/portal and is also offered during onboarding.

​

Prerequisites

Before connecting, confirm the following:

1. You have a Microsoft Partner Center account with active GDAP relationships for the tenants you want to manage.
2. The user connecting Partner Center is in the AdminAgents security group in your MSP tenant.
3. The Azure AD application Petra M365 Security Analyzer is registered with delegated permissions. If you have not done this before, Petra will walk you through it during setup.

​

Connecting Partner Center

1. Go to app.petrasecurity.com/portal, or click Add Tenant from the navbar and choose Continue with Partner Center.
2. Click Connect Microsoft Partner Center.
3. Sign in with your MSP tenant credentials on the Microsoft login page and consent to the requested permissions.
4. After approval, you are redirected back to Petra. Your managed tenants will appear automatically.

​

Managing Tenants

Once connected, the managed tenants table shows every client tenant that has an active GDAP relationship with your MSP.

​

What the table shows

​

Syncing tenants

Petra automatically syncs your managed tenants from Microsoft Partner Center each time you open the managed tenants page. You can also manually sync by clicking Sync Tenants (in the overflow menu at the top of the table). Both actions query your GDAP relationships and update tenant names, user counts, and permission status.

​

GDAP permission requirements

To onboard a tenant through Partner Center, your GDAP relationship must include either:

• Global Administrator, or
• Application Administrator or Cloud Application Administrator, plus Privileged Role Administrator

If you do not have Global Administrator, the relationship needs Privileged Role Administrator in addition to Application Administrator or Cloud Application Administrator. If a tenant shows Missing under GDAP Permissions, click Request to create a new GDAP relationship request. You will receive a link that the client’s admin needs to approve. If a tenant shows Ready but you need to update the GDAP relationship with additional roles, click Re-request Permissions in the Actions column. This creates a new GDAP relationship request that includes all required roles for Petra.

​

Onboarding a Tenant

1. Find the tenant in the managed tenants table.
2. Confirm that GDAP Permissions shows Ready.
3. Click Onboard. The Add Tenant modal opens.
4. Review the defaults and adjust if needed (Petra Response, Scan-only). See Onboard a Tenant for details.
5. Review the Review Onboarding summary, then click Onboard Tenant.

Petra installs the application into the client tenant and grants the required permissions automatically using your GDAP relationship. No action is required from the client’s admin.

​

Refreshing email permissions

If a tenant’s email permissions need to be refreshed (for example, after permissions were revoked or modified), you can refresh them directly from the managed tenants table:

1. Find the tenant in the managed tenants table.
2. Click Refresh in the Email Perms column for that tenant.

This action:

• Assigns GDAP access if needed (using the Assign User flow)
• Runs the consent flow to grant all Graph permissions on the service principal
• Updates delegated permissions (oauth2PermissionGrants) for Microsoft Graph
• Grants application permissions (appRoleAssignments) required for email operations

The refresh operation only works for tenants that were onboarded through Partner Center. If a tenant was added through the Single Tenant flow, you’ll need to update permissions outside of Partner Center.

​

Batch onboarding

You can onboard multiple tenants at once. Select the tenants you want using the checkboxes, then click Onboard. The Add Tenant modal opens showing how many tenants are selected, with an expandable list of tenant names. Review the defaults and click Onboard to apply the same settings to all selected tenants.

​

Migrating Legacy Tenants

If you originally onboarded a tenant individually (outside of Partner Center) and later established a GDAP relationship with that tenant, you can migrate it to Partner Center management. Migrating gives you the same centralized permission management and bulk operations available to tenants that were onboarded through Partner Center. Legacy tenants are marked with a Legacy badge in the managed tenants table.

​

What migration does

When you migrate a legacy tenant, Petra:

1. Assigns your user to the GDAP relationship for the tenant. If this step fails, migration stops and you see an error. See GDAP Assignment Errors for how to resolve it.
2. Installs the Partner Center application into the client tenant using your GDAP relationship.
3. Grants all required Graph and Exchange permissions through the Partner Center app.
4. Verifies that every required permission was granted successfully.
5. Switches the tenant to use the Partner Center app instead of the individually installed app.

After migration, the tenant is managed through Partner Center exactly like a tenant that was onboarded through Partner Center from the start. You can refresh permissions, re-sync, and manage it from the managed tenants table.

​

Prerequisites

Before migrating a legacy tenant, confirm the following:

1. The tenant has an active GDAP relationship with your MSP that includes the required admin roles (Global Administrator, or Application Administrator or Cloud Application Administrator plus Privileged Role Administrator).
2. The tenant’s GDAP Permissions column shows Ready in the managed tenants table.
3. The tenant is currently onboarded and shows the Legacy badge.

​

Migrating a single tenant

1. Find the legacy tenant in the managed tenants table (look for the Legacy badge).
2. Click Migrate to Partner Center in the Actions column.
3. Confirm the migration in the modal that appears.
4. Petra installs the Partner Center app, grants permissions, and verifies them. This typically takes a few seconds.
5. When migration completes, the Legacy badge is removed and the tenant is managed through Partner Center.

​

Batch migration

You can migrate multiple legacy tenants at once. Select the legacy tenants using the checkboxes, then click Migrate to Partner Center. Petra processes them in the background and updates the table as each one completes.

​

Re-authenticating

If your OAuth session expires or you need to switch the connected account, open the overflow menu at the top of the table and click Re-authenticate with Microsoft Partner Center. This runs the same Microsoft sign-in flow as initial setup and replaces the stored credentials.

​

How Petra Connects to Your Partner Center

​

Step 1: Initial authentication

When you connect Partner Center, Petra redirects you to Microsoft’s login page (login.microsoftonline.com) where you sign in with your MSP tenant credentials. You are asked to consent to the following permissions:

• Microsoft Graph: DelegatedAdminRelationship.Read.All, DelegatedAdminRelationship.ReadWrite.All, User.Read.All, Organization.Read.All, Directory.ReadWrite.All, Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All
• Partner Center API: user_impersonation

These are all delegated permissions, meaning they act on behalf of the signed-in user and are scoped to what that user is authorized to do.

​

Step 2: Discovering client tenants via GDAP

When you sync tenants, Petra uses the stored refresh token to get a Microsoft Graph access token, then queries the tenantRelationships/delegatedAdminRelationships endpoint filtered to status eq 'active'. This returns only GDAP relationships that have been explicitly approved by the client tenant. Petra reads the roles and customer tenant IDs from these relationships and stores them locally for display.

​

Step 3: Onboarding a client tenant

When you click Onboard, two things happen:

1. Delegated permission consent via Partner Center API. Petra calls the Partner Center /v1/customers/{tenantId}/applicationconsents endpoint. This is Microsoft’s CPV (Control Panel Vendor) API, which installs the Petra application into the client tenant and grants delegated permissions (Graph, Exchange, Office 365 Management APIs). This operation is governed by the GDAP relationship and only succeeds if an active relationship with the required admin roles exists.
2. Application permission grants via Graph API. After the service principal is installed, Petra obtains a customer-tenant-scoped Graph token (using the GDAP relationship) and creates appRoleAssignment entries on the Petra service principal. These are the application-level permissions needed for background operations like reading audit logs and managing mailbox settings without user context.

​

Security

• All access is mediated through GDAP. Petra cannot access any client tenant that has not approved a GDAP relationship with your MSP. If the relationship is terminated or expires, access is revoked.
• Delegated context. The Partner Center consent and Graph API calls operate in the context of the authenticated MSP admin user, bounded by their GDAP role assignments.
• No direct credentials. Petra does not store or use any client tenant passwords, certificates, or secrets. Access is entirely through OAuth tokens derived from the GDAP relationship.
• Revocable at any time. You can disconnect Partner Center from Petra at any time. Client tenants can terminate the GDAP relationship to immediately revoke access.

​

Troubleshooting

If you encounter errors while onboarding tenants or syncing permissions, Petra now provides specific, actionable error messages to help you resolve the issue.

​

GDAP Access Errors

“The Partner Portal user does not have GDAP access to customer tenant” This error (AADSTS50177) means the user you authenticated with does not have access to the customer tenant through the GDAP security group. To resolve:

1. Add the authenticated user to the GDAP security group that grants admin access to this customer tenant in Microsoft Partner Center.
2. Alternatively, reconnect the Partner Portal with a different user who already has GDAP access to this tenant.

The error message will include the authenticated user’s email and the customer tenant name to help identify which relationship needs to be fixed. “Operation not allowed: tenant already has an active GDAP relationship” This error (403 disallowedOperation) occurs when you try to create a new GDAP relationship request for a tenant that already has an active relationship. To resolve:

1. Check the managed tenants table to see if the tenant already appears with an active GDAP relationship.
2. If the relationship exists but shows Missing permissions, the relationship may need to be updated with the required roles rather than creating a new one.
3. If you need to create a new relationship, first terminate the existing one in Microsoft Partner Center.

“GDAP relationship request failed: duplicate display name” This error (400) occurs when you try to create a GDAP relationship with a display name that already exists for another relationship. To resolve:

1. Use a unique display name for the new GDAP relationship request.
2. Display names must also meet Microsoft’s length requirements (Petra validates this automatically).

​

GDAP Assignment Errors

“Could not assign your user to the GDAP relationship for this tenant” This error appears during onboarding or migration when Petra cannot assign your user to the GDAP relationship for the target tenant. If the assignment fails, the operation stops immediately, and no changes are made to the tenant. To resolve:

1. Wait a couple of minutes and retry. Microsoft sometimes takes a moment to propagate GDAP relationship changes.
2. Verify that the GDAP relationship is active and includes the required admin roles (Global Administrator, or Application Administrator or Cloud Application Administrator plus Privileged Role Administrator).
3. Confirm that the authenticated user is in the GDAP security group for this customer tenant.
4. If the issue persists, check the GDAP relationship in Microsoft Partner Center for any pending or degraded state.

​

Permission Errors

“The Partner Portal user does not have sufficient permissions to manage customer tenant” This error (often “Unsupported token”) indicates one of the following:

1. The authenticated account does not have the Admin Agent role in Microsoft Partner Center.
2. The Azure AD application is not properly consented in your MSP tenant.
3. The user is not a member of the GDAP security groups for your customer tenants.

To resolve:

1. Verify the user has the Admin Agent role in Partner Center.
2. Ensure the user is a member of the GDAP security groups for your customer tenants.
3. If needed, reconnect the Partner Portal to refresh the consent and permissions.

​

Session Expiration Errors

“The Partner Portal authorization has expired or been revoked” (AADSTS65001) “The Partner Portal session has expired” (AADSTS700082) These errors indicate your OAuth session has expired or been revoked. To resolve:

1. Click Re-authenticate with Microsoft Partner Center from the overflow menu at the top of the managed tenants table.
2. Sign in again with your MSP tenant credentials and consent to the requested permissions.

​

Migration Errors

“No existing legacy tenant found to migrate” This error means the tenant was not onboarded individually before. Migration is only for tenants that were originally added outside of Partner Center. If the tenant is not yet onboarded, use Onboard instead. “This tenant is already managed by Partner Center” The tenant has already been migrated or was onboarded through Partner Center originally. No action is needed. “This tenant does not have the required GDAP permissions for migration” The GDAP relationship for this tenant is missing one or more of the required admin roles. Request a new GDAP relationship with the required roles (Global Administrator, or Application Administrator or Cloud Application Administrator plus Privileged Role Administrator), then retry the migration. “Migration failed: could not grant permissions” Petra installed the Partner Center app but could not grant all required permissions. The error message lists which permissions failed and why. To resolve:

1. Check that the GDAP relationship is active and includes the required admin roles.
2. If an admin consent URL is provided in the error message, have a tenant admin grant consent using that URL.
3. Retry the migration after resolving the permission issues.

“Migration failed: only X of Y permissions verified” Petra installed the app and attempted to grant permissions, but verification found that some permissions are missing. The error message lists the missing permissions. To resolve:

1. Review the missing permissions listed in the error message.
2. Verify the GDAP relationship includes the required admin roles.
3. Retry the migration. If the issue persists, contact support@petrasecurity.com.

​

Application Permission Grant Failures

“Failed to grant application permissions” or “Failed to grant Graph API permissions” When onboarding or syncing permissions, Petra grants both delegated permissions (via Partner Center) and application permissions (via Graph API). If application permissions fail to grant, you may see:

• A message indicating which specific permissions failed.
• An error if all permissions failed individually.

These errors typically indicate a GDAP relationship issue or insufficient permissions. Check that:

1. The GDAP relationship is active and includes the required admin roles.
2. The authenticated user has the Admin Agent role in Partner Center.
3. The user is a member of the GDAP security group for this customer tenant.

If delegated permissions synced successfully but application permissions failed, Petra will surface the specific error instead of silently claiming success. “Cannot onboard tenant: failed to grant permissions” This error occurs when one or more required permissions fail to grant during onboarding. Petra blocks onboarding in this case because without the full set of permissions, monitoring and protection cannot function properly. The error message will list which specific permissions failed and why. To resolve:

1. Review the permission failures listed in the error message.
2. If an admin consent URL is provided, have a tenant admin grant consent using that URL.
3. Verify the GDAP relationship includes the required admin roles (Global Administrator, or Application Administrator or Cloud Application Administrator plus Privileged Role Administrator).
4. Retry onboarding after resolving the permission issues.

​

FAQs

​

Does connecting Partner Center affect my clients?

No. Connecting only reads your existing GDAP relationships. Nothing is installed in any client tenant until you explicitly click Onboard.

​

Can I use a service account instead of my personal account?

Yes. The current implementation authenticates using a specific MSP admin user’s OAuth session. If you prefer, you can use a dedicated service account within your MSP tenant. The key requirement is that the account has the Admin Agent role in Partner Center and is a member of the security group assigned to your GDAP relationships.

​

What happens if a GDAP relationship expires?

Petra’s access to that tenant is revoked along with the relationship. Monitoring of already-onboarded tenants continues, but the tenant list in Petra will no longer sync with Partner Center. New tenants added in Partner Center will not appear in Petra until a new GDAP relationship is established and the tenant is reconsented.

​

Can I onboard tenants without Partner Center?

Yes. You can add tenants individually by clicking Add Tenant and choosing Add tenants individually. This uses a direct Microsoft OAuth flow where the client’s Global Admin consents to the Petra app. See Add Individually for the step-by-step guide.

​

Who in my organization can use Partner Center?

Any member with the Admin or Full Member role who has tenant management permissions can access the Partner Center page. External Guests and Billing members cannot.

​

Can I disconnect Partner Center?

Yes. Re-authenticate with a different account or contact support@petrasecurity.com to remove the connection entirely. Disconnecting does not remove tenants that have already been onboarded.

​

Do I need to turn on audit logs before onboarding?

Audit logs should be enabled on the client tenants you plan to onboard. There is no cost to enable them regardless of Microsoft licensing. If you manage the tenant, they are likely already enabled. Petra needs audit log data to detect and investigate threats.