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.
Before you start
Section titled “Before you start”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”- Sign in to the Okta Admin Console.
- Go to Applications → Applications and choose Browse App Catalog.
- Search for Identiguard and choose Add Integration.
- Review the access it asks for and choose Install & Authorize.
- Copy the client secret. Okta shows it once.
- Leave the page open. You need the Okta domain and client ID from it in the next step.
2. Create the tenant in Identiguard
Section titled “2. Create the tenant in Identiguard”- Open the workspace and go to Tenants.
- Under Create a tenant, find the Okta card (caption Workforce identity) and choose Connect. The page Add New Okta Tenant opens.
- Fill in the form. Every field is described in the table below.
- 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.
- Optionally, under Agent Monitoring, tick Monitor AD Agents or Monitor LDAP Agents and choose a Check Interval (minutes).
- Choose Create Okta Tenant. The button reads Creating… while Identiguard works.
The fields
Section titled “The fields”| 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.
Choosing event types
Section titled “Choosing event types”- 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.
What happens when you create the tenant
Section titled “What happens when you create the tenant”- 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.
- 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>. - You return to the Tenants page.
3. Send a test event
Section titled “3. Send a test event”- In Okta, go to Workflows → Event Hooks.
- Open the hook Identiguard created and go to Preview.
- Choose any event type and choose Deliver Request.
- In Identiguard, open Dashboard. The event appears under Real-time events.
What Identiguard can read
Section titled “What Identiguard can read”| 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.
Good to know
Section titled “Good to know”- 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.
Troubleshooting
Section titled “Troubleshooting”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.
Form validation
Section titled “Form validation”| 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. |
Creation errors
Section titled “Creation errors”| 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. |
After creation
Section titled “After creation”| 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. |