Skip to main content
Sumo Logic

Collect Okta Logs

This page has instructions for collecting logs from Okta.

Prerequisites

The integration between Sumo and Okta relies upon SumoJanus, a proprietary library used for script-based collection from applications such as Okta, Box, and Salesforce. The system where you deploy SumoJanus and configure your installed collector and script source must have Java.

Process Overview

  1. Generate an Authentication Token in Okta.
  2. Download the SumoJanus Package necessary for authentication and deploy the package on a local server running the Sumo Logic Collector.
  3. Update the local properties file with the Okta token created in step 1. The Properties file will be generated in step 2 when you download and deploy the SumoJanus package.
  4. Configure an Installed Collector and create a Script Source in Sumo Logic to send the data from Okta to Sumo Logic.

The following sections provide detailed instructions:

Generate the Okta API token

Create an Okta API token, following instructions on the Create an API token page in Okta help. You will add the token to the SumoJanus properties file, later in this procedure

Download the SumoJanus Packages

The following SumoJanus files are required to collect logs from Okta.

  Linux Windows
SumoJanus v3.0.1 package file sumojanus-dist.3.0.1.tar.gz sumojanus-dist.3.0.1.zip
Okta bundle package for SumoJanus sumojanus-Okta-r1.0.1.tar.gz sumojanus-Okta-1.0.1.zip

Deploy the SumoJanus Packages

If you have not previously set up SumoJanus, follow the steps in New SumoJanus installation. If you have previously set up SumoJanus, follow the instructions in SumoJanus installation update.

New SumoJanus installation
  1. Copy the two package files you downloaded to the same folder, then unzip them there.
    • On Linux, run the following commands:
      tar xzvf sumojanus-dist.3.0.1.tar.gz 
      tar xzvf sumojanus-Okta-1.0.1.tar.gz
      
    • On Windows, use Windows Explorer to open the packages.

The first unzip will create a folder called sumojanus in the directory where you unzipped, along with relevant files. The second unzip will add more files to the folder which you need later.

SumoJanus installation update

If you have previously set up  SumoJanus, be aware that you can’t mix SumoJanus v2.0 and v3.x, and we recommend that you deploy v3.x  in a separate folder. If you already have a v3.x SumoJanus folder, follow these steps:

  1. Back up conf/sumologic.properties and the data folder.
  2. Copy the file sumojanus-Okta-1.0.1.tar.gz to the parent folder where SumoJanus is currently installed.
  3. From there, unzip the file sumojanus-Okta-1.0.1.tar.gz using the following command: tar xzvf sumojanus-Okta-1.0.1.tar.gz 
    This will copy the files from the Okta package to the sumojanus folder.

Edit the Properties file

  1. Open the file sumojanus/conf/sumologic.properties in a text editor and add the following lines.

    [generic]
    path = .

    # provide the parameters for a bundle via a unique section after this [oktacollector]
    # required, your Okta API token api_token =

    # required, your okta account URL, e.g: https://acme.okta.com okta_org_url =
    # required, file to keep track of the okta event stream stream_pos_path = ${path}/data/okta_checkpoint.dat
    # optional, maximum pagination limit is 100 #pagination_limit = 100
    #optional, start time window to query, in epoch milliseconds. Default is 7 days ago. #start_time = 1435709058000 # optional, end time window to query, in epoch milliseconds. Default is 1 minute ago #end_time = 1436377600000

     
  2. api_token. Enter the Okta API token that you created in the Generate the Okta API token step.
  3. okta_org_url. Enter your Okta URL. Note that the URL starts with https, and not http.
  4. stream_pos_path. Replace the ${path}variable with the actual path on the server where SumoJanus is installed. For example: "/home/sumojanus"
  5. Save your changes.

Once you’re done editing, your sumojanus/conf/sumologic.properties file should look similar to this:

Okta Properties File

Configure a Collector

Configure an Installed Collector on a Linux or Windows machine. By default the Collector will come with a Java Runtime Environment. To ensure that SumoJanus can locate Java, you may need to update the .bat or .bash file, as described below.

On Windows, update SumoJanus_Okta.bat

Navigate to the folder where you installed SumoJanus, and open SumoJanus_Okta.bat  in a text editor. Line 3 of the script sets JAVAPATH to C:\Program Files\Sumo Logic Collector\jre\bin as shown below:

set JAVAPATH="C:\Program Files\Sumo Logic Collector\jre\bin"

If your collector JRE is in a different location, update Line 3 accordingly.  

On Linux, update SumoJanus_Okta.bash

Navigate to the folder where you installed SumoJanus, and open SumoJanus_Okta.bash  in a text editor. Update the script as follows:

  1. Add a line that sets JAVA_HOME to point to the location of your JRE,  just before the last line of the script. For example, if your collector's JRE is in /opt/Sumocollector/jre/bin, insert this line:

    JAVA_HOME=/opt/Sumocollector/jre/bin
  2. The last line of the script is:

    java -jar ${SUMOJANUS_JAR_FILE} ${runMode} OktaCollector-1.0.1.jar -e 1800

    Prefix the line with $JAVA_HOME/, like this:

    $JAVA_HOME/java -jar ${SUMOJANUS_JAR_FILE} ${runMode} OktaCollector-1.0.1.jar -e 1800

Configure a Source

  1. Configure a Script Source.

    Linux

    Linux

    Windows

    Windows

  2. Configure the Source fields:
    1. Name. OktaCollector.
    2. (Optional) Description.
    3. Source Category. okta
    4. Frequency. Every 5 Minutes
    5. Specify a timeout for your command. Activate the checkbox and select 60 Minutes
    6. Command. For Linux, use/bin/bash. For windows, use Windows Script. (Specify the correct path on your system).
    7. Script. Use the path to sumojanus that you created in the Deploy the Packages step, such as /home/ubuntu/sumojanus/bin/SumoJanus_Okta.bash.(Do not select "Type the script to execute.")
    8. Working Directory. $path/sumojanus,where $path is the path of SumoJanus that you created in the Deploy the Packages step.
  3. Click Save.

Sample Log Message

{
   "actor":{
      "id":"00u17b6c3rwVP7kqo1d8",
      "type":"User",
      "alternateId":"kyle.diedrich@company.com",
      "displayName":"Kyle Diedrich",
      "detailEntry":null
   },
   "client":{
      "userAgent":{
         "rawUserAgent":"PostmanRuntime/3.0.11-hotfix.2",
         "os":"Unknown",
         "browser":"UNKNOWN"
      },
      "zone":"null",
      "device":"Unknown",
      "id":null,
      "ipAddress":"12.97.85.90",
      "geographicalContext":{
         "city":"San Francisco",
         "state":null,
         "country":"United States",
         "postalCode":"94107",
         "geolocation":{
            "lat":37.7697,
            "lon":-122.3933
         }
      }
   },
   "authenticationContext":{
      "authenticationProvider":null,
      "credentialProvider":null,
      "credentialType":null,
      "issuer":null,
      "interface":null,
      "authenticationStep":0,
      "externalSessionId":"trsp5PU7OIoTgCOdFBgJOQWIA"
   },
   "displayMessage":"Delete application",
   "eventType":"application.lifecycle.delete",
   "outcome":{
      "result":"SUCCESS",
      "reason":null
   },
   "published":"2017-10-02T17:38:45+0000",
   "securityContext":{
      "asNumber":null,
      "asOrg":null,
      "isp":null,
      "domain":null,
      "isProxy":null
   },
   "severity":"INFO",
   "debugContext":{
      "debugData":{
         "requestUri":"/api/v1/apps/0oa1alyz0mr8M2MoG1d8"
      }
   },
   "legacyEventType":"app.generic.config.app_deleted",
   "transaction":{
      "type":"WEB",
      "id":"WRzO-wWGVlYAavrUTHqwcgAABsA",
      "detail":{ }
   },
   "uuid":"49916412-d679-4285-b3e0-d740c73e4999",
   "version":"0",
   "request":{
      "ipChain":[
         {
            "ip":"12.97.85.90",
            "geographicalContext":{
               "city":"San Francisco",
               "state":null,
               "country":"United States",
               "postalCode":"94107",
               "geolocation":{
                  "lat":37.7697,
                  "lon":-122.3933
               }
            },
            "version":"V4",
            "source":null
         },
         {
            "ip":"54.235.68.72",
            "geographicalContext":{
               "city":"Ashburn",
               "state":null,
               "country":"United States",
               "postalCode":"20149",
               "geolocation":{
                  "lat":39.0481,
                  "lon":-77.4728
               }
            },
            "version":"V4",
            "source":null
         }
      ]
   },
   "target":[
      {
         "id":"0oa1alyz0mr8M2MoG1d8",
         "type":"AppInstance",
         "alternateId":"Cisco AnyConnect VPN (2)",
         "displayName":"Cisco AnyConnect VPN",
         "detailEntry":null
      }
   ]
}

Query Samples

Details of Applications Deleted

_sourceCategory = "okta" "application.lifecycle.delete"
| json field=_raw "eventType" as event_type
| where event_type = "application.lifecycle.delete"
| json field=_raw "outcome.result" as outcome_result
| json field=_raw "displayMessage" as display_message
| json field=_raw "published"as published_time
| json field=_raw "actor.displayName" as okta_user_name
| json field=_raw "actor.alternateId" as okta_user_id
| json field=_raw "actor.type" 
| json field=_raw "severity" as severity 
| json field=_raw "target[0].displayName" as app_name
| json field=_raw "target[0].type" as app_type
| json field=_raw "client.ipAddress" as client_ip
| json field=_raw "client.geographicalContext.city" as city 
| json field=_raw "client.geographicalContext.state" as state
| json field=_raw "client.geographicalContext.country" as country
| json field=_raw "client.geographicalContext.postalCode" as postal_code
| count by app_name, okta_user_id, outcome_result, display_message

Details of MFA Deactivate Event

_sourceCategory = "okta" "user.mfa.factor.deactivate"
| json field=_raw "eventType" as event_type
| where event_type = "user.mfa.factor.deactivate"
| json field=_raw "outcome.result" as outcome_result
| json field=_raw "published" as published_time
| json field=_raw "actor.displayName" as actor
| json field=_raw "actor.alternateId" as actor_id
| json field=_raw "actor.type"
| json field=_raw "severity" as severity
| json field=_raw "client.userAgent.os" as OS
| json field=_raw "client.userAgent.browser" as browser
| json field=_raw "client.device" as device
| json field=_raw "client.ipAddress" as client_ip
| json field=_raw "client.geographicalContext.country" as country 
| json field=_raw "client.geographicalContext.state" as state
| json field=_raw "client.geographicalContext.city" as city 
| json field=_raw "target[0].displayName" as okta_user_name
| json field=_raw "target[0].alternateId" as okta_user_id
| count by okta_user_id, actor, outcome_result, country, state