Identity Hooks (Directory & App Connections)

Identity Hooks allow Zonitix to synchronize with your existing identity providers like Microsoft Entra ID, Okta, or Google Workspace.

What A Hook Is

A “hook” is one saved connection to one outside system. You add and manage hooks under Access Governance → Identity Hooks: connect a directory to bring your people in, connect the apps they use so onboarding and offboarding can create and close accounts there, and connect Microsoft Intune or Jamf Pro to pull device evidence.

Unified User Directory

Instead of manually entering employee accounts in multiple dashboards, Identity Hooks link Zonitix directly to your corporate directory (like Microsoft Entra ID or Okta). When an employee is added or removed in your corporate system, the next scheduled sync picks up the change and updates their status and profile attributes in Zonitix.

Connecting A Hook — The Five Steps

Every provider goes through the same wizard, so once you have connected one you know them all. You need a permission to manage hooks or integrations; the two permission names are under Technical detail, in Driving Providers Over The API.

Credentials are encrypted at rest and never returned to the browser — editing a hook shows you only which credential fields are set, not their values. Saving merges your changes into the stored config, so changing the sync interval can never silently wipe a secret.

Deleting a hook does not delete the people or groups it imported. They stay in your directory and are simply no longer tied to that hook. What is removed is the hook itself and the app-usage data it supplied to SaaS Discovery. The deletion is recorded in the audit log.

Each hook has its own Sync dashboard, opened from the icon on the hook’s row or from its menu. It shows how many records the latest completed run synced, created and modified, a viewer for checking how one person’s directory data maps to Zonitix fields, and the last 10 sync runs with what each one changed.

What Sync Actually Does

A background scheduler wakes every 5 minutes and syncs any hook that is active, verified, and past its interval — so a 24-hour interval means “about once a day,” not on the hour. Manager relationships are resolved in a second pass, which is what builds your org chart. Sync never deletes a user; accounts disabled upstream are marked inactive.

Creating and disabling accounts from an onboarding or offboarding run is a separate capability with a longer list of providers; see Signed Offer To Onboarding (Zero-Touch).

Per-capability validation runs for Microsoft Entra ID, AWS and LDAP/OpenLDAP. Every other type — Okta, Google Workspace and the SaaS connectors — runs one required Authenticate check. Either way, a hook cannot sync until it has passed and is verified. The first validation a hook ever passes also switches its scheduled sync on, provided it has never synced. A later validation never switches a hook you paused back on.

How A Directory Write Is Protected

Disabling or creating an account is the one action an attacker wants most, so it does not run wherever a workflow happens to execute. Every directory write funnels through a single service that decides, while the workflow engine only asks — the engine can no longer even read the encrypted hook credentials.

• A dedicated write credential. The endpoint accepts its own directory token, not the shared internal one — a compromised report renderer or any other peer cannot reach it.
• A fixed action list, never a passthrough. Only create, disable, enable, add to group and remove from group. The two group actions need the hook’s Write Groups capability, and the group is one Zonitix already knows, never a name the caller supplies. There is deliberately no delete and no “run this LDAP command for me.”
• You pass an email, never a directory path. Zonitix resolves the account itself, inside that hook’s own configured scope, so a caller cannot point the write at Domain Admins or a service account.
• Disable, never delete. Offboarding suspends the account and releases the seat while keeping it recoverable — a mistake costs an inconvenience, not a user’s group history and mailbox linkage.
• A burst limit with two-person release. An automated caller that starts disabling accounts faster than a real process ever would — ten in an hour — is parked for a second administrator to approve, not obeyed. That is the control that stops a compromised workflow disabling everyone at 3am.

Releasing A Held Disable

The offboarding step reports “Held for a second administrator” and the account stays enabled. A notice then appears at the top of Access Governance → Identity Hooks, on every plan, saying how many offboarding account disables are held. It is shown only while something is held, and only to people who can open Identity Hooks and are also either an administrator or allowed to approve identity changes. One of them clicks Review, then Approve or Reject. It must be someone other than the person who ran the offboarding.

Re-enabling an account is only automated where it can be undone without guessing (LDAP/OpenLDAP today); for other providers Zonitix tells you to re-enable it in that provider’s own console rather than pretend it did.

If something here is not working as you expect, start with When something goes wrong.

What To Create On The Provider Side

Microsoft Entra ID / Azure AD

1. Azure Portal → Microsoft Entra ID → App registrations → New registration.
2. From Overview, copy the Application (client) ID and Directory (tenant) ID.
3. Certificates & secrets → New client secret → copy the Value immediately (it is shown once, and it is not the Secret ID).
4. API permissions → Microsoft Graph → Application permissions (not Delegated — there is no signed-in user in this flow).
5. Add Directory.Read.All. User.Read.All alone will pass the user check but fail the group check.
6. Click Grant admin consent. This is the step people miss — without it the credentials authenticate fine and then every directory call returns 403.

Okta

1. Okta Admin Console → Security → API → Tokens.
2. Create Token, name it, and copy the value immediately — it is shown only once.
3. The token inherits the permissions of the admin who created it, so create it as a Read-Only Admin (or higher) to read users and groups.

Google Workspace

1. Google Cloud Console → APIs & Services → Library → enable the Admin SDK API.
2. IAM & Admin → Service Accounts → create one, then Keys → Add key → JSON and download it.
3. Copy the service account’s numeric Client ID (not its email address).
4. admin.google.com → Security → Access and data control → API controls → Manage Domain Wide Delegation → Add new, paste the Client ID.
5. Authorize these scopes — the second only if you want group sync:
   .../auth/admin.directory.user.readonly
   .../auth/admin.directory.group.readonly

Active Directory / LDAP

1. Open outbound access from your instance to the domain controller: 389 (LDAP), 636 (LDAPS, recommended), or 3268/3269 for the Global Catalog.
2. Get the DC’s FQDN with Get-ADDomainController. Use the FQDN, not a bare IP, so LDAPS certificate validation works.
3. Get the Base DN with Get-ADDomain (the DistinguishedName field), or derive it: corp.example.com → dc=corp,dc=example,dc=com.
4. Create a dedicated read-only service account to bind with — not a person’s login.

What To Paste Into Zonitix

adminEmail on Google Workspace is the super-admin the service account impersonates through domain-wide delegation — it is not a login for Zonitix.

Held Disables: Permissions, Reply And Routes

The notice about held disables is shown to people who can open Identity Hooks (manage_hooks or manage_integrations) and are also either an administrator or hold approve_identity_changes.

Once the same actor has 10 disables in the last 60 minutes, the next disable is not performed: the endpoint answers 202 with { parked: true, requestId, message }, stores a pending change request with source WORKFLOW, and audits DIRECTORY_DISABLE_PARKED. The request is listed and decided through GET /user-management/align/change-requests, POST /user-management/align/change-requests/:id/approve and POST /user-management/align/change-requests/:id/reject, all of which need approve_identity_changes. Without the AlignSync entitlement those three routes still answer, for held disables only. An approval by the requester is refused: “You cannot approve your own change request — a different person must approve it.”

SaaS App Connectors

Beyond your directory, Zonitix connects to the SaaS apps your people actually use, so a joiner or leaver can be actioned in the same run. Every connector below calls the vendor’s real API. There is no placeholder data anywhere in this path — a connector without a working implementation fails loudly and records a failed sync rather than importing invented users into your directory.

The last column says whether an onboarding or offboarding run can create and remove the person’s account in that app through the hook. Together with the directories, that makes the full list of systems a run can drive: Microsoft Entra ID, Okta, Google Workspace, Active Directory / OpenLDAP, AWS IAM, Slack, GitHub, Zoom, Jira, Salesforce, BambooHR, 1Password, Zendesk, ServiceNow, Dropbox and Generic SCIM 2.0. Confluence, Figma and GCP hooks cannot create or remove accounts. What “remove” means differs by provider — some disable the account, some delete it — see Signed Offer To Onboarding (Zero-Touch).

Two you should know the shape of before relying on them. Confluence authenticates and confirms the token works, but the endpoint it reads returns only the token owner’s own profile — it is a credential check, not a directory import. Figma cannot list organisation members through the public REST API at all, so its sync refuses with an explicit message telling you it needs the Enterprise SCIM API rather than quietly returning nothing.

None of the SaaS connectors read groups today — they import people, not group structure. Group sync is available for Microsoft Entra ID, Okta, Google Workspace, AWS IAM and LDAP / OpenLDAP.

When It Doesn’t Connect

Client Credentials Flow

Zonitix authenticates to Microsoft Entra ID (formerly Azure AD) using the OAuth2 server-to-server client credentials flow. Other providers use their own mechanisms — Okta uses a static API token, and Google Workspace uses a signed JWT with domain-wide delegation.

Driving Providers Over The API

The wizard above is a thin front-end over one REST resource. An integrator or CI job can create, verify, sync, and pull compliance evidence from a provider entirely over HTTP, and a compliance inspector can pull per-provider evidence the same way. Everything on this resource is proxied by the API gateway to the integration service — the gateway strips the /user-management segment and forwards to /providers on the service — so every path below is rooted at:

Every call is authenticated at the gateway and then gated by RBAC in the service. There are two tiers: a write/CONNECT tier that requires manage_hooks or manage_integrations, and a read/VIEW tier satisfied by either of those or by manage_alignment_policy, execute_identity_writeback, or approve_identity_changes. manage_hooks is kept as a valid superset in every list for backward compatibility.

The Writable-Field Allowlist

Create and update both mass-assign only from a fixed allowlist. A key that is not on this list is silently dropped from the request body — it is not an error, it just does not persist. The list is exactly:

Field defaults on the model, for anything you omit at create time: isActive = true, syncInterval = 24 (hours), every canRead*/canWrite* flag = false, config = {}. The capability flags being off by default is why a freshly created hook syncs nothing until you either check the boxes in the wizard or send the flags true — and until a validation confirms them.

One exception, for older LDAP hooks. A hook also carries capabilitiesSetAt, the time its capabilities were first decided. It is set when a create request carries any capability flag, or when an update changes a flag to a different value; re-sending the values already stored does not count. An LDAP or OPENLDAP hook where it is still empty — for example one created over the API with no capability flags at all — is treated as allowed to read users and groups, so an import that was already running is not stopped. Every other type enforces the stored flags strictly. For writes: AlignSync write-back always requires canWriteUsers to be true, while account create and disable from a workflow run is allowed on a hook whose capabilities were never decided.

Per-Type config Schemas

config is a free-form JSON object; which keys are required is decided by type at test/sync time (the connection test throws a named error if one is missing). These are the types the connection test actually implements — any other type is rejected at test time with Test for {type} not fully implemented.

Device Management Hooks (Microsoft Intune And Jamf Pro)

In plain words: a Microsoft Intune or Jamf Pro hook does not bring people or groups into your directory. It reads how your managed devices are doing — whether they are compliant and whether their disks are encrypted — and feeds that to Compliance as evidence. You connect it the same way as any other hook, from the Device Management category of the hook catalogue.

Technically: POST /:id/sync on these two types runs a device-evidence refresh instead of a directory import (Intune: device-compliance; Jamf Pro: disk-encryption) and the summary reads “device evidence refreshed” with the number of devices scanned and flagged. The background scheduler runs the same refresh on the hook’s sync interval. A dry run contacts nothing and returns a preview line. The same data can be pulled on demand from GET /:id/evidence/:type.

The hook catalogue also shows tiles for a number of individual apps that are provisioned over SCIM. Each of those tiles creates an ordinary SCIM hook, so the SCIM row above applies to them.

Secrets, And Why Update Merges

Any config key whose name looks like a credential is encrypted at rest and stripped from every response. Concretely that is the seven named fields — clientSecret, apiToken, bindPassword, secretAccessKey, serviceAccountJson, accessKeyId, externalId (the AWS role External ID) — plus anything matching secret / token / password / passwd / api_key / credential / private_key / access_key / service_account. A response never returns the value, its length, or a prefix; it returns configuredCredentials, an array of the key names that are set. An inspector reads that array to confirm which secrets exist without ever seeing one.

Worked Example — Create, Test, Then Rotate

Test vs. Validate — Two Different Verifications

Bespoke capability suites exist only for AZURE_AD, AWS, and LDAP/OPENLDAP. For every other type — Okta, Google Workspace, and all the SaaS connectors — /validate falls back to a single required Authenticate check that just runs the connection test, so it still flows through the same verify-then-sync path. If a type has no connection test at all, /validate returns supported: false and persists nothing.

POST /:id/sync — Importing Users And Groups

Body fields, all optional: syncType ("delta" default over the API, or "full"), isManual (defaults to true when called via the API), and dryRun (defaults to false). The guard an inspector checks: sync throws 400 Provider must be verified before syncing when isVerified is false — there is no path to import directory data on an unverified hook. A scheduled (non-manual) run on an inactive hook is skipped rather than erroring.

Sync is really implemented for AZURE_AD, GOOGLE_WORKSPACE, AWS, OKTA, LDAP/OPENLDAP, ZOOM, CONFLUENCE, the extended SaaS set (Slack, Jira, GitHub, Salesforce, Zendesk, ServiceNow, Notion, Dropbox, BambooHR, 1Password) and SCIM. GCP and FIGMA have no directory sync: a manual sync answers 200 with a message that starts “Sync not available:” and unsupported: true, writes a SYNC_<TYPE>_UNSUPPORTED audit row, and does not move lastSync; the scheduler never dispatches them. INTUNE and JAMF refresh device evidence instead of importing people (see Device management hooks). Check the returned message, and GET /:id/logs, to confirm a run did real work.

The response is always { message }, with up to four extra flags that are present only when true: skipped (nothing ran), unsupported (the type has no directory sync), inFlight (a sync of this hook is already running) and partial (the connector stopped before it had read the whole directory, so only part was imported). A client that reads only message will mistake these for a normal run.

GET /:id/evidence/:type — Compliance Evidence

An inspector can pull point-in-time evidence straight from the provider. Each call makes a live API request and returns a JSON envelope: { title, timestamp, count, data } (the MFA scans also carry scanned). Evidence is implemented for five provider types — OKTA, AZURE_AD, AWS, INTUNE and JAMF; any other type returns 400 Evidence fetching not supported for provider type.