# System Audit Logs

Ingests Okta system events for audit trail analysis and platform activity monitoring.

**Sync Type: Incremental**

## Authentication

This input supports API Key and OAuth 2.0 (service app) authentication. See [Okta Authentication](./okta-auth) for setup instructions and required credentials for each method.

## Details
Monad keeps track of the state of the Input via a timestamp by using the the since filter parameter on the [api](https://developer.okta.com/docs/reference/api/system-log/). We use the timestamp of the last successful run to retrieve only newer logs that have appeared between the current and last successful runs of this Input.  Monad Generates a timestamp when initiating the sync. It will only save the timestamp if no errors occur during the sync.

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Org URL | string | Yes | Your Okta Organization URL. |
| Backfill Start Time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

#### Secrets

Secrets vary by authentication method. See [Okta Authentication](./okta-auth) for details. If using the Oauth flow, the token should be granted the ```okta.logs.read``` scope.

# OCSF Conversion

The following JQ transformation converts Okta System Log data to OCSF Version 1.1.0 compliant format.

## JQ Transformation

```jq
def clean_timestamp($ts):
  ($ts | split(".")[0] + "Z" | fromdateiso8601);

def get_activity_details($event_type):
  if ($event_type | strings and contains("user.authentication")) then
    {activity: "Logon", activity_id: 1}
  else
    {activity: "Unknown", activity_id: 0}
  end;

def get_audit_category($event_type):
  if ($event_type | strings and contains("user.authentication")) then
    {category_name: "Audit Activity events", category_uid: 3}
  else
    {category_name: "Unknown", category_uid: 0}
  end;

def get_event_class:
  {class_name: "Authentication", class_uid: 3002};

def get_clear_text_value($auth_protocol):
  if ($auth_protocol == null) then
    true  # Return true for null values
  elif ($auth_protocol | strings) then
    $auth_protocol != "FTP" and $auth_protocol != "TELNET"
  else
    true  # Default case
  end;

def get_destination_endpoint($debug_data):
  {
    hostname: ($debug_data.requestUri // ""),
    ip: "",
    instance_uid: "",
    interface_id: "",
    svc_name: ($debug_data.url // "")
  };

def get_logon_type($transaction):
  if ($transaction.type | strings and contains("WEB")) then
    {logon_type: $transaction.type, logon_type_id: 99}
  else
    {logon_type: ($transaction.type // "UNKNOWN"), logon_type_id: 0}
  end;

def get_severity($severity):
  if ($severity | strings and $severity == "INFO") then
    {severity: $severity, severity_id: 1}
  else
    {severity: ($severity // "UNKNOWN"), severity_id: 0}
  end;

def get_src_endpoint($data):
  {
    hostname: ($data.debugContext.debugData.requestUri // ""),
    "ip ": ($data.client.ipAddress // ""),
    interface_id: ($data.client.device // "")
  };

def get_src_user($data):
  {
    type: ($data.actor.type // ""),
    name: ($data.actor.displayName // ""),
    email_addr: ($data.actor.alternateId // "")
  };

def get_status_details($data):
  if ($data.outcome.result | strings and $data.outcome.result == "SUCCESS") then
    {
      status: $data.outcome.result,
      status_code: "N/A",
      status_detail: "LOGON_USER_INITIATED",
      status_id: 1
    }
  else
    {
      status: ($data.outcome.result // "UNKNOWN"),
      status_code: "N/A",
      status_detail: "",
      status_id: -1
    }
  end;

def get_enrichment_data($client_data):
  [{
    name: "geographicalContext",
    data: ($client_data.geographicalContext // {}),
    value: ($client_data.ipAddress // ""),
    type: "location"
  }];

def get_actor_data($actor_data):
  if $actor_data == null then 
    null 
  else 
    # Find the first element where type is "User"
    ($actor_data | map(select(.type == "User")) | first) // null |
    if . != null then {
      "user": {
        "uid": .id,
        "name": .displayName,
        "email_addr": .alternateId
      }
    } else null end
  end;

def get_type_category($event_type):
  if ($event_type | strings and contains("user.authentication")) then
    {type_name: "Authentication Audit: Logon", type_uid: 300201}
  else
    {type_name: "Unknown", type_uid: 0}
  end;

def get_metadata($time; $version):
  {
    original_time: ($time // ""),
    product: {
      vendor_name: "Okta",
      name: "Okta System Log"
    },
    version: ($version // "0")
  };

def get_auth_protocol($auth_provider):
  if ($auth_provider == null) then
    {auth_protocol: "Unknown", auth_protocol_id: 0}
  elif ($auth_provider | strings and contains("FACTOR")) then
    {auth_protocol: "Other / MFA", auth_protocol_id: 1}
  else
    {auth_protocol: "Unknown", auth_protocol_id: 0}
  end;

def transform_data:
  . as $data |
  {
  # Base OCSF Fields
  time: clean_timestamp($data.published),
  activity_name: (get_activity_details($data.eventType).activity),
  activity_id: (get_activity_details($data.eventType).activity_id),
  category_name: (get_audit_category($data.eventType).category_name),
  category_uid: (get_audit_category($data.eventType).category_uid),
  class_name: get_event_class.class_name,
  class_uid: get_event_class.class_uid,
  type_name: (get_type_category($data.eventType).type_name),
  type_uid: (get_type_category($data.eventType).type_uid),

  # Authentication Details
  authentication_info: {
    auth_protocol: (get_auth_protocol($data.authenticationContext.authenticationProvider).auth_protocol),
    auth_protocol_id: (get_auth_protocol($data.authenticationContext.authenticationProvider).auth_protocol_id),
    is_cleartext: get_clear_text_value($data.authenticationContext.authenticationProvider),
    session_uid: ($data.authenticationContext.externalSessionId // "")
  },

  # Source and Destination Information
  src_endpoint: get_src_endpoint($data),
  dst_endpoint: get_destination_endpoint($data.debugContext.debugData),

  # User Information
  src_user: get_src_user($data),
  dst_user: ($data.actor.alternateId // ""),
  user_info: {
    name: ($data.actor.displayName // ""),
    type: ($data.actor.type // ""),
    email_addr: ($data.actor.alternateId // "")
  },

  # Status and Severity Details
  severity: (get_severity($data.severity).severity),
  severity_id: (get_severity($data.severity).severity_id),
  status: (get_status_details($data).status),
  status_code: (get_status_details($data).status_code),
  status_detail: (get_status_details($data).status_detail),
  status_id: (get_status_details($data).status_id),

  # Login Information
  logon_info: {
    type: (get_logon_type($data.transaction).logon_type),
    type_id: (get_logon_type($data.transaction).logon_type_id)
  },

  # Actor Information
  actor: (get_actor_data($data.target)),

  # Enrichment Data
  enrichments: get_enrichment_data($data.client),

  # Metadata
  metadata: get_metadata($data.published; $data.version),

  # Additional Context
  raw_data: (. | tostring),
  display_message: ($data.displayMessage // ""),
  ref_time: ($data.published // "")
};

transform_data
```

## OCSF Mapping Details

The JQ transformation converts Okta System Logs to OCSF Version 1.1.0 with the following key mappings:

### Core Fields
- **Time**: Mapped from `published` timestamp with milliseconds stripped
- **Class UID**: Set to 3002 (Authentication)
- **Category UID**: Set to 3 (Audit Activity Events)
- **Type UID**: Set to 300201 (Authentication Audit: Logon)
- **Activity ID**: Mapped based on event type (1 for authentication events, 0 for unknown)
- **Severity ID**: Mapped from Okta severity levels:
    - INFO → 1
    - Others → 0 (Unknown)

### Authentication Information
- **Protocol**: Mapped from authentication provider context
    - MFA/FACTOR → Other / MFA (ID: 1)
    - Others → Unknown (ID: 0)
- **Session UID**: Maps from `externalSessionId`
- **Cleartext**: Determined based on authentication protocol

### Endpoint Information
- **Source Endpoint**:
    - Hostname: Maps from `debugContext.debugData.requestUri`
    - IP: Maps from `client.ipAddress`
    - Interface ID: Maps from `client.device`
- **Destination Endpoint**:
    - Hostname: Maps from `debugContext.debugData.requestUri`
    - Service Name: Maps from `debugContext.debugData.url`

### User Information
- **Source User**:
    - Name: Maps from `actor.displayName`
    - Type: Maps from `actor.type`
    - Email: Maps from `actor.alternateId`
- **Destination User**: Maps from `actor.alternateId`

### Status Information
- **Status**: Maps from `outcome.result`
    - SUCCESS → Status ID: 1
    - Others → Status ID: -1
- **Status Detail**: Set to "LOGON_USER_INITIATED" for successful authentication

### Login Information
- **Type**: Maps from `transaction.type`
    - WEB → Type ID: 99
    - Others → Type ID: 0

### Enrichment Data
- **Geographical Context**:
    - Maps location data from `client.geographicalContext`
    - Includes IP address from `client.ipAddress`

### Metadata
- **Version**: Default "1.1.0"
- **Product**:
    - Vendor Name: "Okta"
    - Name: "Okta System Log"
- **Original Time**: Preserved from source timestamp

### Customization
- The transformation maintains OCSF compliance while preserving Okta-specific context
- Optional fields include fallback values to ensure data consistency
- Enrichment data preserves geographical and device context for security analysis

## Related Articles
- [https://help.okta.com/en-us/content/topics/security/api.htm](https://help.okta.com/en-us/content/topics/security/api.htm)
- [https://developer.okta.com/docs/reference/api/system-log/](https://developer.okta.com/docs/reference/api/system-log/)
## Sample Record

```json
{
  "actor": {
    "id": "00u5syyx5nWoMofVG697",
    "type": "User",
    "alternateId": "carol.brown@example.com",
    "displayName": "Peter Williams",
    "detailEntry": null
  },
  "client": {
    "userAgent": {
      "rawUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537",
      "os": "Windows 10",
      "browser": "CHROME"
    },
    "zone": "zone1",
    "device": "Computer",
    "id": null,
    "ipAddress": "122.81.138.43",
    "geographicalContext": {
      "city": "Los Angeles",
      "state": "California",
      "country": "United States",
      "postalCode": "90001",
      "geolocation": {
        "lat": 34.0522,
        "lon": -118.2437
      }
    }
  },
  "device": null,
  "authenticationContext": {
    "authenticationProvider": null,
    "credentialProvider": null,
    "credentialType": null,
    "issuer": null,
    "interface": null,
    "authenticationStep": 0,
    "externalSessionId": "102iMPbbG5LQWie2hixFENZjA"
  },
  "displayMessage": "User accessing Okta admin app",
  "eventType": "user.session.access_admin_app",
  "outcome": {
    "result": "SUCCESS",
    "reason": null
  },
  "published": "2025-08-11T23:46:52.179765Z",
  "securityContext": {
    "asNumber": 7922,
    "asOrg": "comcast",
    "isp": "comcast",
    "domain": "comcast.net",
    "isProxy": false
  },
  "severity": "INFO",
  "debugContext": {
    "debugData": {
      "requestId": "43ac7e83fe4db209cde65a60660d0de4",
      "dtHash": "9d7615ea3e9691b91a63e1afe174d601aa4629a3634545dc54c80b86b4ac80fc",
      "requestUri": "/admin/sso/callback",
      "threatSuspected": "false",
      "url": "/admin/sso/callback?code=******&state=PL-xCLrZqA-VcVgCQeTfunyoliTaqrui"
    }
  },
  "legacyEventType": "app.admin.sso.login.success",
  "transaction": {
    "type": "WEB",
    "id": "43ac7e83fe4db209cde65a60660d0de4",
    "detail": {}
  },
  "uuid": "dbbb906c-b195-11ee-8a84-b58212db54c8",
  "version": "0",
  "request": {
    "ipChain": [
      {
        "ip": "73.63.194.174",
        "geographicalContext": {
          "city": "Los Angeles",
          "state": "California",
          "country": "United States",
          "postalCode": "90001",
          "geolocation": {
            "lat": 34.0522,
            "lon": -118.2437
          }
        },
        "version": "V4",
        "source": null
      }
    ]
  },
  "target": [
    {
      "id": "00u5syyx5nWoMofVG697",
      "type": "AppUser",
      "alternateId": "",
      "displayName": "Jane Johnson",
      "detailEntry": null
    }
  ]
}
```