Okta

On this page

Okta connects through an API Services app you create in your Okta org. Governax signs in to that app with a key unique to your entity, so no secret of yours is ever pasted into Governax. It then registers an Event Hook in your Okta org for you, so there is no webhook configuration to do by hand.

Before you start#

What you need
ItemDetail
Your Okta org domainFor example your-org.okta.com, or your custom domain. A pasted URL or the Admin Console address also works.
A Super Admin in your Okta orgOnly a Super Admin can grant Okta API scopes to an app.
Operator grade on the Governax entityThe connect form, and the key it shows, are visible to operators.

Creating the Okta app#

Open Integrations → Okta for the entity in Governax and keep it open: the connect page shows these same steps with this entity's key filled in, and you paste the client ID back there.

  1. Create an API Services app

    Applications → Applications → Create App Integration. Choose API Services, click Next, name it Governax, and save.

  2. Add this entity's key to the app

    Governax app → General → Client Credentials → Edit. Set Client authentication to Public key / Private key. Under Public keys choose Save keys in Okta, click Add key, paste the key from the Governax connect page, then Done and Save.

    The key is unique to this entity, so the app can only ever be connected to it. Leave "Require Demonstrating Proof of Possession (DPoP)" as it is: Governax works either way.

  3. Grant the scopes

    Governax app → Okta API Scopes. Click Grant next to okta.eventHooks.manage (create, verify, health-check and remove the one Event Hook) and okta.users.read (the snapshot of active users at connect), and nothing else. Only a Super Admin can grant scopes.

  4. Assign an admin role

    Governax app → Admin roles → Edit assignments. Assign Super Administrator, or a custom admin role that can manage Event Hooks and view users. Scopes alone are not enough: Okta also checks the app's role on every call. Custom-role Event Hook permissions are an Okta Early Access feature (2025.12), so check your org has it before relying on it.

  5. Copy the client ID

    Governax app → General → Client Credentials. Okta client IDs start with 0oa.

Connecting#

  1. Enter the domain and the client ID

    The domain is your org's domain, for example your-org.okta.com, or your custom domain. The Admin Console address (ending -admin.okta.com) also works: Governax converts it to the org domain, where OAuth lives.

  2. Governax verifies and configures

    Governax signs in to your app, creates an Event Hook in your Okta org, and Okta verifies that hook by calling it. All of this happens inside the one request, and nothing is saved until it works, so a setup mistake is reported to you, naming the step to fix. The initial user snapshot starts once the connection is saved and runs in the background.

The Event Hook Governax creates#

You will see a new Event Hook in your Okta admin console named after your entity. It points at a URL unique to this connection:

https://<governax>/api/webhooks/okta/<connection-id>

Each connection has its own URL and its own authorisation secret, sent by Okta as a header on every delivery. Because the secret is derived per connection, a value captured from one customer cannot be replayed against another. Governax verifies it on every delivery before doing anything with the payload.

Events captured#

Governax subscribes to 24 Okta System Log event types, producing these ledger events:

Okta event types by area
AreaEvent types
User lifecycleresource.user_created, access.user_activated, access.user_suspended, access.user_unsuspended, access.user_deactivated, resource.user_deleted
Groupsaccess.group_member_added, access.group_member_removed, resource.group_created, resource.group_deleted
Applicationsaccess.app_assigned, access.app_unassigned, resource.app_created, resource.app_deactivated, resource.app_deleted
Administrative privilegeaccess.admin_role_granted, access.admin_role_revoked
Multi-factorsecurity.mfa_factor_added, security.mfa_factor_removed, security.mfa_reset
Policy and tokensresource.policy_changed, access.api_token_created, access.api_token_revoked
Connect timeaccess.baseline_observed for every active user

Not captured: routine authentication and session events. Okta's System Log records every sign-in; recording those in a governance ledger would bury the access changes that matter.

Okta is the connector with the most complete attribution: its events carry login identifiers that are normally email addresses, so both actor and subject are usually populated.

Disconnecting#

Disconnecting deactivates and deletes the Event Hook in your Okta org through your app, then marks the connection dead. Nothing is left behind in Okta except the app itself, which you can deactivate or delete if you are revoking access properly.

Troubleshooting#

Governax checks each connection every six hours. A problem shows as "Needs attention" on the Integrations page, with the reason on the Okta page and a Reconnect button that fixes it in place, without stopping events.

Common Okta connection problems
SymptomCause and fix
Okta did not accept Governax's keyThe key on the app is missing or belongs to a different entity, or the client ID is wrong. Add the key shown on this entity's Okta page to the app, and check the client ID.
The Okta app is missing a scopeGrant okta.eventHooks.manage and okta.users.read on the app's Okta API Scopes tab.
The Okta app has no admin roleAssign an admin role that can manage Event Hooks on the app's Admin roles tab.
The Event Hook no longer exists, or is inactiveIt was deleted or deactivated in Okta. Reconnect: Governax registers a new hook.
Uses the retired API-token methodThe connection predates API Services apps. Create the app as above, then Reconnect.
invalid okta domainEnter only the domain, for example your-org.okta.com.
Okta could not reach Governax to verify the Event HookA temporary problem on the Governax side. Nothing was saved; try again in a minute, and contact support if it keeps failing.
Already connectedThis Okta org is bound to another entity or organisation. Disconnect it there first.
Sign-ins are not appearingThey are deliberately excluded. Only access and configuration change is recorded.

General connector behaviour is covered in Connecting a tool.