Manage your directory connection

After connecting Microsoft Entra, run manual syncs, change which groups you sync, inspect the connection workspace, and reconnect or disconnect a directory.

Once Microsoft Entra is connected, the Synced directories table on the Integrations page becomes your control center for the connection. Expand a row to inspect what's synced, kick off a manual sync, change which groups are in scope, and authorize recipient domains — and use the per-row buttons to disconnect, retry, or reconnect when something needs attention. You'll come back here whenever your org structure changes or a sync needs a nudge.

Before you start

Prerequisites

You're signed in to Hook as an org admin, with the right organization selected in the sidebar org switcher if you manage more than one.
You've already connected Microsoft Entra at least once. If you haven't, start with Sync users from Microsoft Entra.
For reconnecting after an error, have an identity admin who can grant Microsoft consent on standby — some reconnect paths route back through the consent screen.

Open the connection workspace

From the org portal, go to Settings → Integrations (/org/settings/integrations). The Synced directories table lists your connected directories with a status badge on each. Click an ACTIVE Entra row to expand its inline workspace.

The workspace opens with a header of summary metrics:

Connected — the date and time the connection was established.
Synced groups — how many groups are currently in scope.
Unique users — the deduplicated count of users across those groups.
Authorized domains — how many recipient domains are authorized.

Below the metrics sits the sync block, then a Groups / All users tab pair, and an Authorized domains pane on the right.

Expanded Microsoft Entra directory workspace showing summary metrics, sync status, groups, and authorized domains

Inspect what's synced

The Groups tab lists every synced group with its type and user count. Click a group to inspect its members in the adjacent pane; use the search box to filter within a group. Switch to the All users tab for a deduplicated roster across every synced group, with each user's email and the groups they belong to.

The Authorized domains pane on the right lists the email domains detected from your synced users, each tagged Authorized, Pending review, Unauthorized, or Blocked. Rows that need action expose an Authorize domain button inline. For the full domain workflow, see Authorize recipient domains.

Live member data can be partial

If Hook can't load live members within its time budget, the workspace shows an amber banner — either "Live directory members could not be loaded for this view" or "Live member data is partial because the directory preview hit its time budget." Group metadata and counts are still accurate; the live member list just fills in on the next sync.

Run a manual sync

Hook refreshes membership from Entra on a recurring basis, but you can force a refresh from the sync block whenever you want the latest immediately.

Click Sync now

In the sync block, click Sync now. The button is disabled when zero groups are selected — you have to have at least one group in scope before a sync can run. While a sync is active, the button reads Syncing… and the status badge shows Syncing.

Directory sync block showing the last synced state and Sync now action

Watch the live counters

The sync block polls the run and shows a live counter strip: Created, Updated, and Deactivated. Created folds new groups and users; Updated folds renames, profile changes, and membership add/remove movement; Deactivated folds soft-deletes and user deactivations.

A short label under the badge names the kind of sync — Delta sync, or Delta sync · full re-enumeration when Hook's change tokens were stale and it falls back to a full re-walk. The first sync after connecting runs as an initial sync and shows no kind label.

Confirm it finished

When the run reaches a terminal state, the badge flips to Synced with a "Last synced" timestamp, or Sync failed if something went wrong. The workspace metrics and domain pane refresh automatically once the run completes.

One sync at a time

Each directory allows only one active sync. If a sync is already running, Sync now is disabled and a second trigger returns "A sync is already in progress for this directory." Wait for the current run to finish.

Change which groups you sync

To add or remove groups from the sync scope, click Manage groups in the Synced groups footer. This reopens the picker with your current selections pre-checked. Adjust the selection and continue to the preview — but this time Hook shows a Confirm scope change screen instead of a first-run preview.

Review the diff

The scope-change screen splits your edit into Adding and Removing sections. Each group is an expandable row: added groups list their incoming members; removed groups show how many users are currently synced through them, and which of those members will be deactivated.

The intro text restates the effect: "The sync engine will pull membership for added groups and detach users from removed groups. Reactivated users are auto-restored."

Confirm scope changes screen with Adding and Removing sections and a removed user tagged Will be deactivated

Heed the orphan warning

When removing groups would leave users with no remaining directory-group memberships, Hook shows an amber callout: "N users will be deactivated because they have no remaining directory-group memberships after this change." These are users who were only reachable through the groups you're removing.

A user who would be detached from a removed group but is also a member of a group you're adding is not counted as an orphan — the sync engine re-attaches them.

Acknowledge an empty scope

If your edit removes every group, Hook shows a red alert: "This will deactivate every user from this directory connection." You must tick the I understand this will deactivate N users checkbox before Save scope change un-disables. Affected users can be restored later by re-selecting their groups.

Removing all groups deactivates everyone

An empty scope leaves no directory-sourced memberships, so every user synced from this directory is deactivated. The acknowledgement checkbox is required precisely because this is destructive — only proceed if you mean it.

Save the change

Click Save scope change. Hook queues a scope-resync and shows a toast like "Scope change queued: 2 added, 1 removed," then returns you to Integrations. If your selection matches the current scope exactly, Hook tells you there are no changes to apply and offers Done instead.

Group size cap

A single added group can't exceed 50,000 members. If one does, Hook blocks the save and names the offending group — remove it from the selection to proceed.

Retry a failed scope sync

A scope-resync runs in the background after you save. Sync now only triggers a regular delta or initial sync, so it can't recover a failed scope change on its own. When the most recent run is a failed scope-resync, the sync block exposes a dedicated Retry scope sync button that re-enqueues the same change verbatim — no need to redo the picker.

Directory sync block in the failed scope resync state with Sync now and Retry scope sync buttons

Lifecycle actions per row

The buttons on the right of each Synced directories row depend on the connection's status:

ACTIVE — a Disconnect button. Clicking it opens a confirmation dialog before anything happens.
PENDING — a Cancel connection button, for when a consent handshake is in flight and you want to abandon it.
ERROR — both Retry and Disconnect. Retry sends you back through Microsoft's admin-consent screen to repair the connection.
DISCONNECTED — a Reconnect button.

Synced directories table with Connected, Pending, Failed scope sync, and Disconnected rows and their action buttons

Disconnect

On an ACTIVE row, click Disconnect, then confirm in the dialog. The dialog spells it out: "Disconnecting will stop syncing this directory. You can reconnect later; previously synced groups are preserved." After confirming, a toast reads "Microsoft Entra disconnected" and the row flips to DISCONNECTED.

Because previously synced groups are preserved, you don't lose your selection — reconnecting can resume without re-picking groups.

Reconnect

On a DISCONNECTED row, click Reconnect. Hook chooses one of two paths automatically:

Soft-resume — if the connection was healthy when you disconnected (the consent handshake had completed and there was no outstanding error), Hook flips it back to ACTIVE and immediately starts a sync. A toast reads "Microsoft Entra reconnected — syncing now," and you stay on the page.
Re-consent — if the handshake never finished or the disconnect followed an error, Hook sends you back to Microsoft's admin-consent screen to re-authorize before resuming.

Reconnecting reuses the same connection row, so your preserved group selection comes back without re-selecting.

Cancel a pending connection

If a connection is stuck in PENDING — for example, you started a connect but never finished the Microsoft consent step — click Cancel connection to abort the in-flight handshake. A toast confirms "Microsoft Entra connection cancelled."

Common pitfalls

Sync now is disabled with zero groups. A directory with no groups in scope has nothing to sync. Pick at least one group via Manage groups first.
A failed scope change won't fix itself from Sync now. Use the dedicated Retry scope sync button in the sync block — a regular sync can't replay a scope change.
Removing all groups is destructive. It deactivates every user from the directory and forces an explicit acknowledgement. Re-select the groups later to restore those users.
One active directory provider per org. Hook supports a single ACTIVE directory connection per organization today, so you can't run two providers side by side.
Nested groups aren't expanded automatically. The sync engine enumerates direct members only. If a group contains other groups, select those nested groups separately to bring their members into Hook.