Directory sync (Azure Entra ID)

Directory sync imports and reconciles your organization's users from Azure Entra ID (formerly Azure AD) using app-only Microsoft Graph access. Where SSO authenticates a user at sign-in, directory sync proactively creates, updates, and deactivates ActionConnect users to match your directory.

What sync does

On each run, ActionConnect:

• Creates users that exist in Entra but not yet in ActionConnect (JIT, with a default role).
• Updates changed names and account status.
• Deactivates users that have disappeared from the directory (optional), and maps disabled Entra accounts to disabled ActionConnect users.

Matching is by the stable Entra object id first, then email, so renames and email changes don't create duplicates. Sync is idempotent — running it again is safe and converges to the same result.

Connecting Entra

A tenant admin registers a connection with these values from an Entra app registration:

Field	What it is
Display name	A label for the connection.
Directory (tenant) id	Your Azure directory GUID.
Application (client) id	The app registration's client id.
Client secret	A secret on that app registration.
Group (optional)	Scope sync to members of a single Entra group.
Default role	Role assigned to users created by sync.

Example request on the tenant surface:

curl -X POST https://<your-org>.actionconnect.com/api/directory/entra \
  -H 'content-type: application/json' \
  -d '{"displayName":"Acme Entra","directoryId":"<azure-dir-guid>",
       "clientId":"<app-client-id>","clientSecret":"<secret>","groupId":"<optional-group>"}'

IMPORTANT

The client secret is encrypted at rest (AES-256-GCM with a server-held key) before it is stored. Plaintext credentials never touch the database, and the secret is never returned by any read endpoint.

Required Entra permissions

The app registration needs application (app-only) permissions, admin-consented:

• User.Read.All
• GroupMember.Read.All — only if you scope sync to a group.

Running a sync

Trigger a sync run for a connection:

curl -X POST https://<your-org>.actionconnect.com/api/directory/connections/<id>/sync

ActionConnect acquires an app-only token (client-credentials), pages through /users (or the chosen group's members) from Microsoft Graph, and reconciles them into your users table.

Group scope

If you set a group, only that group's members are imported and reconciled — ideal for onboarding just the team that uses ActionConnect rather than your entire directory.

Sync history

Every run is recorded with counts (seen / created / updated / deactivated) and a status. Review past runs to confirm a sync behaved as expected:

curl https://<your-org>.actionconnect.com/api/directory/connections/<id>/runs

Sync is manually triggered today; scheduled runs are supported by the design and can be enabled later.

Extensibility

The provider is abstracted, so other directories (Okta, Google Workspace) can be added without changing how reconciliation works. Entra is the first supported provider.

Directory sync vs. SSO

	Directory sync	SSO
When it runs	In the background, on each sync	At each sign-in
Creates users	Yes (proactively, from the directory)	Yes (JIT, on first login)
Deactivates users	Yes (when removed from directory)	No
Needs Graph permissions	Yes (User.Read.All)	No

Many organizations use both: SSO for sign-in and directory sync to keep the roster current.