6. Microsoft connection (Graph + Exchange Online)

Microsoft Graph

Microsoft Graph provides the directory reads and writes that power onboarding, offboarding and day‑to‑day changes.

• Self‑Hosted — authenticates with your own app (client ID) + certificate.
• SaaS — authenticates with the central vendor certificate against your tenant.

When does it go live? Directory sync stays paused until Microsoft is actually connected:

• Self‑Hosted: your tenant ID, client ID and certificate (or secret) are configured and a Test connection succeeds.
• SaaS: admin consent has been granted for the managed application.

Granting admin consent (both modes) and a successful Test connection (Self‑Hosted) switch the console to live automatically. See Troubleshooting → “green but nothing syncs”.

Permission check. The Setup Wizard and the Connection screen verify that the required Microsoft permissions are present. Any missing permission is shown as a warning but does not hard‑block an otherwise working connection.

Graph application permissions

The app requests the following Microsoft Graph application permissions (admin consent):

Required (core lifecycle):

Permission	Used for
User.Read.All / User.ReadWrite.All	Read/create/update user accounts
Group.Read.All / Group.ReadWrite.All	Read/manage groups and memberships
Directory.Read.All	Directory reads (users, groups, org)
Organization.Read.All	Tenant / SKU / org details

Optional (feature‑gated — only needed when that feature is used):

Permission	Feature	Notes
MailboxSettings.Read, Mail.Send	Notifications / mailbox	Scoped sending
User-PasswordProfile.ReadWrite.All	Password resets
UserAuthenticationMethod.ReadWrite.All	Auth‑method management
User.Invite.All	Guest invitations
Synchronization.ReadWrite.All	Hybrid Entra Cloud Sync	On‑demand provisioning
AuditLog.Read.All	Stale‑License report & sign‑in activity	Requires an Entra ID P1 plan on the tenant. Without it the console degrades gracefully — the Stale‑License report shows a helpful notice instead of last‑sign‑in data.

Adding new permissions → re‑consent

When a new Graph permission is added to the app (for example AuditLog.Read.All), tenants that consented earlier will not have granted it yet. The console detects this automatically (declared‑vs‑granted, self‑healing) and shows a “New Microsoft permissions available” banner plus a card on the Connection screen with a one‑click Grant admin consent action. The prompt clears on its own once consent is re‑granted — no version bump or manual reset needed.

Exchange Online

Exchange Online handles mailbox operations that Microsoft Graph can't (shared mailboxes, distribution lists) and scoped email sending for notifications.

• Connect — the app detects your tenant’s Exchange organization and connects.
• Scoped send policy — instead of granting tenant‑wide send, the app creates a policy that limits sending to a single mail‑enabled security group containing your sender mailbox. This is created via the guided Exchange step in the wizard, and the chosen group is reused in Notifications.
• Least privilege — setup escalates to Exchange Administrator only long enough to create the policy, then downgrades to Exchange Recipient Administrator.

Address‑book (GAL) visibility

The Hide from Global Address Book switches on Microsoft 365 groups, mail‑enabled security groups, distribution lists, shared mailboxes and employees are applied through Exchange Online (Set-UnifiedGroup / Set-DistributionGroup / Set-DynamicDistributionGroup / Set-Mailbox with -HiddenFromAddressListsEnabled). The console always persists the chosen flag; the Exchange change is applied best‑effort and degrades gracefully if a recipient's mailbox or the required cmdlet isn't available. Verify GAL visibility against your live tenant if you rely on it.

See Notifications for using the scoped policy to send alert emails.