Entra App Registration Permissions for GALsync and contactSync

Purpose

Certificate-based authentication through an Entra ID App Registration is now the only supported way for these products to reach Exchange Online. Getting the permissions right is most of the work, and the failures are distinctive once you know them. This article covers what to grant, the two steps people miss, and how to tell which one is missing.

What the application needs

Three separate things, and all three are required. Granting API permissions alone is the most common incomplete configuration.

1. API permissions, as application permissions rather than delegated:

Mail.ReadWrite and Mail.Send — Microsoft Graph, for mailbox access where the data file travels by mail.
Exchange.ManageAsApp — Office 365 Exchange Online, for app-only Exchange Online PowerShell.

2. Admin consent granted on those permissions. Permissions that are assigned but not consented do not take effect.

3. An Exchange directory role assigned to the application — Exchange Recipient Administrator or Exchange Administrator. This is the step most often missed, and on its own it accounts for a large share of "everything looks right and nothing works" cases.

The two steps people miss

The Exchange role. API permissions govern what the application may call; the directory role governs what it may act on in Exchange. An application with correct Graph permissions and no Exchange role authenticates successfully and then fails when it tries to do anything.

The failure is specific and worth recognising verbatim:

The role assigned to application <app-id> isn't supported in this scenario.
Please check online documentation for assigning correct Directory Roles to
Azure AD Application for EXO App-Only Authentication.

If you see that, the missing piece is the role, not the permissions.

Restarting the console after consent. The product picks up newly consented permissions when it starts. After granting admin consent, close and reopen the console before testing — otherwise a correctly configured application will still appear to be failing.

Do not mix authentication methods

An environment configuration holding both App Registration details and user credentials does not work reliably. If you have migrated from user-based authentication, remove the user credentials from the environment configuration rather than leaving them in place alongside the new settings.

This is a genuine root cause, not tidiness: a configuration with both populated has been the confirmed explanation for a product that stopped synchronizing after a migration to Graph and App Registration.

Create the certificate as the service account

Generate the certificate from within the product, while logged on as the account the service runs as, then upload the public certificate to the App Registration.

The reason is the same one behind several other problems in these products: certificates land in the profile of the account that creates them, and scheduled policies run as the service account. A certificate created under your own account works when you test interactively and is absent when the service runs.

The same applies to the ExchangeOnlineManagement module — install it with -Scope AllUsers.

Tenant and endpoint settings

Set the Organization / Tenant value to the tenant's default .onmicrosoft.com domain. Not the .mail.onmicrosoft.com routing domain — that is a hybrid mail-flow domain and will cause both the PowerShell connection test and the test email to fail.

For GCC High, DoD or other national clouds, the endpoints must also be selected. See Configuring GALsync for GCC High, DoD and Other National Clouds.

Watch for identity providers in the path

Where a third-party identity provider fronts Microsoft 365 sign-in, confirm the service account and the application are handled consistently by it. An identity provider intercepting authentication for the synchronization account produces access-denied behaviour that looks like a permissions problem in Entra and is not.

If access is denied and the Entra configuration checks out, this is worth eliminating before going further.

Diagnosing in order

Does Exchange Online PowerShell connect? Test with the same App ID, thumbprint and organisation the product uses. If this fails, the problem is authentication — certificate, tenant value or endpoints.
```
Connect-ExchangeOnline -AppId <app-id> `
    -CertificateThumbprint <thumbprint> `
    -Organization <tenant>.onmicrosoft.com
```
Does a query return data? If the connection opens but queries return nothing useful, look at the Exchange role and at any application access policy scoping the app to a subset of mailboxes.
```
Get-Recipient -Identity <user> |
    Format-List Name, RecipientTypeDetails, PrimarySmtpAddress, EmailAddresses

Get-ApplicationAccessPolicy | Where-Object { $_.AppId -eq '<app-id>' }
```
Does it work manually but not on schedule? That is the service account context — certificate and module location.
Has the certificate expired? A red X on the environment configuration and its policies indicates expiry. See Renewing an Expired App Registration Certificate for GALsync and contactSync.

Service account rights on the server

The GALsync service account does not require Domain Admin. Local administrator rights on the GALsync server, plus delegated permissions on the target organizational unit where imports are written, is the appropriate level.

References

GALsync 8.7 Manual p.233 — restricting an application's access to specific mailboxes.
GALsync and contactSync 8.7 Upgrade Instructions — removal of user-based authentication as of 8.6; certificate-based authentication requirements.
Microsoft documents the directory role assignment for Exchange Online app-only authentication at App-only authentication for unattended scripts in Exchange Online PowerShell.
The current manuals are published by NETsec at netsec.de.

Articles in this section