Okta connector (API token)

When to use this connector

• You are an Okta-first or Okta-plus-Microsoft tenant and want ITDR to detect and respond to identity threats on the Okta side.
• You are comfortable issuing an Okta admin API token. API token is the fastest path; an OAuth admin-consent flow is planned for a follow-up but is not yet available.
• You have at least one Okta admin who can sign into the Okta admin console and create a token under Security > API > Tokens.

What ITDR ingests from Okta

• Okta users (status, profile, last sign-in) into the platform identities table with provider="okta". Provider badge appears on /identities.
• Okta system-log auth events (user.session.start, user.authentication.*) into the platform sign_in_events table with provider="okta". Mapped to the same columns Microsoft uses (app, IP, location, status_error_code, failure_reason, device summary, is_interactive) so the existing sign-in detection rules fire on Okta data with no rule changes.
• Incremental ingest after the first run via a cursor stored on the connector. Fresh connectors backfill the prior seven days.

Required Okta scopes

• okta.users.read — Pull the user inventory to populate /identities with okta-provider rows. Without it the first sync fails the validate call with a 403.
• okta.logs.read — Pull the system log (auth + lifecycle events). Without it sign-in events never reach /alerts or detection.
• okta.users.manage — Required only if you want the containment bundle Contain identity to run on Okta-linked incidents — it calls /lifecycle/deactivate and DELETE /sessions. Without this scope the bundle errors at execution time but the rest of the connector still works.

How to create an API token in Okta

1. Sign in to your Okta admin console as a Super Admin (or any admin with the API Access Management permission).
2. Navigate to Security > API > Tokens.
3. Click "Create Token". Name it something like "ITDR Platform Token" and confirm.
4. Copy the token immediately — Okta only shows it once. ITDR encrypts the token at rest using the same Fernet pipeline used for Microsoft connector secrets.
5. Confirm the token operates with at least the required scopes above. Tokens inherit the permissions of the user who created them, so use a service account or a dedicated admin.

How to add the connector in ITDR

1. In ITDR, open /connectors.
2. In the "Add connector" card, click the fourth pill: Okta (API token).
3. Fill in: Connector name (free text), Okta org URL (e.g. https://your-org.okta.com), and the API token.
4. Click Create Okta connector. The backend validates the token against /api/v1/users?limit=1 before persisting. On success you see a green "Okta connector created" message; on failure you see a specific reason (401 = bad token, 403 = wrong scope, 404 = wrong org URL).
5. Within five minutes the ops-worker okta_sync job picks up the connector, ingests users and the prior seven days of system-log auth events, and starts the cursor-based incremental loop.

Detection coverage on Okta data

• repeated_failed_signins fires on Okta auth failures the same way it fires on Microsoft 4xx error codes.
• success_after_failed_signins fires on Okta failure → success patterns within the same window.
• rapid_location_change fires on Okta sign-ins from geographically inconsistent IPs.
• risky_signin_success — partial coverage. Okta does not publish a unified per-event risk score like Microsoft Sign-in Risk, so this rule only fires on Microsoft events for now.
• aitm_token_replay_distinct_device — Microsoft-only for now. Okta has session and device fingerprint metadata but the rule expects Microsoft fingerprint shape.

Containment on Okta-linked incidents

• Contain identity bundle works on Okta-linked incidents: revoke sessions calls DELETE /api/v1/users/{id}/sessions; disable user calls POST /api/v1/users/{id}/lifecycle/deactivate.
• Single-approver flow (the requestor auto-approves their own request) — same as Microsoft for non-destructive bundles.
• Audit trail captures the Okta API calls under the existing containment_bundle.* event types.
• Device bundles (lock, wipe, retire) require Microsoft Intune permissions and are not applicable to Okta-only identities. If submitted, they error cleanly at execution time with "Device actions require an active Microsoft connector with Intune permissions" — they are not silently dropped.

Operational notes

• Sync runs every five minutes by default (same cadence as Microsoft). Adjustable per-connector via the sync_interval column.
• API token rotation: regenerate in Okta, then PATCH the connector configuration with the new token. The /connectors/okta/{id}/test endpoint re-validates and returns ok=true on success.
• Rate limits: Okta enforces per-org rate limits (typically 600 req/min for tokens). The Okta client honors Retry-After headers automatically with up to three exponential-backoff retries on 429.
• Error visibility: the connector row stores sync_status="error" and sync_error="<message>" on failure. Check /connectors detail or the worker logs.
• Okta posture scanning (admin role assignments, MFA factor coverage, password policy hygiene, sign-on MFA enforcement) runs every six hours when an Okta connector is active. See the Okta posture findings KB article for details.

Known limitations and what's coming

• Detection rules that key on Microsoft-specific Sign-in Risk fields (risk_level high/medium) skip Okta events because Okta does not publish a unified risk score.
• Device-based containment (lock, wipe, retire) requires Microsoft Intune and is not applicable to Okta-only identities. The bundle target_type filter already prevents these from appearing for identity-only Okta targets.
• Cross-provider identity dedup (matching the same human in Microsoft + Okta) is not yet automatic — they appear as separate rows in /identities with provider badges so analysts can correlate visually.