Okta (im_okta)
This module fetches log events from Okta services using the Okta System Log API.
| To examine the supported platforms, see the list of installer packages in the Available Modules chapter. |
Pagination
The Okta API returns the log events in pages.
Each page provides a set of events and, if there are more events, a next link in the response headers (via the Link header) for the following page of events.
The module follows this link to fetch subsequent pages of events, continuing until there are no more next links or when the rate limit defined by Okta is reached.
If the Okta rate limit is hit, the module automatically backs off and retries once the rate limit resets (as indicated by the x-rate-limit-reset header).
To prevent the module from reaching the rate limit, the module waits the configured PollDelay between each request.
When all records are received, the module waits for the configured PollInterval before polling the API again for new events.
Configuration
The im_okta module accepts the following directives in addition to the common module directives.
Required directives
The following directives are required for the module to start.
The Okta API token for authentication. This token must have the required permissions to read system logs. |
|
The base URL of the Okta API endpoint.
For example, |
Optional directives
The maximum number of events to retrieve per API call.
The value must be a positive integer greater than 0.
The default value is |
|||||||||||||||||||||||||||||||||||||
The unconditional delay, in seconds, between the API calls to Okta for the next page of results.
The directive overcomes a known limitation in Okta, where the rate limit is not handled well when processing concurrent requests.
If this directive is not set, the module will request data as quickly as possible until it either reaches the end of the results or the rate limit allowed by Okta.
In the case of the latter, the module then waits for the limit to reset.
The value must be a positive integer, including 0.
The default value is |
|||||||||||||||||||||||||||||||||||||
How frequently the module will check for new events in seconds.
The value must be a positive integer greater than 0.
The default value is |
|||||||||||||||||||||||||||||||||||||
This optional boolean directive instructs the module on where to start reading events from the log source. Reading all events can result in a lot of messages and is usually not the expected behavior. When The following matrix shows the outcome of this directive in conjunction with the SavePos directive:
|
|||||||||||||||||||||||||||||||||||||
This optional boolean directive instructs the module whether to save the position of the last read event before NXLog exits. On the next startup, NXLog will try to read the saved position from the cache file. This directive in conjunction with the ReadFromLast directive allows for resuming reading events directly from the saved position. When This directive can be overridden by the global NoCache directive.
If NoCache is |
|||||||||||||||||||||||||||||||||||||
The time interval for the first event to pull, using a duration format such as |
Example
This configuration collects Okta logs and converts the records to JSON format using the xm_json module.
<Extension json>
Module xm_json
UnFlatten true
</Extension>
<Input okta>
Module im_okta
Token "your-token"
URL "https://yourdomain.okta.com"
Limit 50 (1)
PollInterval 30 (2)
PollDelay 1 (3)
Since 10d (4)
Exec to_json(); (5)
</Input>| 1 | Limit is set to retrieve 50 events in each API call. |
| 2 | PollInterval is reduced to 30 seconds to check for new events more frequently. |
| 3 | PollDelay is set to 1 second, defining the minimal delay between each API call. |
| 4 | Since is set to 10d to retrieve logs from 10 days ago if the module does not find a saved state. |
| 5 | The record is converted to JSON using the to_json() procedure of the xm_json module. |
The following is an Okta log record after it was processed by NXLog.
{
"authenticationContext": {
"authenticationProvider": null,
"authenticationStep": 0,
"credentialProvider": null,
"credentialType": null,
"externalSessionId": "102ff_BfG_5SXq__r791m8kHA",
"interface": null,
"issuer": null,
"rootSessionId": "102ff_BfG_5SXq__r791m8kHA"
},
"published": "2025-04-05T06:44:38.410Z",
"device": null,
"severity": "INFO",
"version": "0",
"legacyEventType": "core.user.factor.activate",
"client": {
"device": "Computer",
"geographicalContext": {
"city": "London",
"country": "United Kingdom",
"geolocation": {
"lat": "12.3456",
"lon": "13.4567"
},
"postalCode": "TW1",
"state": "London"
},
"id": null,
"ipAddress": "82.46.11.6",
"userAgent": {
"browser": "CHROME",
"os": "Windows 11",
"rawUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
},
"zone": "null"
},
"securityContext": {
"asNumber": 12312,
"asOrg": "internet service provider",
"domain": "example.com",
"isProxy": false,
"isp": "isp limited"
},
"displayMessage": "Activate factor for user",
"request": {
"ipChain": [
{
"geographicalContext": {
"city": "London",
"country": "United Kingdom",
"geolocation": {
"lat": "12.3456",
"lon": "13.4567"
},
"postalCode": "TW1",
"state": "London"
},
"ip": "82.46.11.6",
"source": null,
"version": "V4"
}
]
},
"debugContext": {
"debugData": {
"dtHash": "e710faf0b9abefe7af996343a890c9515f20897925865723df86d46d4d0e5209",
"requestId": "73d1b6d4c7d26028a6a7fb3c4e3b1ee6",
"requestUri": "/api/v1/users",
"traceId": "dac9a6ca-1d43-4d14-9a3f-4fd4310f9dbf",
"url": "/api/v1/users?activate=true"
}
},
"transaction": {
"detail": {},
"id": "73d1b6d4c7d26028a6a7fb3c4e3b1ee6",
"type": "WEB"
},
"uuid": "71e0df02-11e9-11f0-a0dc-8d9442950784",
"outcome": {
"reason": "User set up EMAIL_FACTOR factor",
"result": "SUCCESS"
},
"eventType": "user.mfa.factor.activate",
"target": [
{
"alternateId": "jdoe@mycompany.com",
"detailEntry": null,
"displayName": "John Doe",
"id": "00uqc335qjMxn7vAV687",
"type": "User"
}
],
"actor": {
"alternateId": "jbloggs@mycompany.com",
"detailEntry": null,
"displayName": "Joe Bloggs",
"id": "00uqa26xldEKVpwB3679",
"type": "User"
},
"EventReceivedTime": "2025-04-05T08:45:56.327215+02:00",
"SourceModuleName": "okta",
"SourceModuleType": "im_okta",
"Hostname": "PC-1"
}
