Availability: Microsoft Entra sync and connection diagnostics require Enterprise Edition and the Pro tier.

Microsoft Entra sync helps MSPs keep client contacts current without manually recreating every user from Microsoft 365. After you connect your partner identity source, AlgaPSA can discover managed Entra tenants, match them to client records, and create or update contacts for those clients.

Throughout this guide, the client names are fictional MSP examples. Use this workflow when your MSP manages clients like GreenLeaf Dental Group, Northstar Accounting, or Pioneer Law Group through Microsoft partner access and wants cleaner contact records for tickets, billing contacts, approvals, and client communication.

Figure 1: The Entra integration opens as a guided setup wizard: Connect, Find tenants, Match to clients, then Preview & pilot.

The Connect step states the permissions requested and the effect on your contacts before you authorize anything — Alga reads tenants and user names, emails, phone numbers, and job titles, and never writes back to Microsoft, reads mail, files, calendars, or Teams messages. Copy for a change record puts that summary on the clipboard for your change-management process.

Two connection methods are offered. Most MSPs should choose Direct Microsoft partner, where Alga talks to Microsoft Graph through your partner relationship. Choose CIPP (CyberDrain Improved Partner Portal) only if you already run a CIPP instance.

What Entra sync does

Area	What AlgaPSA does	MSP benefit
Tenant discovery	Finds managed Microsoft Entra tenants visible to your partner connection.	Reduces manual setup when onboarding multiple Microsoft 365 clients.
Client mapping	Suggests matches between Entra tenants and AlgaPSA clients by domain or name.	Helps avoid syncing GreenLeaf users into the wrong client record.
Contact sync	Creates contacts or links existing contacts by email address.	Keeps service desk and billing contact records aligned with Microsoft 365 users.
Field updates and portal provisioning	Optionally updates name, phone, job title, and related identity fields from Entra. Where enabled, mappings can also control Entra-managed client-portal user provisioning, auto-link SSO behavior, and default portal role assignment.	Lets your MSP choose which system is authoritative for contact details while keeping portal access aligned with Microsoft identity.
Reconciliation	Queues ambiguous matches for human review.	Prevents unsafe merges when more than one contact could match the same Entra user.

Entra sync is designed to be non-destructive. It creates, links, updates, or marks contacts inactive when an Entra account is disabled; it does not delete contacts.

Prerequisites

Before you start, confirm the following:

AlgaPSA access: You are an AlgaPSA administrator with permission to update system settings.
Edition and tier: Microsoft Entra sync requires Enterprise Edition and the Pro tier. Navigate to Settings > General in the sidebar to open Admin Settings, then select Integrations under Data & Integration and open Identity.
Microsoft access: Your Microsoft partner tenant has access to the client tenants you want to sync.
Microsoft partner connection: Use Microsoft delegated partner access for managed tenants.
App registration: The Microsoft Entra app you connect with must be registered for Accounts in any organizational directory (multi-tenant), with the delegated Microsoft Graph permissions ManagedTenants.Read.All, Directory.Read.All, User.Read, and offline_access. A Global Administrator in your own tenant grants admin consent for these when you connect. Each client tenant must also admit the app before its contacts can sync; see Grant the app access in each client tenant.
Client records: Create or review AlgaPSA clients before mapping. Add clear websites, billing email domains, or client names so matching works well.

Recommended setup scenario

For this guide, assume your MSP, Northwind MSP, supports these clients:

Entra tenant	AlgaPSA client	Example sync outcome
GreenLeaf Dental Group	GreenLeaf Dental Group	Creates and links dental office contacts for support tickets and billing questions.
Northstar Accounting	Northstar Accounting	Keeps Microsoft 365 user names and phone numbers current for tax-season support.
Pioneer Legal Services	Pioneer Law Group	Requires review because the Entra tenant name differs from the AlgaPSA client name.
Harbor Clinic	No matching client yet	Can be imported as a new client or skipped until onboarding is ready.

Step 1: Open the Entra integration

Navigate to Settings > General in the sidebar to open Admin Settings.
Select Integrations (under Data & Integration).
Open the Identity category.
Review the Microsoft Entra Integration card.

The setup mode shows four guided steps: Connect, Find tenants, Match to clients, and Preview & pilot. Complete them in order. Nothing is written to your contacts until you have seen a preview and approved it.

Step 2: Connect Microsoft Entra

In the Connection Options area, choose the direct Microsoft partner connection.

Click the direct Microsoft connection option.
Sign in with the appropriate Microsoft partner administrator account.
Review and approve the requested Microsoft permissions.
Return to AlgaPSA and confirm the connection health shows connected.

Operational check: Use a named integration owner, such as your service operations manager or identity lead, so token rotations and permission reviews have a clear owner.

Step 3: Discover managed tenants

After the connection is active, click Run Discovery.

AlgaPSA loads the managed Entra tenants visible to your connection and records the last discovery time. Discovery does not create contacts yet. It only prepares the tenant list for mapping.

After setup, use Run Discovery on the Connection tab when you add a new Microsoft 365 client, complete GDAP setup, or change partner tenant access. Review the refreshed tenant list and mappings before syncing the new client.

Step 4: Map Entra tenants to AlgaPSA clients

Open Review Mappings to confirm how discovered Entra tenants should connect to AlgaPSA client records.

Figure 2: Review auto-matched tenants, choose a client for unmatched tenants, import a new client, or skip tenants that are not ready for sync.

Mapping statuses you may see:

Status	Meaning	Recommended action
Auto-matched	AlgaPSA found a strong match, usually by domain.	Review it, then confirm if correct.
Needs review	AlgaPSA found a possible match but is not confident enough to choose automatically.	Select the correct client manually.
Unmatched	No likely client was found.	Select a client, import as a new client, or skip.
Skipped	You chose not to map this tenant right now.	Remap later when the client is ready.

For example, greenleafdental.example may match GreenLeaf Dental Group automatically. A tenant named Pioneer Legal Services may need manual review if the AlgaPSA client is named Pioneer Law Group.

After reviewing rows, click Confirm Selected Mappings.

Operational check: Do not confirm mappings solely by display name. Check the primary domain, client billing domain, and client website before syncing contacts.

Grant the app access in each client tenant

Discovery reads your partner relationship, so it works as soon as your own tenant has consented. Syncing a client's contacts is different: AlgaPSA reads that client's directory directly, and Microsoft only allows that after the client tenant has admitted your app. A mapped client whose tenant has not granted consent will fail every sync with a credentials error, no matter how the mapping looks.

For each client tenant you mapped:

Open the admin consent page for that tenant in a browser:
```
https://login.microsoftonline.com/<client-tenant-id>/adminconsent?client_id=<your-app-client-id>
```
Replace <client-tenant-id> with the client's Entra tenant ID or their primary domain (for example greenleafdental.example), and <your-app-client-id> with the Application (client) ID of the app you connected with, from App registrations in your own tenant.
Sign in as someone allowed to grant consent in that tenant: the client's own Global Administrator, or your account if your delegated (GDAP) role there permits granting tenant-wide admin consent.
Approve the requested permissions. To verify, open Enterprise applications in that client tenant and confirm your app is listed.

Consent usually takes effect within a few minutes. If a client tenant enforces Conditional Access policies that require multi-factor authentication or a compliant device for external users, those policies can still block sync; see Troubleshooting.

Operational check: Grant consent for one client, run a sync for just that client, and confirm it completes before repeating for the rest.

Step 5: Choose field sync controls

Field sync controls decide which Entra values can overwrite fields on already-linked AlgaPSA contacts.

Common MSP choices:

Field	Typical setting	Why
Display Name	On	Useful when Microsoft 365 is the source of truth for staff names.
Email	Usually Off	Prevents accidental contact routing changes if aliases or UPNs differ.
Phone	On	Keeps help desk callback details current.
Role	On	Keeps job titles such as Office Manager or Controller current.
UPN	Usually Off	Enable only if your team uses UPN for identity troubleshooting.

Click Save Field Sync Controls after changing the switches.

Step 6: Preview, pilot, then run the initial sync

After at least one tenant is mapped, do not sync everything at once. The Preview & pilot step exists to make the first sync boring.

Preview a sync. AlgaPSA reports exactly what a run would do — contacts it would create, link, update, inactivate, and queue as ambiguous — without writing anything. Read it before you approve it.
Pilot a single client. Run the sync against one mapped tenant only. Pick a client you know well, ideally a small one, and check the resulting contacts by hand.
Run the rest. Once the pilot looks right, run the remaining tenants.

This sequence catches the two mistakes that are expensive to undo at scale: a tenant mapped to the wrong client, and field sync controls that overwrite contact details you meant to keep.

When you are ready, click Run Initial Sync.

During the sync, AlgaPSA processes each mapped tenant and handles users as follows:

Ignored: Disabled accounts, users without valid email identities, and common service account patterns are skipped.
Created: New people are created as contacts under the mapped AlgaPSA client.
Linked: Existing contacts are linked when there is one clear email match.
Updated: Enabled field sync controls may update linked contact fields.
Queued: Ambiguous matches are sent to the reconciliation queue for review.
Inactivated: Contacts linked to disabled Entra accounts may be marked inactive rather than deleted.

Step 7: The operations console

Once the first sync completes, the setup wizard is replaced permanently by an operations console. The wizard does not come back — the connection is now something you run rather than something you set up.

The console has five tabs:

Tab	What it is for
Overview	Current state at a glance: what is mapped, what synced last, what needs attention
Sync & schedule	Run discovery or a full sync now, preview a run, and set the sync schedule
Clients	Every mapped tenant with its client, and per-client sync results
History	Recent sync runs with per-tenant outcomes
Connection	Credential status, credential rotation, and the exportable connection record

Preview is still available after setup. Use it before any sync that follows a change to mappings or field controls — it is the same non-destructive dry run offered during onboarding.

Rotate a credential in place

The Connection tab rotates the Microsoft credential without dismantling the integration. Tenant mappings, client links, and sync history all survive the rotation, so a scheduled secret rotation is no longer a reason to rebuild the connection.

Export the connection record

Connection also exports the connection record — the permissions granted, when they were authorized, who authorized them, and the current credential state. This is the artifact to attach to a change ticket or hand to an auditor asking what access your PSA holds over client directories.

Monitor sync runs and resolve ambiguous matches

Use the History and Overview tabs to review recent sync runs and clear the ambiguous match queue.

Figure 3: After sync, review run results and resolve ambiguous contact matches before they affect service desk records.

Review sync history

The Recent Sync Runs panel shows:

Run type, such as initial or all-tenants.
Completion status.
Start and completion time.
Number of tenants processed.
Success and failure counts.

Click View details when you need per-client results, such as how many contacts were created, linked, updated, inactivated, or queued as ambiguous.

Resolve ambiguous matches

Ambiguous matches happen when AlgaPSA finds more than one possible contact for the same Entra user. For example, Jordan Lee at GreenLeaf Dental Group might match both an office manager contact and a billing contact.

For each queue item:

Review the Entra user name and email.
Review the candidate contacts.
Choose an existing contact when one is correct, then click Resolve to Existing.
Click Resolve to New if the Entra user should become a separate contact.

Operational check: Assign someone on the service desk or client success team to review ambiguous matches after each initial client onboarding sync.

Ongoing operations checklist

Use this checklist after the initial sync is complete:

Run discovery after adding a new Microsoft 365 client or changing Microsoft partner access.
Preview a sync after changing mappings or field sync controls, before running it.
Review unmapped and skipped tenants monthly.
Check recent sync runs for failed tenants on the History tab.
Clear the ambiguous match queue before major client communication campaigns.
Review field sync controls before turning on email or UPN updates.
Confirm inactive contacts before removing them from client-facing workflows.
Rotate the Microsoft credential on your normal schedule from the Connection tab, and export the connection record when your change process needs evidence.

Related identity features

Entra sync creates and maintains client contacts. Two related capabilities cover people signing in:

Client portal SSO lets client contacts sign in with their own Microsoft accounts, with an Entra access group deciding who gets portal access. Tenant mappings here can also drive portal provisioning mode and default portal role.
SCIM user provisioning lets Entra deactivate and reactivate your own internal AlgaPSA users.

Troubleshooting

Run connection diagnostics

When discovery or contact sync fails, diagnostics help your identity lead find the failing layer before changing credentials or client mappings. Go to Settings > Data & Integration > Integrations > Identity, open the Entra console's Connection tab, and click Run diagnostics beside Validate. Running diagnostics requires the system_settings:read permission.

The dialog walks the connection in order and shows Pass, Warn, Fail, or Skip for each check:

Layer	Direct Microsoft partner connection	CIPP connection
AlgaPSA readiness	Checks access, the saved connection, Microsoft app registration binding and secret, and sync worker and schedule health. Expected app registration values are provided for manual comparison.	Checks access, the saved connection, sync worker and schedule health, and CIPP credentials. A Direct Microsoft app registration is not required for CIPP.
Authentication and reachability	Refreshes the partner token, checks its scopes, and tests Microsoft Graph access.	Tests the CIPP API address and API credential.
Tenant discovery	Reads managed tenants and compares them with confirmed client mappings.	Reads CIPP's tenant list and compares it with confirmed client mappings.
Sync health	Reviews recent runs, the latest per-client results, and the reconciliation queue.	Reviews the same local sync history and reconciliation queue.

If a layer fails, dependent checks stop and show Skip with a Blocked by explanation. Independent checks, such as local sync history, still run. Expand the failed step and follow Recommendations: Microsoft failures retain the AADSTS code alongside the named remedy, so an expired secret, missing consent, and a Conditional Access requirement lead to different fixes. For CIPP authentication failures, check the API credential in CIPP rather than replacing a Direct Microsoft app secret.

For example, AADSTS7000222 calls for rotating the app secret in Microsoft and updating it in AlgaPSA. AADSTS65001 calls for consent in the tenant named by the failure. Partner consent requires reconnecting afterward; missing consent in GreenLeaf's tenant must be resolved in GreenLeaf's tenant.

If the connection passes but a particular client still fails, select that client under Selected client diagnostics and click Run client diagnostics. The client results name the affected tenant and remedy. Re-run the checks after applying the fix.

Export evidence and refresh discovery

Use Copy support bundle or Download JSON to share the diagnostic result with support. Exports redact identifiers by default and exclude full tokens and secrets while retaining request IDs for investigation. Include identifiers in export lets you retain identifiers when support needs that context; it does not include full credentials.

Diagnostics inspect the connection without changing client mappings or contacts or starting a sync. Token refresh can renew stored authentication tokens. To refresh the saved tenant list after setup or a partner-access change, return to Connection and click Run Discovery, then review mappings before syncing contacts.

Common problems

Problem	What to check
The Identity category is missing	Confirm Enterprise Edition and Pro tier access.
Discovery finds no tenants	Confirm Microsoft partner access and GDAP relationships.
A sync or preview fails with "Microsoft rejected the stored credentials" and `consent_required` or `AADSTS65001`	The app has not been granted admin consent in that client's tenant. Follow Grant the app access in each client tenant; reconnecting your own tenant does not fix this.
The error mentions `AADSTS700016`	Your app registration is limited to your own directory. In App registrations > Authentication, set supported account types to Accounts in any organizational directory, then retry.
The error mentions `AADSTS50076` or `AADSTS50079`	A Conditional Access policy in the client tenant requires multi-factor authentication or a compliant device for your account. Review that tenant's policies for external users with the client's administrator.
Discovery and mapping work, but every sync for a client fails with a credentials error	Work through the three rows above in order: client-tenant consent first, then app registration account types, then Conditional Access. Sync history shows the exact Microsoft error code for each run.
A tenant matched the wrong client	Do not confirm it. Select the correct client manually or improve the client website/billing domain first.
A tenant is unmatched	Select a client manually, import it as a new client, or skip it until onboarding is ready.
Contacts are not updating	Check field sync controls; only enabled fields can overwrite linked contacts.
Service accounts appear in sync	Add exclusion patterns for naming conventions such as `svc-`, `automation`, or `noreply`.
A user matched multiple contacts	Resolve the item in the ambiguous match queue instead of creating duplicates.

Best practices for MSPs

Keep client domains accurate in AlgaPSA before running discovery.
Map tenants in batches and review each domain before confirming.
Leave email overwrite disabled unless your operations team has agreed that Entra should control contact email addresses.
Use the reconciliation queue as part of onboarding closeout for new managed clients.
Treat disabled Entra accounts as an offboarding signal, but review important billing or executive contacts before removing them from workflows.

Navigation

20.10. Sync Microsoft Entra Tenants and Contacts for MSP Clients