This guide walks you through connecting your Okta environment to TruU TOTAL for persona generation and threat detection.

Overview

TOTAL ingests identity and authentication event data from your Okta tenant via the Okta System Log API. We poll the /api/v1/logs endpoint on a configurable interval to collect, normalize, and correlate authentication events, MFA challenges, user lifecycle changes, and administrative actions across your environment. Connector Type: Polling

Prerequisites

Okta Administrator access with permission to create API tokens or OAuth 2.0 service apps
Okta tenant (production or preview) with active users and event logging enabled
Super Admin or Read-Only Admin role for the service account
Approximately 15 minutes to complete setup

Step 1: Identify Your Okta Org URL

Sign in to your Okta Admin Console
Your Okta Org URL is displayed in the browser address bar — it follows the format https://your-org.okta.com
Paste the Org URL into the TruU Portal

The Org URL is your unique Okta domain, e.g. https://acme.okta.com or https://acme.oktapreview.com for sandbox environments.

Step 2: Create an API Service Account (OAuth 2.0 — Recommended)

TOTAL authenticates to your Okta tenant using a scoped OAuth 2.0 service app with the Client Credentials grant flow.

In the Okta Admin Console, navigate to Applications → Applications
Click Create App Integration
Select API Services and click Next
Enter:
- Name: TruU TOTAL - Log Reader
Click Save
On the app’s General tab, copy the Client ID
Under Client Credentials, select Public key / Private key
Click Add Key, generate a new key pair, and copy the Private Key (JSON)
Paste the Client ID and Private Key into the TruU Portal

Assign Required Scopes

Navigate to Security → API → Tokens (or the app’s Okta API Scopes tab)
Grant the following scope:
- okta.logs.read
Optionally assign the Read-Only Administrator role to the service app under Admin Roles

Alternative: If your organization prefers SSWS API tokens, you can generate one under Security → API → Tokens. Copy the token value immediately — it is only shown once. Paste it into the TruU Portal. Note that SSWS tokens have broader access and shorter rotation cycles than scoped OAuth 2.0 tokens.

Step 3: Verify Connectivity

Once credentials are entered in the TruU Portal:

Click Test Connection — TOTAL will issue a test query against your System Log API
If successful, you’ll see a confirmation with the number of recent events detected
If configured, TOTAL will run a historical data pull on initial setup to seed user personas before live monitoring begins

Security & Privacy

What We Access

Read-only access to the Okta System Log via /api/v1/logs
Queries use since / until filtering — we only fetch new events since the last poll
All API calls are scoped to the okta.logs.read permission

What We Don’t Have Access To

Write access to your Okta tenant
Ability to create, modify, or delete users, groups, or policies
Access to user passwords or MFA secrets
Access to Okta configuration or administrative functions

Updating or Rotating Credentials

Rotate OAuth 2.0 Keys (Recommended: Before expiry)

In Okta Admin Console, go to Applications → TruU TOTAL - Log Reader
Under Client Credentials, click Add Key to generate a new key pair
Copy the new private key and paste it into the TruU Portal
After TOTAL confirms the new key is active, deactivate the old key

Revoke Access

To immediately remove TOTAL’s access:

Option A — Disable in the TruU Portal:
- Go to the TruU Portal → Settings → Connectors
- Find the Okta connector and click Disable
Option B — Deactivate the app in Okta:
- Go to Applications → TruU TOTAL - Log Reader
- Click Deactivate
Option C — Delete the app:
- Go to Applications → TruU TOTAL - Log Reader
- Click Delete

Rate Limiting & Scalability

Okta API Rate Limits

Parameter	Limit
System Log endpoint	~120 req/min org-wide (varies by tier)
Per-token share	Up to 50% of the org-wide bucket
Response page size	100 events per response (adjustable)
Throttle response	HTTP 429 with `Retry-After` header
DynamicScale add-on	Multiplies limits on eligible endpoints

Ingestion Capacity

At the standard tier, TOTAL sustains ~200 events/sec — approximately 17.2M events/day. A large enterprise with 100K+ users typically generates 500K–2M Okta events/day, giving TOTAL 8–30× headroom above expected volume. Peak-hour surges (3–5× average during morning logins) are absorbed without approaching the ceiling.

Event Freshness

Events appear in the Okta System Log within seconds. TOTAL polls on a configurable interval (default: 60 seconds). End-to-end latency from event occurrence to TOTAL processing is typically under 2 minutes.

Resilience

TOTAL uses cursor-based ingestion with at-least-once delivery. The polling cursor only advances after events are successfully collected, normalized, and published. If any step fails — API throttling, network interruption, process restart — the cursor stays put and the next poll replays from the last known-good position. No events are lost. Transient failures (429s, 5xx, timeouts) are retried automatically with exponential backoff. After 5 consecutive failures, the connector self-pauses to prevent runaway retries and can be re-enabled from the TruU Portal. On recovery from an extended outage, TOTAL resumes from its last cursor — Okta retains System Log events for 90 days, so data loss requires 90+ days of downtime.

Part 2: Event Types & Data Schema

Signal Classification

Signal Class	TOTAL Category
Core IAM	Authentication, Admin
MFA & Device Trust	Authentication

Event Types We Ingest

TOTAL extracts the following categories of events from the Okta System Log. Every event is tied to a human identity via the actor field. System-level events (policy creation, application lifecycle) that are not attributable to a specific user are excluded.

Authentication Events

Okta Event Type	Description	TOTAL Classification
`user.authentication.sso`	SSO authentication into an application	Authentication
`user.authentication.auth_via_mfa`	Authentication via MFA challenge	Authentication
`user.authentication.auth_via_IDP`	Authentication via external Identity Provider	Authentication
`user.authentication.auth_via_social`	Authentication via social login	Authentication
`user.authentication.verify`	Step-up authentication verification	Authentication
`user.session.start`	User session initiated	Authentication
`user.session.end`	User session terminated	Authentication
`user.session.clear`	All sessions cleared for a user	Authentication
`user.authentication.auth_via_radius`	Authentication via RADIUS	Authentication

MFA / Factor Events

Okta Event Type	Description	TOTAL Classification
`user.mfa.factor.activate`	MFA factor enrolled and activated	Authentication
`user.mfa.factor.deactivate`	MFA factor removed	Authentication
`user.mfa.factor.reset_all`	All MFA factors reset for a user	Authentication
`user.mfa.factor.update`	MFA factor updated	Authentication
`user.mfa.attempt_bypass`	MFA bypass attempted	Authentication
`user.authentication.auth_via_mfa`	MFA challenge completed	Authentication

User Lifecycle Events

Okta Event Type	Description	TOTAL Classification
`user.lifecycle.create`	New user created	Admin
`user.lifecycle.activate`	User account activated	Admin
`user.lifecycle.deactivate`	User account deactivated	Admin
`user.lifecycle.suspend`	User account suspended	Admin
`user.lifecycle.unsuspend`	User account unsuspended	Admin
`user.lifecycle.delete.initiated`	User deletion initiated	Admin
`user.account.lock`	User account locked	Authentication
`user.account.unlock`	User account unlocked	Admin
`user.account.unlock_token`	Unlock token generated	Admin

Group & Role Events

Okta Event Type	Description	TOTAL Classification
`group.user_membership.add`	User added to group	Admin
`group.user_membership.remove`	User removed from group	Admin
`user.account.privilege.grant`	Admin privilege granted to user	Admin
`user.account.privilege.revoke`	Admin privilege revoked from user	Admin

Application Access Events

Okta Event Type	Description	TOTAL Classification
`app.user_management.assign_user_to_app`	User assigned to application	Admin
`app.user_management.deactivate_user`	User deactivated from application	Admin
`application.provision.user.push`	User pushed to downstream app	Admin

Security Events

Okta Event Type	Description	TOTAL Classification
`security.threat.detected`	Threat detected for a user by Okta ThreatInsight	Alert
`security.request.blocked`	User’s request blocked by ThreatInsight	Alert

Sample Source Event (Okta System Log)

{
  "uuid": "f4d7e3c2-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "published": "2026-03-15T14:32:18.000Z",
  "eventType": "user.authentication.sso",
  "version": "0",
  "severity": "INFO",
  "displayMessage": "User single sign on to app",
  "actor": {
    "id": "00u1a2b3c4d5e6f7g8",
    "type": "User",
    "alternateId": "jane.doe@acme.com",
    "displayName": "Jane Doe"
  },
  "client": {
    "userAgent": {
      "rawUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "os": "Windows 10",
      "browser": "CHROME"
    },
    "zone": "null",
    "device": "Computer",
    "id": null,
    "ipAddress": "198.51.100.42",
    "geographicalContext": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "postalCode": "94105",
      "geolocation": {
        "lat": 37.7749,
        "lon": -122.4194
      }
    }
  },
  "outcome": {
    "result": "SUCCESS",
    "reason": null
  },
  "target": [
    {
      "id": "0oa1a2b3c4d5e6f7g8",
      "type": "AppInstance",
      "alternateId": "Salesforce",
      "displayName": "Salesforce Production"
    }
  ],
  "transaction": {
    "type": "WEB",
    "id": "WcKr0pJxZmwAkLo2s",
    "detail": {}
  },
  "authenticationContext": {
    "authenticationProvider": "FACTOR_PROVIDER",
    "credentialProvider": null,
    "credentialType": "OTP",
    "externalSessionId": "102abc_session_xyz",
    "interface": null,
    "issuer": null
  },
  "securityContext": {
    "asNumber": 7018,
    "asOrg": "AT&T",
    "isp": "AT&T",
    "domain": "att.net",
    "isProxy": false
  }
}

TOTAL Normalized Event

The raw Okta event above is normalized into the TOTAL event schema:

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "AUTH",
  "source": "OKTA",
  "signal_type": "CORE_IAM",
  "domain_id": "customer-domain-001",
  "tuid": "tuid-jane-doe-001",
  "timestamp": "2026-03-15T14:32:18.000Z",
  "payload": {
    "event_id": "f4d7e3c2-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "user": "jane.doe@acme.com",
    "action": "user.authentication.sso",
    "outcome": "SUCCESS",
    "target_app": "Salesforce Production",
    "ip_address": "198.51.100.42",
    "city": "San Francisco",
    "country": "United States",
    "device": "Computer",
    "browser": "CHROME",
    "os": "Windows 10",
    "mfa_method": "OTP"
  },
  "raw_metadata": {
    "platform_event_id": "f4d7e3c2-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "event_type": "user.authentication.sso",
    "actor_id": "00u1a2b3c4d5e6f7g8",
    "actor_email": "jane.doe@acme.com",
    "actor_display_name": "Jane Doe",
    "outcome": "SUCCESS",
    "client_ip": "198.51.100.42",
    "client_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "client_device": "Computer",
    "geo_city": "San Francisco",
    "geo_state": "California",
    "geo_country": "United States",
    "geo_lat": 37.7749,
    "geo_lon": -122.4194,
    "authentication_provider": "FACTOR_PROVIDER",
    "credential_type": "OTP",
    "external_session_id": "102abc_session_xyz",
    "target_id": "0oa1a2b3c4d5e6f7g8",
    "target_type": "AppInstance",
    "target_display_name": "Salesforce Production",
    "security_as_org": "AT&T",
    "security_is_proxy": false,
    "created_at": "2026-03-15T14:32:18.000Z",
    "source_platform": "okta"
  },
  "platform_event_id": "f4d7e3c2-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "platform_event_source": "OKTA_SYSTEM_LOG_API"
}

How This Feeds TOTAL

Persona Building

Okta is one of the highest-value signal sources for TOTAL. Every SSO authentication, MFA challenge, and session event contributes to a user’s digital routine baseline — what apps they access, when, from where, and how they authenticate. This forms the core identity anchor of each persona.

Anomaly Detection

TOTAL’s behavioral engine uses Okta events to detect:

Impossible travel — authentication from geographically impossible locations within a short time window
Credential compromise indicators — failed authentication bursts, password spray patterns, unusual SSO targets
MFA fatigue attacks — rapid repeated MFA push notifications indicating an attacker trying to exhaust a user into approving
Privilege escalation — unexpected admin role grants, group membership changes that expand access boundaries
Account takeover signals — MFA factor resets, session anomalies, authentication from new devices or ISPs that deviate from the established persona

Breach Lifecycle Coverage

Okta events provide primary coverage across Compromise Identity, Scope / Lateral Movement, and Privilege Escalation stages — the earliest and most critical phases where TOTAL aims to shift detection left toward t₀.

Documentation Index

​Overview

​Prerequisites

​Step 1: Identify Your Okta Org URL

​Step 2: Create an API Service Account (OAuth 2.0 — Recommended)

​Assign Required Scopes

​Step 3: Verify Connectivity

​Security & Privacy

​What We Access

​What We Don’t Have Access To

​Updating or Rotating Credentials

​Rotate OAuth 2.0 Keys (Recommended: Before expiry)

​Revoke Access

​Rate Limiting & Scalability

​Okta API Rate Limits

​Ingestion Capacity

​Event Freshness

​Resilience

​Part 2: Event Types & Data Schema

​Signal Classification

​Event Types We Ingest

​Authentication Events

​MFA / Factor Events

​User Lifecycle Events

​Group & Role Events

​Application Access Events

​Security Events

​Sample Source Event (Okta System Log)

​TOTAL Normalized Event

​How This Feeds TOTAL

​Persona Building

​Anomaly Detection

​Breach Lifecycle Coverage