Test connection / Test permissions

Before you trust a school's Google Workspace or Microsoft Entra sync — or when something looks wrong — Test connection and Test permissions answer the question directly, using the exact credentials and environment the real sync engine uses, without touching anything.

The golden rule

This never changes anything. The check only reads — it lists a handful of users/groups, reads a token's granted permissions, and (for Entra) acquires a client-credentials token. It never creates, updates or deletes a user, group, licence, classroom or any other record on Google or Microsoft's side. A pass here is a real statement about whether the live sync will work, not a simulation.

Test connection vs. Test permissions

Test connection — the minimal check: can we authenticate and make one trivial read? This confirms the service account (Google) or the tenant/client/secret (Entra) actually work.
Test permissions — the fuller check: connection, plus a checklist of every capability the sync actually needs for this school — users, groups, organisational units, Google Classroom, Entra licensing, administrative units — based on which of those the school has switched on. Only the areas the school actually syncs are checked; the rest show as not applicable.

Both produce a result you can come back to later; you don't have to wait on the page.

Steps

Step 1 — Open Test connection {#step-1}

For one school: go to Sync → Test connection (/v2/admin/sync/connection-test). Only the platforms the school actually uses (Google, Entra, or both) show a card — if neither is enabled, the page tells you there's nothing to test yet.

Step 2 — Run a test {#step-2}

Each platform card has two buttons: Test connection and Test permissions. If the school uses both Google and Entra, an extra "Test both platforms" bar at the top runs the same check across both at once. Select a button to queue the check — it runs on the real sync engine's queue, so results usually land within a few seconds; the page polls automatically while a test is in progress.

Step 3 — Read the result {#step-3}

Each result shows a status pill and a checklist:

Symbol	Meaning
✓ (green check)	Granted — this capability works
✗ (red cross)	Missing or insufficient — the check ran but failed; the detail line explains why (for Google, an unauthorised scope; for Entra, a permission the app registration hasn't been granted)
— (grey dash)	Not applicable — this school doesn't sync this feature (e.g. Google Classroom is off), so it wasn't checked

The overall pill above the checklist rolls this up:

Passed — connected, and every relevant capability is granted.
Warning — connected, but at least one capability is missing (see the ✗ rows for which).
Failed — couldn't connect or authenticate at all; nothing else could be checked.
Not set up — the school doesn't have credentials configured yet (no Google admin user, or no Entra tenant/client/secret saved) — configure them first in Google Workspace settings or the Entra settings before testing.

A result also shows when it ran and who requested it.

Test connection result showing a status pill above a checklist with granted, missing and not applicable permission rows

Step 4 — Test every school in the trust (MAT) {#step-4}

From MAT Overview, go to Test connection (/v2/admin/mat/connection-test) to see a grid of every authorised school against Google and Entra. Select Test all schools to queue the fuller permissions check for every enabled platform across every school you can access — useful before a rollout, or to spot which schools in the trust need attention. The grid only ever shows schools within your MAT access; it can't reach beyond it.

MAT overview test connection grid showing every school and platform combination with a Test all schools option

Why this matters

A result here reflects the real sync engine's own environment — the same service account, the same per-school Entra app registration, the same scopes — so a pass is trustworthy evidence the live sync will work, and a fail tells you exactly what's missing before the nightly sync run finds out the hard way. If the live sync is already failing, start here before digging into sync errors: a connection/permission problem usually explains a whole cluster of failures at once.

Troubleshooting

"It says 'not set up'" — the school's Google admin user/domain, or Entra tenant/client ID/secret, hasn't been entered yet. Nothing was attempted against Google or Microsoft — enter the credentials first.
"Connection passed but permissions show warnings" — authentication works, but a specific permission the sync needs hasn't been granted. For Google, re-authorise domain-wide delegation for the missing scope named in the detail line (see Google Workspace settings). For Entra, the app registration your school uses is missing a Microsoft Graph permission — the exact permissions and how to grant admin consent for them should be confirmed with your IT admin or the Realsmart provisioning team, because the Entra permission list is maintained by the provisioning service rather than in this app. Don't guess at permission names in the Azure portal.
"I ran it and nothing changed on Google/Entra's side" — correct, and expected — that's the whole point. If you need to see the effect of a real change, use the sync itself, not this check.