[Okta] Add Missing Event Categories

[terrancedejesus]

Summary

In the Okta integration, specifically for the elasticsearch ingestion pipeline we are missing some event.category mappings based on available Event Types documented by Okta. This directly affects any OOTB prebuilt SIEM rules that use EQL which leads with event categories such as authentication.

This brought up by a community member for attempting to resolve some false-negative logic in an OOTB rule that relies on Okta system logs. Specifically, user.authentication.auth_via_mfa should be in the authentication event category mapping, but is not. As a result, there is no defined event.category in the events.

Solution

• user.authentication.auth_via_mfa should be added to the authentication category.
• We should review the event types and get these mapped accordingly for event.category.

Okta is a relatively popular integration amongst our users and this update would be a good quality of life change. Additionally, it allows our EQL-based OOTB prebuilt SIEM rules to not rely on any which can effect performance from the detection engine.

Example Event:

{
  "_index": ".ds-logs-okta.system-default-2025.08.15-000006",
  "_id": "35f5a302-8ccd-11f0-8fd9-cf64cb28a413",
  "_version": 1,
  "_source": {
    "@timestamp": "2025-09-08T16:02:24.996Z",
    "agent": {
      "ephemeral_id": "da73596f-da11-4fe1-b7df-897ffea9233a",
      "id": "22b75296-5bb5-4bc0-9918-e87b4902269d",
      "name": "ip-172-31-11-200",
      "type": "filebeat",
      "version": "8.17.3"
    },
    "client": {
      "as": {
        "organization": {
          "name": "mctv"
        }
      },
      "domain": "sssnet.com",
      "geo": {
        "city_name": "Massillon",
        "country_name": "United States",
        "location": {
          "lat": REDACTED,
          "lon": REDACTED
        },
        "region_name": "Ohio"
      },
      "ip": "REDACTED",
      "user": {
        "full_name": "Elastic TRADE",
        "id": "00ujjn0nzx9RSYZ9M5d7",
        "name": "REDACTED"
      }
    },
    "cloud": {
      "account": {
        "id": "891377031307"
      },
      "availability_zone": "us-east-2a",
      "image": {
        "id": "ami-0cb91c7de36eed2cb"
      },
      "instance": {
        "id": "i-06a549dcaba759e6e"
      },
      "machine": {
        "type": "t2.small"
      },
      "provider": "aws",
      "region": "us-east-2",
      "service": {
        "name": "EC2"
      }
    },
    "data_stream": {
      "dataset": "okta.system",
      "namespace": "default",
      "type": "logs"
    },
    "ecs": {
      "version": "8.11.0"
    },
    "elastic_agent": {
      "id": "22b75296-5bb5-4bc0-9918-e87b4902269d",
      "snapshot": false,
      "version": "8.17.3"
    },
    "event": {
      "action": "user.authentication.auth_via_mfa",
      "agent_id_status": "verified",
      "created": "2025-09-08T16:03:52.288Z",
      "dataset": "okta.system",
      "id": "35f5a302-8ccd-11f0-8fd9-cf64cb28a413",
      "ingested": "2025-09-08T16:04:02Z",
      "kind": "event",
      "outcome": "success"
    },
    "input": {
      "type": "httpjson"
    },
    "okta": {
      "actor": {
        "alternate_id": "REDACTED",
        "display_name": "Elastic TRADE",
        "id": "00ujjn0nzx9RSYZ9M5d7",
        "type": "User"
      },
      "authentication_context": {
        "authentication_provider": "FACTOR_PROVIDER",
        "authentication_step": 0,
        "credential_provider": "OKTA_CREDENTIAL_PROVIDER",
        "external_session_id": "idxXmXb3FPqRbWDC84_x5JwrA"
      },
      "client": {
        "device": "Computer",
        "ip": "REDACTED",
        "user_agent": {
          "browser": "CHROME",
          "os": "Mac OS 15.6.1 (Sequoia)",
          "raw_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
        },
        "zone": "null"
      },
      "debug_context": {
        "debug_data": {
          "REDACTED",
          },
          "request_id": "156066e2db2a130acac471276638450b",
          "request_uri": "/idp/idx/identify",
          "threat_suspected": "false",
          "url": "/idp/idx/identify?"
        }
      },
      "display_message": "Authentication of user via MFA",
      "event_type": "user.authentication.auth_via_mfa",
      "outcome": {
        "result": "SUCCESS"
      },
      "request": {
        "ip_chain": [
          {
            "geographical_context": {
              "country": "United States",
              "city": "Massillon",
              "state": "Ohio",
              "postal_code": "44646",
              "geolocation": {
                "lon": REDACTED,
                "lat": REDACTED
              }
            },
            "ip": "REDACTED",
            "version": "V4"
          }
        ]
      },
      "security_context": {
        "as": {
          "number": 12097,
          "organization": {
            "name": "mctv"
          }
        },
        "domain": "sssnet.com",
        "is_proxy": false,
        "isp": "massillon cable communications"
      },
      "target": [
        {
          "id": "00ujjn0nzx9RSYZ9M5d7",
          "type": "User",
          "display_name": "Elastic TRADE",
          "alternate_id": "REDACTED"
        },
        {
          "id": "lae2ebdv2v1WQjwP75d7",
          "detailEntry": {
            "methodTypeUsed": "Password",
            "methodUsedVerifiedProperties": "[USER_PRESENCE]"
          },
          "type": "AuthenticatorEnrollment",
          "display_name": "Password",
          "alternate_id": "unknown"
        }
      ],
      "transaction": {
        "id": "156066e2db2a130acac471276638450b",
        "type": "WEB"
      },
      "uuid": "REDACTED"
    },
    "related": {
      "ip": [
        "REDACTED"
      ],
      "user": [
        "Elastic TRADE",
        "tradebot"
      ]
    },
    "source": {
      "as": {
        "number": 12097,
        "organization": {
          "name": "MASSCOM"
        }
      },
      "domain": "sssnet.com",
      "geo": {
        "city_name": "Massillon",
        "continent_name": "North America",
        "country_iso_code": "US",
        "country_name": "United States",
        "location": {
          "lat": REDACTED,
          "lon": REDACTED
        },
        "region_iso_code": "US-OH",
        "region_name": "Ohio"
      },
      "ip": "REDACTED",
      "user": {
        "full_name": "Elastic TRADE",
        "id": "REDACTED",
        "name": "REDACTED"
      }
    },
    "tags": [
      "forwarded",
      "okta-system"
    ],
    "user": {
      "full_name": "Elastic TRADE",
      "name": "REDACTED",
      "target": {
        "full_name": "Elastic TRADE",
        "id": "REDACTED"
      }
    },
    "user_agent": {
      "device": {
        "name": "Mac"
      },
      "name": "Chrome",
      "original": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
      "os": {
        "full": "Mac OS X 10.15.7",
        "name": "Mac OS X",
        "version": "10.15.7"
      },
      "version": "140.0.0.0"
    }
  },
  "fields": {
    "okta.client.device": [
      "Computer"
    ],
    "elastic_agent.version": [
      "8.17.3"
    ],
    "user_agent.original.text": [
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
    ],
    "okta.client.ip": [
      "REDACTED"
    ],
    "okta.client.user_agent.os": [
      "Mac OS 15.6.1 (Sequoia)"
    ],
    "okta.security_context.as.number": [
      12097
    ],
    "source.user.name.text": [
      "tradebot"
    ],
    "agent.name.text": [
      "REDACTED"
    ],
    "source.geo.region_name": [
      "Ohio"
    ],
    "user.full_name.text": [
      "Elastic TRADE"
    ],
    "cloud.service.name.text": [
      "EC2"
    ],
    "user.target.full_name": [
      "Elastic TRADE"
    ],
    "source.ip": [
      "REDACTED"
    ],
    "agent.name": [
      "ip-172-31-11-200"
    ],
    "event.agent_id_status": [
      "verified"
    ],
    "event.outcome": [
      "success"
    ],
    "source.geo.city_name": [
      "Massillon"
    ],
    "user_agent.original": [
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
    ],
    "okta.uuid": [
      "REDACTED"
    ],
    "cloud.region": [
      "us-east-2"
    ],
    "source.user.full_name.text": [
      "Elastic TRADE"
    ],
    "input.type": [
      "httpjson"
    ],
    "okta.authentication_context.authentication_step": [
      0
    ],
    "related.user": [
      "Elastic TRADE",
      "REDACTED"
    ],
    "tags": [
      "forwarded",
      "okta-system"
    ],
    "okta.client.zone": [
      "null"
    ],
    "cloud.machine.type": [
      "t2.small"
    ],
    "cloud.provider": [
      "aws"
    ],
    "agent.id": [
      "22b75296-5bb5-4bc0-9918-e87b4902269d"
    ],
    "client.user.name": [
      "REDACTED"
    ],
    "source.as.number": [
      12097
    ],
    "okta.target.type": [
      "User",
      "AuthenticatorEnrollment"
    ],
    "okta.authentication_context.external_session_id": [
      "REDACTED"
    ],
    "client.user.name.text": [
      "tradebot"
    ],
    "user_agent.os.full": [
      "Mac OS X 10.15.7"
    ],
    "okta.authentication_context.credential_provider": [
      "OKTA_CREDENTIAL_PROVIDER"
    ],
    "user.name": [
      "REDACTED"
    ],
    "okta.debug_context.debug_data.device_fingerprint": [
      "REDACTED"
    ],
    "source.domain": [
      "sssnet.com"
    ],
    "user_agent.os.name": [
      "Mac OS X"
    ],
    "cloud.instance.id": [
      "REDACTED"
    ],
    "okta.security_context.is_proxy": [
      false
    ],
    "agent.type": [
      "filebeat"
    ],
    "client.geo.region_name": [
      "Ohio"
    ],
    "okta.actor.type": [
      "User"
    ],
    "related.ip": [
      "REDACTED"
    ],
    "elastic_agent.snapshot": [
      false
    ],
    "user.target.full_name.text": [
      "Elastic TRADE"
    ],
    "okta.client.user_agent.raw_user_agent": [
      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
    ],
    "client.domain": [
      "sssnet.com"
    ],
    "elastic_agent.id": [
      "22b75296-5bb5-4bc0-9918-e87b4902269d"
    ],
    "okta.debug_context.debug_data.url": [
      "/idp/idx/identify?"
    ],
    "okta.actor.display_name": [
      "Elastic TRADE"
    ],
    "okta.debug_context.debug_data.factor": [
      "PASSWORD_AS_FACTOR"
    ],
    "cloud.image.id": [
      "ami-0cb91c7de36eed2cb"
    ],
    "event.action": [
      "user.authentication.auth_via_mfa"
    ],
    "event.ingested": [
      "2025-09-08T16:04:02.000Z"
    ],
    "@timestamp": [
      "2025-09-08T16:02:24.996Z"
    ],
    "okta.target.detailEntry.methodUsedVerifiedProperties": [
      "[USER_PRESENCE]"
    ],
    "user_agent.name.text": [
      "Chrome"
    ],
    "cloud.account.id": [
      "891377031307"
    ],
    "data_stream.dataset": [
      "okta.system"
    ],
    "agent.ephemeral_id": [
      "da73596f-da11-4fe1-b7df-897ffea9233a"
    ],
    "event.id": [
      "35f5a302-8ccd-11f0-8fd9-cf64cb28a413"
    ],
    "user_agent.device.name": [
      "Mac"
    ],
    "user.name.text": [
      "tradebot"
    ],
    "okta.outcome.result": [
      "SUCCESS"
    ],
    "okta.security_context.isp": [
      "massillon cable communications"
    ],
    "user_agent.os.version": [
      "10.15.7"
    ],
    "cloud.availability_zone": [
      "us-east-2a"
    ],
    "user.target.id": [
      "00ujjn0nzx9RSYZ9M5d7"
    ],
    "okta.debug_context.debug_data.request_uri": [
      "/idp/idx/identify"
    ],
    "okta.display_message": [
      "Authentication of user via MFA"
    ],
    "client.user.full_name": [
      "Elastic TRADE"
    ],
    "okta.target.id": [
      "REDACTED",
      "REDACTED"
    ],
    "client.as.organization.name": [
      "mctv"
    ],
    "okta.actor.alternate_id": [
      "REDACTED"
    ],
    "user_agent.version": [
      "140.0.0.0"
    ],
    "client.geo.country_name": [
      "United States"
    ],
    "source.geo.region_iso_code": [
      "US-OH"
    ],
    "client.as.organization.name.text": [
      "mctv"
    ],
    "event.kind": [
      "event"
    ],
    "okta.debug_context.debug_data.flattened": [
      {
        "traceId": "307a59cb-0dc3-43f9-974b-ed7b51140201",
        "authnRequestId": "REDACTED",
        "deviceFingerprint": "REDACTED",
        "requestId": "156066e2db2a130acac471276638450b",
        "authenticatorMethodChallengeTime": "2025-09-08T16:02:21.235Z",
        "dtHash": "REDACTED",
        "requestUri": "/idp/idx/identify",
        "threatSuspected": "false",
        "factor": "PASSWORD_AS_FACTOR",
        "factorIntent": "AUTHENTICATION",
        "url": "/idp/idx/identify?"
      }
    ],
    "client.user.id": [
      "REDACTED"
    ],
    "okta.security_context.domain": [
      "sssnet.com"
    ],
    "client.ip": [
      "REDACTED"
    ],
    "user_agent.name": [
      "Chrome"
    ],
    "okta.client.user_agent.browser": [
      "CHROME"
    ],
    "data_stream.type": [
      "logs"
    ],
    "okta.request.ip_chain": [
      {
        "geographical_context": {
          "country": "United States",
          "city": "Massillon",
          "state": "Ohio",
          "postal_code": "44646",
          "geolocation": {
            "lon": REDACTED,
            "lat": REDACTED
          }
        },
        "ip": "REDACTED",
        "version": "V4"
      }
    ],
    "okta.debug_context.debug_data.dt_hash": [
      "REDACTED"
    ],
    "okta.transaction.id": [
      "156066e2db2a130acac471276638450b"
    ],
    "cloud.service.name": [
      "EC2"
    ],
    "ecs.version": [
      "8.11.0"
    ],
    "event.created": [
      "2025-09-08T16:03:52.288Z"
    ],
    "okta.target.display_name": [
      "Elastic TRADE",
      "Password"
    ],
    "user.full_name": [
      "Elastic TRADE"
    ],
    "agent.version": [
      "8.17.3"
    ],
    "source.user.name": [
      "REDACTED"
    ],
    "okta.debug_context.debug_data.request_id": [
      "REDACTED"
    ],
    "okta.target.detailEntry.methodTypeUsed": [
      "Password"
    ],
    "source.user.full_name": [
      "Elastic TRADE"
    ],
    "source.geo.location": [
      {
        "coordinates": [
          REDACTED,
          REDACTED
        ],
        "type": "Point"
      }
    ],
    "okta.target.alternate_id": [
      "REDACTED",
      "unknown"
    ],
    "okta.event_type": [
      "user.authentication.auth_via_mfa"
    ],
    "user_agent.os.name.text": [
      "Mac OS X"
    ],
    "okta.debug_context.debug_data.threat_suspected": [
      "false"
    ],
    "okta.transaction.type": [
      "WEB"
    ],
    "client.geo.location": [
      {
        "coordinates": [
          REDACTED,
          REDACTED
        ],
        "type": "Point"
      }
    ],
    "event.module": [
      "okta"
    ],
    "okta.actor.id": [
      "00ujjn0nzx9RSYZ9M5d7"
    ],
    "source.geo.country_iso_code": [
      "US"
    ],
    "source.user.id": [
      "REDACTED"
    ],
    "okta.authentication_context.authentication_provider": [
      "FACTOR_PROVIDER"
    ],
    "client.geo.city_name": [
      "Massillon"
    ],
    "source.as.organization.name.text": [
      "MASSCOM"
    ],
    "data_stream.namespace": [
      "default"
    ],
    "source.as.organization.name": [
      "MASSCOM"
    ],
    "source.geo.continent_name": [
      "North America"
    ],
    "user_agent.device.name.text": [
      "Mac"
    ],
    "client.user.full_name.text": [
      "Elastic TRADE"
    ],
    "user_agent.os.full.text": [
      "Mac OS X 10.15.7"
    ],
    "okta.security_context.as.organization.name": [
      "mctv"
    ],
    "source.geo.country_name": [
      "United States"
    ],
    "event.dataset": [
      "okta.system"
    ]
  }
}

[elasticmachine]

Pinging @elastic/security-service-integrations (Team:Security-Service Integrations)

[efd6]

@terrancedejesus Can you provide the preferred mappings between the Okta event types and event.category?

[terrancedejesus]

@efd6 - Certainly, I will prepare this for today.

[terrancedejesus]

@efd6 - I started with all Okta events as listed in the link I originally referenced. Then mapped the event categories to them. Cross-checked these with the existing mappings, of these core.concurrency.org.limit.violation and security.request.blocked should be changed. I checked to confirm we do not have any EQL-based rules that rely on the category from these events since they would be changed. The rest are simply not mapped. There is a total of 991 events. Here is some stat distribution with updated categories and types.

  configuration         455 events ( 45.9%)
  iam                   272 events ( 27.4%)
  authentication        197 events ( 19.9%)
  threat                 23 events (  2.3%)
  host                   20 events (  2.0%)
  session                16 events (  1.6%)
  network                 8 events (  0.8%)

  info                  264 events ( 26.6%)
  user                  240 events ( 24.2%)
  creation              180 events ( 18.2%)
  change                154 events ( 15.5%)
  deletion              152 events ( 15.3%)
  error                 141 events ( 14.2%)
  protocol              101 events ( 10.2%)
  group                  95 events (  9.6%)
  end                    82 events (  8.3%)
  allowed                77 events (  7.8%)
  denied                 75 events (  7.6%)
  start                  73 events (  7.4%)
  access                 63 events (  6.4%)
  admin                  33 events (  3.3%)
  connection             23 events (  2.3%)
  installation           19 events (  1.9%)
  indicator              10 events (  1.0%)

okta_event_categories_with_ecs.json

[efd6]

Is the mapping in the JSON? such that it would be something like, e.g. Okta workflows.user.flow.execution.cancel to "event.category":["iam"] and "event.type":["deletion","user"]. There are nearly a thousand mappings in that (this ends up being 4359 lines of pipeline). Do you want all of them handled?

Expand to see generator

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"
	"path/filepath"

	// For okta_event_categories_with_ecs.json.
	_ "embed"

	. "github.com/efd6/dispear"
)

//go:embed okta_event_categories_with_ecs.json
var data []byte

func main() {
	var mapping []struct {
		Event    string   `json:"event"`
		Category string   `json:"ecs_category"`
		Type     []string `json:"ecs_type"`
		Tags     []string `json:"tags"`
	}
	err := json.Unmarshal(data, &mapping)
	if err != nil {
		log.Fatal(err)
	}
	params := make(map[string]any)
	for _, m := range mapping {
		d := make(map[string]any)
		if len(m.Type) != 0 {
			d["type"] = m.Type
		}
		if len(m.Category) != 0 {
			d["category"] = []string{m.Category}
		}
		if len(m.Tags) != 0 {
			d["tags"] = m.Tags
		}
		if len(d) == 0 {
			continue
		}
		params[m.Event] = d
	}

	DESCRIPTION(fmt.Sprintf(`Code generated by %s; DO NOT EDIT.

Okta event type mapping to ECS event type and category.`, filepath.Base(os.Args[0])))
	ON_FAILURE(
		SET("event.pipeline").VALUE("pipeline_error"),
		APPEND("event.message", errorFormat),
		APPEND("tags", "preserve_original_event").
			ALLOW_DUPLICATES(false),
	)

	SCRIPT().
		DESCRIPTION("Map Okta event types to event.type and event.category.").
		IF(`ctx.okta?.event_type != null`).
		PARAMS(params).
		SOURCE(`
			def addUnique(List dst, List src) {
			  if (src.length == 0) {
			    return dst;
			  }
			  HashSet s = new HashSet(dst ?: []);
			  s.addAll(src);
			  return new ArrayList(s);
			}
			def p = params[ctx.okta.event_type];
			ctx.event.type = addUnique(ctx.event.type, p.type);
			ctx.event.category = addUnique(ctx.event.category, p.category);
			ctx.tags = addUnique(ctx.tags, p.tags);
		`)

	Generate()
}

const errorFormat = "Processor '{{{ _ingest.on_failure_processor_type }}}' {{{#_ingest.on_failure_processor_tag}}}with tag '{{{ _ingest.on_failure_processor_tag }}}' {{{/_ingest.on_failure_processor_tag}}}failed with message '{{{ _ingest.on_failure_message }}}'"

[terrancedejesus]

@efd6

Is the mapping in the JSON? such that it would be something like, e.g. Okta workflows.user.flow.execution.cancel to "event.category":["iam"] and "event.type":["deletion","user"].

Yes, while doing event category I added event type as well.

There are nearly a thousand mappings in that (this ends up being 4359 lines of pipeline). Do you want all of them handled?

That is a great question, I'd be interested in how we handle larger ECS mappings for other integrations and what is feasible in doing so or your recommendation? Okta has roughly 991 unique events, I'd imagine this is small in comparison to other data streams so is there a recommended route for handling these?

[andrewkroh]

At some table size we could switch to an enrich processor, but currently there is no infrastructure in Fleet building up the enrich index.

With 1024 event types I still think we are in the range that is fine for a script params map. For maintenance purposes we might want to isolate the table lookup to its own pipeline so that it is easier to regenerate and does not bloat the existing default/core pipeline.

[terrancedejesus]

@andrewkroh - Thanks for the insight. The enrich processor seems like a great candidate for some of the entity enrichments. Keeping in mind of course anything we rely on for prebuilt rules is typically OOTB default dependent with some caveats.

With 1024 event types I still think we are in the range that is fine for a script params map. For maintenance purposes we might want to isolate the table lookup to its own pipeline so that it is easier to regenerate and does not bloat the existing default/core pipeline.

Great to hear. With the mappings done, is there anything else for me to supply for this?