> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta

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

1. Sign in to your [Okta Admin Console](https://your-org.okta.com/admin)
2. Your Okta Org URL is displayed in the browser address bar — it follows the format `https://your-org.okta.com`
3. 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.

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

### Assign Required Scopes

1. Navigate to **Security** → **API** → **Tokens** (or the app's **Okta API Scopes** tab)
2. Grant the following scope:
   * `okta.logs.read`
3. 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:

1. Click **Test Connection** — TOTAL will issue a test query against your System Log API
2. If successful, you'll see a confirmation with the number of recent events detected
3. 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)

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

### Revoke Access

To immediately remove TOTAL's access:

1. **Option A** — Disable in the TruU Portal:
   * Go to the TruU Portal → **Settings → Connectors**
   * Find the Okta connector and click **Disable**

2. **Option B** — Deactivate the app in Okta:
   * Go to **Applications** → `TruU TOTAL - Log Reader`
   * Click **Deactivate**

3. **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)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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₀.