Directory sync: keep your team and their roles in step with Microsoft Entra

Connect your Microsoft Entra directory once, and StackJack keeps your StackJack team list and each person's custom roles in step with the groups you already manage. Put someone in your "Service Desk" group in Entra and they get the Service Desk role here; take them out and the role comes off.

Directory sync is on the Directory Sync page (/directory-sync), under Access & Team in the sidebar. Only owners, co-owners, and administrators can open the page at all — other members see an access notice instead of the tabs, because the Review tab lists directory users' names and email addresses.

StackJack only ever reads your directory. Nothing StackJack does writes back to Entra: it does not create, disable, or edit users, groups, or memberships on the Microsoft side.

What it can do for you

• Provision teammates automatically. A person in a mapped group can be given a StackJack membership without an invitation email — they sign in with Microsoft on day one, no invite link and no separate password.
• Grant and remove roles from group membership. Roles follow the group. Nobody has to remember to update StackJack when someone changes team.
• Offboard. When someone is disabled in your directory but still in a mapped group, StackJack deactivates their membership on the next sync. Someone removed from your mapped groups or deleted from the directory is confirmed by a background check that examines a bounded batch each run (500 per run, rotating), so their deactivation can take several sync runs on a large directory — the Runs tab shows how many were checked and how many are still waiting. Deactivation revokes what it always revokes: their AI assistant endpoints and connected apps included.

Step 1: connect your directory

On the Directory Sync page, press Connect Microsoft Entra. Connecting is two Microsoft steps through one flow: first your organization grants consent, then you sign in so Microsoft can confirm who approved it. Both steps must use the same Microsoft organization, and the sign-in account must hold Global Administrator (or Privileged Role Administrator) at that moment.

If your organization uses PIM, activate the admin role first, then connect — an eligible but inactive role is refused.

StackJack asks for read-only access: users, groups and their memberships, and basic details about the directory itself (User.Read.All, Group.Read.All, Organization.Read.All, all application-level reads). The consent screen is Microsoft's own and lists the exact permissions. StackJack never sees the administrator's password.

When you come back, StackJack checks the connection with real reads — the directory's details, one user, one group — and marks it Connected only after they work. A freshly granted consent can take Microsoft a few minutes to propagate; if the check fails right after consent, wait a moment and try again.

Two rules to know before you bind:

• Sign in with an account in the directory you mean to sync. Before anything has synced you can simply connect again with the right account. Once people or mappings exist, the directory cannot be changed from this page — changing directories requires disconnecting through support.
• One directory connects to one StackJack organization. If your directory is already connected to another StackJack organization, the connection is refused and the message says to contact support.

Step 2: add a mapping

Nothing syncs until at least one mapping is active. A connected directory with no mapping reads nothing and changes nobody. Expect the status card to show an amber "Partly synced" with the reason "no active mappings are configured" until your first mapping exists — that is the page telling you it is idle, not broken.

A mapping ties one thing in your directory to one or more roles. Add mapping offers two ways to match people:

Then pick the roles that mapping grants — at least one — and decide two switches:

• Auto-provision on means a person who matches this mapping and is not yet on your team gets a StackJack membership created automatically. Off means they are listed on the Review tab instead, and nobody is added until you say so.
• Include guest users (off by default) controls whether B2B guest accounts in the group match at all. When it is off, the Runs tab reports how many guests were skipped — that count is why a matched number can be smaller than the group you see in Entra. Turning it off later removes that mapping's roles from guests on the next sync.

Each mapping also has an Active switch; switching off the last active mapping stops the connection reading the directory. A connection holds at most 50 mappings, inactive ones included. Somebody who matches several mappings gets all of their roles added together. If two managers edit the same mapping at once, the second save is refused with a message rather than overwriting — reopen the dialog and apply your change again.

People already on your team pick up their roles on the next sync. The first sync links an existing teammate's StackJack account to their Entra identity; the sync after that grants the roles. Press Sync now if you do not want to wait for the interval.

Step 3: watch the Review tab

The Review tab is everything the sync wants a human to look at. Rows carry the reason directly on them — read the reason, not just the filter pill, because related rows can appear under different pills:

• Discovered — people who match a mapping but have no StackJack membership. Tick the ones you want and press Provision selected. People whose directory account is disabled are badged and cannot be selected; StackJack picks them up by itself if the account is re-enabled. Rows the sync could not provision (for example, an Entra identity already linked to a different StackJack user) also appear here, with the reason.
• Lapsed — people who no longer match any mapping. Their synced roles have been removed; a membership the sync created is deactivated, and a person you invited by hand is left alone and flagged. Ambiguous cases land here too — two directory users resolving to the same StackJack person, an email matching more than one member, or a manually-deactivated member who matches a mapping again. StackJack never guesses on these: it flags and waits for you.
• Conflicts — identity links that need a decision, such as an Entra identity already linked to a different account.

Ignore, and what it does not do

Ignore dismisses a review row. It is not an exemption from offboarding, and it is not permanent. That distinction matters, so read all three points before you use it:

• It hides the reason you dismissed, and it sticks across syncs. StackJack records which reason you dismissed. As long as that reason stays true, later syncs leave the row dismissed rather than putting it back on the list. It works this way for a Discovered row and for a Lapsed one alike.
• A new or changed reason brings the row back. The dismissal is tied to the reason you saw. If something else becomes true of that person — their account is disabled, they lapse from every mapping, a link conflicts — the row returns to Review with the new reason, and you decide again.
• It never withholds a deactivation. Ignoring a person does not stop the sync from deactivating them later. If they are disabled in the directory, or their membership was created by the sync and they leave every mapped group, the sync acts exactly as it would have without the dismissal.

To undo a dismissal. On the Review tab, switch the filter to the Ignored pill, find the row, and select Un-ignore. StackJack puts back the state and reason the row had when you dismissed it, and the row shows when it was dismissed. A row dismissed before StackJack began recording that reason comes back with a note saying so, and the next sync restates what is actually true of that person.

To stop the sync from managing somebody at all, take them out of the mapped group, or remove the mapping. That is the control that changes what the sync does. Ignore only changes what you are shown.

Sync now and Provision selected can refuse before doing anything — the message says why. The usual causes: a previous run has not recorded its outcome yet (see the Runs tab below), another operation on this organization is in progress, or your own access changed. The refusal is a wait or a one-click repair, not a fault.

The Runs tab, and repairing a stuck run

The Runs tab lists each sync with its counts (matched, provisioned, roles added and removed, deactivated, flagged), its duration, whether it was manual or scheduled, guests skipped, and the offboarding-check progress ("N checked · M not examined this run"). A green run can still carry a note — for example, a bulk provision that was partly refused — so read the row, not just the color.

If a run never records an outcome (a rare interruption at exactly the wrong moment), it blocks new syncs on this directory until it ages out — about 50 minutes at the default settings. You do not have to wait: the run's row shows Mark abandoned to managers. It asks for confirmation, and it refuses while the run is still reporting progress (a heartbeat within the last 15 minutes means the run is alive — let it finish). Marking a run abandoned records it as failed and reopens syncing immediately; nothing the run already did is undone.

Status labels worth recognising

• "Partly synced" in amber means the run did not do everything a full sync does, and the reason is spelled out beside the label. Common causes: no active mappings yet (expected on a fresh setup), a group that could not be read (StackJack never removes people on the strength of a failed read — it waits for a clean run), or a run that was interrupted part-way (what it finished before the interruption did apply; the rest happens next run).
• "Blocked", also amber, means the run applied nothing because it would have gone over the member cap. The status card shows a live "N of 500 members" counter. Fix the mapping and sync again; raising the cap is a support request.
• "Last sync failed" in red means that run failed; the scheduled sync keeps trying on its normal interval. "Error" in red means the connection is parked and automatic sync has stopped — fix the cause and press Sync now; a successful run un-parks it.

Sync every sets how often StackJack re-reads the directory: 15 or 30 minutes, an hour, or four hours. Disable stops the automatic sync entirely without disconnecting or changing anybody, and Enable turns it back on.

Limits and safeguards

• A cap of 500 members may be created by the sync for one organization. A sync that would go over it stops whole and applies nothing — a mapping pointed at a group far larger than you meant refuses loudly instead of provisioning hundreds of people.
• At most 50 mappings per connection, inactive ones included.
• Manual role assignments are never touched. The sync only removes roles it granted itself. In the Edit Roles dialog, a role the sync granted is badged "via directory sync" and cannot be unticked there — change the mapping instead.
• If the sync removes someone's last role and their own tool setting was "every tool", their tool access is locked to none rather than silently becoming everything, and the row says so — restore access from the Team page. See custom tool roles for why.
• A role that a mapping uses cannot be deleted until you remove it from the mapping first.
• Roles survive a disconnect. If support disconnects the directory, or you delete a mapping, every role the sync granted is kept and simply becomes a manual assignment you manage on the Team page — nobody loses access because the wiring was removed.
• A member you deactivated by hand stays deactivated. Re-adding them to a mapped group flags them for review; the sync never reactivates someone a person switched off.

Troubleshooting

The connect button says directory sync is not available. The feature is off or not configured on this StackJack deployment — contact support.

Consent came back with an error. The message names the cause: sign-in without an active admin role (activate PIM first, then retry), the two Microsoft steps answered by different organizations (restart the flow and use one account throughout), or a directory already connected to another StackJack organization (contact support). A consent that has not propagated yet just needs a minute and another try.

It connected the wrong directory. If nothing has synced yet, connect again with an account in the right directory. Once people or mappings exist, changing directories requires support.

Someone matched but did not get their roles. Two normal causes, in order: they are an existing teammate matched by email and the roles arrive on the next sync (above), or their row is on the Review tab with the reason on it. Check Review first.

A member was deactivated and I did not expect it. Check the Runs tab for the reason. The three the sync uses are: disabled in the directory, deleted from the directory, and left every mapped group. The last one only deactivates memberships that the sync itself created.

Someone returned to the group but was not reactivated. If a person deactivated them by hand, that is deliberate — the row is flagged for review instead. Reactivate them from the Team page.

Nothing has synced at all. Check that at least one mapping is active — the page says so explicitly when there are none — that the connection is not Disabled, and that no unfinished run is blocking (the Runs tab shows it, with Mark abandoned as the repair).

The page stopped loading and says my access changed. Your role changed, or the organization was deactivated, while the page was open. Directory sync needs an owner, co-owner, or administrator with an active organization — ask one of them, or contact support if that is wrong.