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 Could not assign user to GDAP relationship 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.

​

Connected user is missing Partner Center access

Before you can onboard any tenant, the connected Partner Center user has to be able to manage GDAP from your own MSP tenant. Petra checks this on the managed tenants page and, if either requirement below is missing, shows a banner and disables Onboard and Scan until it is fixed. Both are one-time setup steps in your own MSP tenant, and your customers are not involved. The page re-checks every few seconds, so the banner clears on its own once the change takes effect (a hard refresh also works).

​

Grant the Groups Administrator role

Petra creates a security group named Petra GDAP Access Group in your MSP tenant to hold the GDAP access assignments. Creating and managing that group requires the Entra Groups Administrator role (Global Administrator also satisfies it). If the connected user does not have it, grant it:

1. Sign in to the Microsoft Entra admin center with an account that can assign roles (Privileged Role Administrator or Global Administrator).
2. Go to Identity → Roles & admins → Roles and open Groups Administrator.
3. Click Add assignments, select the connected Partner Center user, and assign the role as Active.
   • If Entra refuses with “this assignment already exists,” the user already has an eligible assignment through Privileged Identity Management (PIM), and Entra won’t allow a second active assignment on top of it. Eligible alone does not satisfy this banner, so fix it by activating the existing assignment instead:
   • Go to Identity Governance → Privileged Identity Management → Microsoft Entra roles → My roles, find Groups Administrator under Eligible assignments, click Activate, and confirm.
   • If the user does not use PIM, an active assignment already exists and should take effect within a few minutes, so no further action is needed.
4. If your organization assigns roles through PIM, activate the eligible assignment under Identity Governance → Privileged Identity Management.

Petra reads the live role assignment (not a cached token), so the banner clears within a few seconds of the role becoming active.

​

Add the user to the AdminAgents group

AdminAgents is a Microsoft-managed security group in your MSP tenant that grants delegated-admin (GDAP) capability. The connected user must be a direct member of it to create GDAP relationships and receive access assignments. You add the user to the group in Entra — there is nothing to select in the Partner Center role list:

1. Sign in to the Microsoft Entra admin center.
2. Go to Identity → Groups → All groups and search for AdminAgents (usually written without a space).
3. Open the group, select Members → Add members, and add the connected Partner Center user.
4. Alternatively, go to Identity → Users, open the connected user, select Groups → Add memberships, and add AdminAgents.

Membership takes effect immediately; the banner clears on the next automatic re-check.

​

Connection and sign-in errors

These errors happen while you connect or re-authenticate Partner Center, before any tenant is onboarded. Microsoft returns them during sign-in, and Petra shows the reason on the managed tenants page with a Try connecting again button.

​

Tenant not set up for Partner Center

Microsoft rejected the sign-in (AADSTS650052) because the tenant you signed in with does not have the Microsoft Partner Center service principal. This almost always means you signed in with an account that is not in your Microsoft Partner Center (CSP) tenant, or that tenant has never consented to the Partner Center app.

1. Sign in with a Global Administrator in your Partner Center (CSP) tenant, not a customer tenant or a secondary tenant.
2. If that is the correct tenant, a Global Administrator must consent to the Microsoft Partner Center application so its service principal is created. Accept the consent prompt during sign-in.
3. Confirm your organization has an active Microsoft Partner Center / CSP enrollment, then click Try connecting again.

​

Consent was declined

The sign-in was cancelled at the Microsoft permission prompt (AADSTS65004), so Petra was not granted the access it needs.

1. Click Try connecting again.
2. At the Microsoft prompt, review the requested permissions and click Accept.
3. You must be signed in as an admin who can consent on behalf of the tenant.

​

Sign-in session expired

Your previous Partner Center sign-in expired or was revoked (AADSTS50173, AADSTS65001, AADSTS700082).

1. Click Try connecting again and complete sign-in with your connected Partner Center account.

​

Partner Center Onboarding Errors

When onboarding fails, the tenant’s Petra Status column shows the error in red; hover to read the full message. Find your message below for what it means and exactly how to fix it. Most fixes are made in Microsoft Partner Center, the Microsoft Entra admin center, or the Microsoft 365 admin center of your MSP or the customer tenant.

​

Connected user lacks GDAP access

The connected Partner Center user is not authorized to manage this customer tenant. It needs the Admin agent role in Partner Center and access to the customer’s GDAP security group.

1. In Partner Center, go to Settings → Account settings → User management and confirm the connected user has the Admin agent role.
2. In Petra, click Assign User for the tenant — this adds the connected user to the GDAP security group and the relationship. (Or add the user to the group manually in Partner Center.)
3. Retry, or re-authenticate with an account that already has access.

​

Missing Groups Administrator role

Petra could not create or update the Petra GDAP Access Group in your MSP tenant because the connected user lacks the Entra Groups Administrator role.

1. In the Microsoft Entra admin center, go to Roles & admins → Roles and open Groups Administrator.
2. Click Add assignments and add the connected user. If the role is assigned through PIM, activate it under Identity Governance → Privileged Identity Management.
3. In Petra, open the overflow menu (three dots) and click Re-authenticate with Microsoft Partner Center, then retry.

​

GDAP relationship already exists or is pending

Microsoft refused to create the GDAP relationship, usually because one is already active or awaiting approval, or delegated administration is turned off in the customer tenant.

1. In Partner Center, open Customers and find this tenant, then check its GDAP relationships.
2. Approve a pending request (the customer’s Global Administrator must approve it) or terminate a stale one.
3. Retry.

​

App installed but tenant record not saved

The application installed in the customer tenant, but Petra could not save the tenant record on our side. This is usually transient.

1. Retry.
2. If it keeps failing, contact support@petrasecurity.com.

​

Permission grant failed

One or more required permissions could not be granted in the customer tenant. This usually points to a GDAP role or consent gap.

1. Confirm the GDAP relationship is active and includes the required admin roles (Global Administrator, or Application Administrator or Cloud Application Administrator plus Privileged Role Administrator).
2. If the message includes an admin-consent link, have the customer’s Global Administrator open it and approve.
3. Retry. If it persists, contact support@petrasecurity.com.

​

No Exchange Online license

The customer tenant has no Exchange Online-capable license or mailbox, so Exchange Online was never provisioned and its service principal does not exist.

1. In the Microsoft 365 admin center of the customer tenant, go to Users → Active users and assign at least one account a license that includes Exchange Online (for example Business Basic/Standard/Premium or an Office/Microsoft 365 E-plan).
2. Wait a few minutes for Exchange Online to provision, then retry.

​

Temporary Microsoft error

Microsoft returned a transient error during onboarding.

1. Wait a few minutes and retry.
2. If it keeps failing, contact support@petrasecurity.com.

​

Could not assign user to GDAP relationship

Petra could not bind the connected user to this tenant’s GDAP relationship. This is usually a short propagation delay after the access assignment is created.

1. Wait about two minutes and retry.
2. If it persists, click Assign User in the Actions column, then retry.
3. Confirm the GDAP relationship is active and includes the required admin roles.

​

Conditional Access policy is blocking

A Conditional Access policy in the customer tenant is blocking the connected account (often treating it as a guest or external user). The error names the specific policy when Petra can resolve it.

1. In the customer tenant’s Microsoft Entra admin center, go to Protection → Conditional Access → Policies and open the named policy.
2. Under Assignments → Users, add the connected account to Exclude (or disable the policy).
3. Retry.

​

Application still provisioning

Petra’s application or its service principal is not fully registered in the customer tenant yet. Microsoft is still provisioning it.

1. Wait a few minutes and retry.
2. If it persists, re-grant consent from the managed tenants table (Grant Perms in the Actions column).

​

Connection expired

The Partner Center connection expired or was revoked, often after a password change or MFA reset on the connected account.

1. In Petra, open the overflow menu (three dots) at the top of the managed tenants table.
2. Click Re-authenticate with Microsoft Partner Center and sign in again.
3. Retry.

​

Tenant already onboarded

This tenant already exists in your organization.

1. Refresh the page; it should show as onboarded.
2. If it still shows as failed, contact support@petrasecurity.com.

​

Rate limited

Microsoft throttled the request because too many calls were made in a short window.

1. Wait the number of seconds shown in the message (or about a minute), then retry.

​

Multi-factor authentication required

The connected Partner Center account must complete multi-factor authentication before it can be used.

1. Complete MFA setup for the connected account at aka.ms/mfasetup, or finish the prompt at the next Microsoft sign-in.
2. In Petra, open the overflow menu (three dots) and click Re-authenticate with Microsoft Partner Center, then retry.

​

Connected account not recognized in this tenant

The connected Partner Center account is not a member or guest of the customer tenant, so direct access fails.

1. Onboard through your GDAP relationship rather than direct access; confirm the customer’s GDAP relationship is active in Partner Center.
2. Alternatively, have the customer add the account to their tenant.
3. Retry.

​

Tenant not found

Microsoft could not find the customer tenant.

1. Confirm the tenant still exists and that its tenant ID is correct in Partner Center.
2. Retry.

​

Tenant disabled by Microsoft

The customer tenant is disabled or blocked by Microsoft.

1. Confirm the tenant is active in Microsoft 365 (check with the customer or Microsoft support).
2. Once active, retry.

​

Compliant device required

A Conditional Access policy in the customer tenant requires a compliant device but is not fully configured.

1. In the customer tenant’s Microsoft Entra admin center, go to Protection → Conditional Access → Policies and finish configuring the compliant-device requirement, or exclude the connected account under Assignments → Users → Exclude.
2. Retry.

​

Device authentication blocked

Microsoft blocked the sign-in with a device requirement.

1. From a registered, compliant device, open the overflow menu (three dots) in Petra and click Re-authenticate with Microsoft Partner Center.
2. Retry.

​

Disabled guest account

The connected account is a disabled guest in the customer tenant.

1. In Petra, open the overflow menu (three dots) and click Re-authenticate with Microsoft Partner Center using an account that has GDAP access to this tenant.
2. Alternatively, have the customer re-enable the guest account.
3. Retry.

​

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.