Skip to content

Connect Okta

Okta sends events to Identiguard through an event hook. Identiguard creates the hook for you once you give it the details of the Identiguard integration in your Okta org.

You need:

  • Administrator access to the Okta org, with permission to manage API service integrations.
  • API Access Management enabled under Security → API.
  • The admin role in the Identiguard workspace. Members and viewers see Only workspace admins can create tenants. and a disabled Admin Access Required button.
  • A free tenant slot on the plan. See the plan tenant limit.

1. Add the Identiguard integration in Okta

Section titled “1. Add the Identiguard integration in Okta”
  1. Sign in to the Okta Admin Console.
  2. Go to Applications → Applications and choose Browse App Catalog.
  3. Search for Identiguard and choose Add Integration.
  4. Review the access it asks for and choose Install & Authorize.
  5. Copy the client secret. Okta shows it once.
  6. Leave the page open. You need the Okta domain and client ID from it in the next step.
  1. Open the workspace and go to Tenants.
  2. Under Create a tenant, find the Okta card (caption Workforce identity) and choose Connect. The page Add New Okta Tenant opens.
  3. Fill in the form. Every field is described in the table below.
  4. Under Event Subscriptions, tick the event types to collect. Nothing is ticked when the page opens, and you must tick at least one. Select All ticks every type.
  5. Optionally, under Agent Monitoring, tick Monitor AD Agents or Monitor LDAP Agents and choose a Check Interval (minutes).
  6. Choose Create Okta Tenant. The button reads Creating… while Identiguard works.
Section Field Rules
Basic Details Tenant Name Required. 100 characters or fewer. No line breaks or control characters.
Basic Details Customer Name Required. The field suggests customer names already used in the workspace.
Basic Details Okta Domain Required. The base URL of the org, such as https://login.example.com.
Basic Details Environment Required. Production or Development.
Basic Details Client ID Required. From the Identiguard integration in Okta.
Credentials Client Secret Required. The secret Okta showed once.
Event Subscriptions Subscribed Event Types At least one. The counter shows N of M selected.
Agent Monitoring Monitor AD Agents, Monitor LDAP Agents Optional. Both are off by default.
Agent Monitoring Check Interval (minutes) Appears when the monitor is ticked. A fixed list: 5, 10, 15, 30, 60 or 120 minutes. The default is 15.

The badges at the top of the page show the workspace, Okta tenant and N event types selected. Back to Tenants and Cancel leave without saving.

  • Search event types… filters the list.
  • Select All ticks every type. While you search, it becomes Select All Visible and ticks only the types on screen.
  • Clear All unticks everything.
  • The footer shows Showing N event types.

Identiguard only offers event types that Okta accepts on an event hook. If you are not sure what to collect, Select All is a reasonable start, and you can remove noisy types later. See Change which events a tenant sends.

  1. On a trial workspace, Identiguard first signs in to the Okta org with the client ID and secret to prove you control it. One Okta org can be used in one trial only.
  2. Identiguard creates an event hook in the Okta org, verifies it and activates it. The hook’s name is IG_Tenant_<tenant name>_<environment>_WS_<first 8 characters of the workspace ID>.
  3. You return to the Tenants page.
  1. In Okta, go to Workflows → Event Hooks.
  2. Open the hook Identiguard created and go to Preview.
  3. Choose any event type and choose Deliver Request.
  4. In Identiguard, open Dashboard. The event appears under Real-time events.
Okta scope Used for
okta.eventHooks.manage, okta.eventHooks.read Creating and checking the event hook
okta.logs.read Reading the system log for reports
okta.users.read, okta.factors.read The user and MFA sections of reports
okta.features.read The enabled features list in tenant details
okta.agentPools.read AD and LDAP agent monitoring

Identiguard changes nothing in Okta apart from its own event hook.

  • Okta rejects a whole hook if it includes one event type that hooks do not support. Identiguard only offers the types Okta accepts.
  • You cannot change the Okta domain later. To move to another org, delete the tenant and create it again.
  • Deleting the tenant in Identiguard also deactivates and removes the event hook in Okta. Remove the integration in Okta as well if the client is leaving. See Managing tenants.
  • To change the event types, the agent monitoring or the name later, see Managing tenants.
  • To change the secret later, see Rotate credentials.

Field errors show in red under the field. Other errors show as a red toast. A toast that starts with Failed to create tenant: comes from the server.

What you see Why What to do
“Only workspace admins can create tenants.” and a disabled Admin Access Required button Your role is member or viewer Ask a workspace admin to create the tenant.
You open the create page and land back on Tenants Only admins can open the create page Ask a workspace admin.
“Tenant name cannot be empty” Tenant Name is blank Enter a name.
“Tenant name must be 100 characters or fewer” The name is too long Shorten it.
“Tenant name cannot contain line breaks or control characters” The name was pasted with hidden characters Type the name by hand.
“Customer name is required” Customer Name is blank Enter the customer.
“Okta domain is required” Okta Domain is blank Enter the org URL.
“Enter Okta base URL (e.g., https://login.example.com)” The domain is not a valid base URL Enter the org URL with https:// and no path.
“Environment is required” No environment is chosen Choose Production or Development.
“Client ID is required” or “Client secret is required” The field is blank Copy the value from the integration in Okta.
“At least one event type must be selected” Nothing is ticked under Subscribed Event Types Tick at least one type.
“Invalid event type submitted” The page sent a type that is not on the allowed list Reload the page and select the types again.
What you see Why What to do
“Failed to create tenant: The <Plan> plan allows up to N tenants per workspace, and this workspace already has M. Upgrade the plan to add more.” The workspace is at its plan tenant limit Delete a tenant you no longer need, or upgrade the plan. See Plans and billing.
“Failed to create tenant: This Okta org has already been used in another Identiguard trial, so it cannot be added to a new one. Choose a plan on the Billing page to add it, or contact Identiguard support.” Trial workspace. Another trial already used this org. Choose a paid plan, or contact Identiguard support.
“Failed to create tenant: Identiguard could not sign in to this Okta org with the client ID and client secret provided, so it cannot be added. Check them and try again.” Trial workspace. Okta refused the client ID and secret. Check both values. Check that the integration is installed and authorised in Okta.
“Failed to create tenant: Identiguard could not reach this Okta org to check the client ID and client secret. Try again in a few minutes.” Trial workspace. Okta did not answer. Check the domain, then try again in a few minutes.
“Failed to create tenant: Failed to create Okta Event Hook: <Okta message>” Okta rejected the hook. Common causes: wrong credentials, the okta.eventHooks.manage scope is missing, or the org has reached its event hook limit. Read the Okta message. Fix the credentials or the scope, then try again.
“Failed to create tenant: Failed to verify Okta Event Hook: <Okta message>” Okta’s one-time verification call to Identiguard failed Try again. If it repeats, escalate to the product team.
“Failed to create tenant: Failed to activate Okta Event Hook: <Okta message>” Okta refused to activate the hook In Okta, open Workflows → Event Hooks and remove any leftover IG_Tenant_ hook for this tenant. Then try again.
“Forbidden: You do not have permission to create tenants.” Your role changed while the page was open Ask a workspace admin.
“Failed to create tenant: Bad Request” The server rejected the form Check every field again. Escalate if it continues.
“Failed to create tenant: API error” or “An unexpected error occurred: …” An unexpected error Try again, then escalate to the product team.
“Failed to create tenant: Server configuration error…” A platform problem Escalate to a platform operator.
What you see Why What to do
No confirmation after you choose Create Okta Tenant The Tenants page does not show a success message Check for the new row in Tenant overview.
No events on the Dashboard Nothing has happened in the org yet, or the hook is not active Send a test event (step 3). In Okta, check that the IG_Tenant_ hook is Active.
A toast “<tenant name> connection unhealthy” An agent check was refused See Tenant health.