Okta Logs

Okta Logs Collector utilizes a pull-based mechanism to retrieve authentication and system events from your Okta organization. This collector interfaces with the Okta System Log API to provide comprehensive visibility into user activities, security events, and system changes within your Okta environment through periodic HTTP requests.

Purpose

The purpose of the Okta Logs Collector source in Observo AI is to enable the platform to actively retrieve system log data from Okta's REST API endpoints by polling or making periodic requests to the Okta System Log API (/api/v1/logs). It pulls authentication events, user management activities, administrative actions, and security events in JSON format from your Okta organization into Observo AI for analysis and processing. This integration supports streamlined data pipelines, real-time security monitoring, and compliance analytics, allowing organizations to enhance observability, detect suspicious activities, and maintain audit trails by proactively fetching log data from Okta's configured endpoints.

Prerequisites

Before configuring the Okta Logs Collector source in Observo AI, ensure the following requirements are met to facilitate seamless data ingestion:

• Okta Organization Access:

  • An active Okta organization (production, preview, or government cloud) must be available.

  • Obtain your Okta domain (e.g., company.okta.com, dev-123456.okta.com) from your Okta administrator.

• Authentication:

  • API Token: Generate an API token from the Okta Admin Console with appropriate permissions:

    • Read-only Administrator role OR

    • Custom role with okta.logs.read permission

  • The API token must be created by an administrator account with sufficient privileges to access system logs.

• Network and Connectivity:

  • Ensure Observo AI can communicate with your Okta domain over HTTPS (port 443).

  • Check for proxy settings, firewall rules, or network policies that may affect connectivity to Okta's API endpoints.

  • Verify that Okta's IP ranges are allowlisted if your organization uses IP-based access controls.

Prerequisite	Description	Notes
Okta Organization	Active Okta org with system logs enabled	Obtain domain from Okta administrator
Authentication	API Token with log read permissions	Create token with Read-only Admin or okta.logs.read scope
Network	HTTPS connectivity to Okta domain	Check firewalls, proxies, and IP allowlists

Integration

The Integration section outlines the configurations for the Okta Logs Collector source. To configure the Okta Logs Collector as a source in Observo AI, follow these steps to set up and test the data flow:

1. Log in to Observo AI:

• Navigate to the Sources tab.

• Click the Add Source button and select Create New.

• Choose Okta Logs Collector from the list of available sources to begin configuration.

1. General Settings:

• Okta Domain: Your Okta organization domain (e.g., company.okta.com, dev-123456.okta.com, company.oktapreview.com, or company.okta-gov.com). Do not include the https:// protocol prefix.

• Collection Interval (seconds): Frequency at which the collector polls the Okta API for new log events. Range: 10-86,401 seconds. Default: 120 seconds (2 minutes).

• Start From: Initial timestamp for beginning log collection in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Only used during the first collection cycle. Leave empty to start from the current time.

  • Examples: 2024-01-01T00:00:00.000Z, 2025-01-15T08:30:00.000Z

1. Authentication:

• Authentication Strategy: Bearer Authentication

• Auth Token: Your Okta API token generated from the Okta Admin Console. This field is masked for security.

• Bearer Header: HTTP header name used to send the bearer token. Default: Authorization

• Bearer Token Prefix: Prefix prepended to the token value. Default: SSWS (note the trailing space for Okta's Single Sign-on With Session format).

1. TLS Configuration (Optional):

• Toggles use of TLS: Enable to configure custom TLS/SSL certificates. Default: disabled (uses standard HTTPS).

• When enabled, configure the following as needed:

  • CA Certificate File: Absolute path to a Certificate Authority (CA) certificate file.

  • Certificate File: Absolute path to the client certificate file for mutual TLS.

  • Private Key File: Absolute path to the private key file.

  • Private Key Password: Password for encrypted private key files.

  • Verify Certificate: Enable to validate server certificates against trusted authorities.

  • Verify Hostname: Enable to ensure server hostname matches certificate.

1. Advanced Settings:

• Okta Collection Script: Pre-configured Lua script that handles the collection logic.

Data Types Collected

The Okta Logs Collector captures the following categories of events from the Okta System Log API:

Authentication Events

• User login attempts (successful and failed)

• Multi-factor authentication (MFA) challenges and verifications

• Password changes and resets

• Session creation and termination

• Single Sign-On (SSO) activities

User Management Events

• User account creation, modification, and deactivation

• Profile updates and attribute changes

• Group membership changes

• User imports and exports

Administrative Actions

• Policy creation and modifications

• Application assignments and configurations

• Administrator role assignments

• Security settings changes

System Events

• API token generation and usage

• Rate limit violations

• System configuration changes

• Audit log access

Security Events

• Suspicious activity detection

• Account lockouts

• Security policy violations

• ThreatInsight events

Each log entry is automatically tagged with _okta_event_type: "systemLog" for easy identification and filtering within Observo AI.

Error Handling

The Okta Logs Collector implements comprehensive error handling to ensure reliability and provide clear diagnostics:

HTTP Status Code Handling

Status Code	Action	Message	Resolution
200 OK	Processes log entries and emits to pipeline	Success	Continues with pagination if Link header present
400 Bad Request	Logs error and halts	"Bad request - check API parameters"	Verify domain, timestamp format, and URL parameters
401 Unauthorized	Logs error and halts	"Authentication failed - check OKTA_API_TOKEN"	Verify API token validity, expiration, and permissions
429 Too Many Requests	Logs warning and retries	"Rate limit exceeded - will retry"	Automatically retries with exponential backoff; consider adjusting collection interval
Other errors	Logs generic error	"Failed to fetch Okta system logs. Status={status}"	Check Okta API status and network connectivity

Retry Mechanism

The collector includes built-in retry logic for transient failures:

• Automatic Retries: Enabled for network issues and rate limits

• Checkpoint Persistence: Maintains collection state to prevent data loss and duplication

Common Troubleshooting

Issue	Symptoms	Resolution
Authentication Failure	401 errors, no data collected	Verify API token is valid and not expired; check service account permissions
Rate Limiting	429 errors, slow collection	Increase collection interval; review Okta rate limit consumption
Empty Responses	No logs collected despite activity	Confirm events exist in specified time range; verify Okta domain is correct
TLS Connection Errors	Cannot connect to Okta	Verify certificate paths, permissions, and TLS configuration