Connect Okta, Entra or Google

Before you start

• This is an IT task. It assumes you know your way around the admin console of Okta, Microsoft Entra or Google Workspace: creating an API token, registering an app or creating a service account. If you do not look after your company’s identity provider yourself, do this together with the person who does.
• A Zonitix admin account that shows Access GovernanceIdentity Hooks in the menu.
• Admin access to your provider: an Okta administrator, a Microsoft Entra admin who can grant admin consent, or a Google Workspace super admin with access to Google Cloud.
• A decision: read-only (people and groups sync in, Zonitix never changes your directory) or read and write (Zonitix can also create, disable and regroup accounts during onboarding and offboarding). You can start read-only and add write access later.

1. Prepare your provider

1. 1

   Step 1: Okta: create an API token

   In the Okta Admin Console, go to SecurityAPITokens and create a token. Copy it straight away; Okta shows it only once.

   The token can do what the Okta admin who created it can do. For read-only, a Read-Only Administrator is enough. For write access, create it as an admin who can manage users and groups, such as a Super Administrator. A read-only token is refused when Zonitix tries to change an account.

   Also note your Okta domain, for example https://acme.okta.com, without /admin on the end.

2. 2

   Step 2: Microsoft Entra ID: register an app

   In the Entra admin center, open App registrationsNew registration. Once it is created, copy the Application (client) ID and Directory (tenant) ID from its Overview page.

   Under Certificates & secretsNew client secret, create a secret and copy its Value (not its ID).

   Under API permissionsAdd a permissionMicrosoft GraphApplication permissions, add Directory.Read.All. It covers both users and groups. For write access, also add User.ReadWrite.All and GroupMember.ReadWrite.All. Then click Grant admin consent.

3. 3

   Step 3: Google Workspace: create a service account

   In Google Cloud, enable the Admin SDK API. Create a service account, but do not give it a project role. On its Keys tab, add a JSON key and download it. Copy the service account’s Client ID.

   In the Google Admin console, go to SecurityAccess and data controlAPI controlsManage Domain Wide Delegation. Add the Client ID with these two read scopes:

   https://www.googleapis.com/auth/admin.directory.user.readonly
   https://www.googleapis.com/auth/admin.directory.group.readonly

   For write access, add these as well: https://www.googleapis.com/auth/admin.directory.user and https://www.googleapis.com/auth/admin.directory.group. You also need the email address of a super admin. Zonitix acts on that admin’s behalf.

2. Connect it in Zonitix

1. 4

   Step 4: Add the integration

   Go to Access GovernanceIdentity Hooks and click “NEW INTEGRATION”. Under Directory, pick “Okta”, “Azure AD” (this is Microsoft Entra ID) or “Google Workspace”.

   A new card appears in the list as a Draft, named for example “Okta Hook 1”. Click “Configure” on it.

   The card’s more-actions menu (the three dots) has a “Setup guide” with the provider steps.

   The Directory list also offers “Active Directory” (an on-premise domain over LDAP) and “OpenLDAP (Linux)”. This guide does not walk through them. They need a network route from your instance to your domain controller or LDAP server (port 636 for LDAPS, or 389) and a bind account. The fields and setup steps are in the Identity Hooks reference.
2. 5

   Step 5: Connect: paste the details

   Give the hook a “Hook Identity Name”. Then fill in the connection fields:

   Okta: “Okta domain” and “API token”. Entra: “Directory (tenant) ID”, “Application (client) ID” and “Client secret”. You can leave the Azure subscription field blank for directory sync. Google: “Primary domain”, “Admin email (impersonated)” and “Service account JSON” (paste the whole downloaded file).

   Secrets are stored encrypted. When you edit the hook later, a saved secret shows as STORED. Leave it blank to keep it. Click “Next”.

3. 6

   Step 6: Capabilities: choose read-only or write

   Under Permissions & Policies, keep “Read Users” and “Read Groups” on. For write access, also turn on “Write Users” and, if you want onboarding to add people to directory groups, “Write Groups”. Leave both off for read-only.

   Pick a “Synchronization Interval” (every 1 to 24 hours; 24 is the default). Click “Next”.

4. 7

   Step 7: Mapping: keep the defaults

   The Attribute Mapping step works with the provider’s defaults. Change it only if your directory stores something like department in an unusual field. Click “Save & validate”.

5. 8

   Step 8: Validate: test the connection

   Zonitix saves the hook and runs its checks against your live provider. Click “Re-run checks” after fixing anything. For Okta and Google this is one Authenticate check. For Entra, the connection, reading users and reading groups are checked separately.

   When the required checks pass, click “Finish”. If an optional check failed, the button reads “Finish anyway” and that capability is switched off until you fix it and re-run.

   The checks prove Zonitix can read. Write access is not tested here. You find out it is missing the first time onboarding or offboarding tries to change an account.
6. 9

   Step 9: Done: run the first sync

   Click “DRY RUN” first to see what a sync would do without changing anything. Then click “MANUAL SYNC” and choose “Full Sync” (all records) for this first run. Later, “Delta Sync” brings in only changes.

   To keep it syncing on its own, turn on the “AUTOMATED BACKGROUND SYNC” switch, then click “Done”. The switch only unlocks after validation passes.

What you should see

If something goes wrong

Okta or Google: the Authenticate check fails

Check that the Okta domain is only the address you sign in at, with no /admin or anything after it, and that the token has not been revoked. For Google, check that the service account’s Client ID is authorised for the read scopes above, and that the admin email belongs to a super admin.

Entra: “Read users” fails even though authentication passed

The app registration has not been granted the permission. Add Directory.Read.All under Application permissions (not Delegated), then click Grant admin consent in Entra. Re-run the checks.

Google: “Service account key creation is disabled”

A Google Cloud organisation policy blocks key downloads. Ask your Google Cloud org policy administrator to lift it for this one project, then create the JSON key again.

Onboarding or offboarding steps land as IT tasks instead of happening automatically

The provider refused the change, usually because the hook is read-only. Turn on Write Users (and Write Groups if needed) on the hook, and give the token or app the write permissions from steps 1 to 3. Until then, Zonitix turns each refused change into a task for IT rather than failing silently.

The background sync switch is greyed out

It stays locked until validation passes. Open the hook, go back to the Validate step and click Run checks.

Still stuck? See When something goes wrong, or Contact Zonitix support.

Where next

• Create a persona
• Onboard your first hire
• Offboard someone
• Fix directory drift with AlignSync