Loading

Okta Entity Analytics
Version 2.1.0 (View all)
Compatible Kibana version(s) 8.15.0 or higher
9.0.0 or higher
Supported Serverless project types
What's this?		 Security
Observability
Subscription level
What's this?		 Basic
Level of support
What's this?		 Elastic

This Okta Entity Analytics integration allows users to securely stream User and Device Entity data to Elastic Security via the REST API. When integrated with Elastic Security, this valuable data can be leveraged within Elastic for risk-scoring scenarios (e.g., context enrichments) and detecting advanced analytics (UBA) use cases.

This module has been tested against the Core Okta API version v1.

In v2 of the integration the user and device data was split into separate data streams. The data ingested into your index will be the same but you may need to update device searches if you were using them.

Note

When you upgrade from v1 you will need to reconfigure the integration and enable it due to internal changes in the package. See Resolve conflicts in the Fleet documentation for details.

The Okta Entity Analytics integration collects two types of data: user and device.

User is used to retrieve all user logs available in an organization. See more details in the API documentation here. Device is used to retrieve all device logs available in an organization. See more details in the API documentation here.

  • Elastic Agent must be installed.
  • You can install only one Elastic Agent per host.
  • Elastic Agent is required to stream data using Entity Analytics Input and ship the data to Elastic, where the events will then be processed via the integration's ingest pipelines.

You have a few options for installing and managing an Elastic Agent:

With this approach, you install Elastic Agent and use Fleet in Kibana to define, configure, and manage your agents in a central location. We recommend using Fleet management because it makes the management and upgrade of your agents considerably easier.

With this approach, you install Elastic Agent and manually configure the agent locally on the system where it’s installed. You are responsible for managing and upgrading the agents. This approach is reserved for advanced users only.

You can run Elastic Agent inside a container, either with Fleet Server or standalone. Docker images for all versions of Elastic Agent are available from the Elastic Docker registry, and we provide deployment manifests for running on Kubernetes.

There are some minimum requirements for running Elastic Agent and for more information, refer to the link here.

The minimum kibana.version required is 8.9.0.

  • Required URL namespace, which should be preceded by an organization's subdomain (tenant) or configured custom domain.
  • Create an Okta API Token for Authentication. Follow this guide.
  1. In Kibana, go to Management > Integrations.
  2. In the "Search for integrations" search bar, type Okta Entity Analytics.
  3. Click on the "Okta Entity Analytics" integration from the search results.
  4. Click on the Add Okta Entity Analytics Integration button to add the integration.
  5. While adding the integration, add the URL and API Token that we got earlier.
  6. Save the integration by adding other necessary parameters.

The Okta provider periodically contacts the Okta API, retrieving updates for users and devices, updates its internal cache of user/device metadata, and ships the updated metadata to Elasticsearch.

Fetching and shipping updates occurs in one of two processes: full synchronizations and incremental updates. Full synchronizations will send the entire list of users and devices in state, along with write markers to indicate the start and end of the synchronization event. Incremental updates will only send data for changed users/devices during that event. Changes can come in many forms, whether it be a change to the user’s or device’s metadata, or a user or device was added or deleted. By default, full synchronizations occur every 24 hours and incremental updates occur every 15 minutes. These intervals may be customized to suit your use case.

A user document:

{
  "@timestamp": "2023-07-04T09:57:19.786056-05:00",
  "event": {
    "action": "user-discovered"
  },
  "okta": {
    "id": "userid",
    "status": "RECOVERY",
    "created": "2023-06-02T09:33:00.189752+09:30",
    "activated": "0001-01-01T00:00:00Z",
    "statusChanged": "2023-06-02T09:33:00.189752+09:30",
    "lastLogin": "2023-06-02T09:33:00.189752+09:30",
    "lastUpdated": "2023-06-02T09:33:00.189753+09:30",
    "passwordChanged": "2023-06-02T09:33:00.189753+09:30",
    "type": {
      "id": "typeid"
    },
    "profile": {
      "login": "name.surname@example.com",
      "email": "name.surname@example.com",
      "firstName": "name",
      "lastName": "surname"
    },
    "credentials": {
      "password": {},
      "provider": {
        "type": "OKTA",
        "name": "OKTA"
      }
    },
    "_links": {
      "self": {
        "href": "https://localhost/api/v1/users/userid"
      }
    }
  },
  "user": {
    "id": "userid"
  },
  "labels": {
    "identity_source": "okta-1"
  }
}

A device document:

{
    "@timestamp": "2023-07-04T09:57:19.786056-05:00",
    "event": {
        "action": "device-discovered",
    },
    "okta": {
        "created": "2019-10-02T18:03:07Z",
        "id": "deviceid",
        "lastUpdated": "2019-10-02T18:03:07Z",
        "profile": {
            "diskEncryptionType": "ALL_INTERNAL_VOLUMES",
            "displayName": "Example Device name 1",
            "platform": "WINDOWS",
            "registered": true,
            "secureHardwarePresent": false,
            "serialNumber": "XXDDRFCFRGF3M8MD6D",
            "sid": "S-1-11-111"
        },
        "resourceAlternateID": "",
        "resourceDisplayName": {
            "sensitive": false,
            "value": "Example Device name 1"
        },
        "resourceID": "deviceid",
        "resourceType": "UDDevice",
        "status": "ACTIVE",
        "_links": {
            "activate": {
                "hints": {
                    "allow": [
                        "POST"
                    ]
                },
                "href": "https://localhost/api/v1/devices/deviceid/lifecycle/activate"
            },
            "self": {
                "hints": {
                    "allow": [
                        "GET",
                        "PATCH",
                        "PUT"
                    ]
                },
                "href": "https://localhost/api/v1/devices/deviceid"
            },
            "users": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://localhost/api/v1/devices/deviceid/users"
            }
        },
        "users": [
            {
                "id": "userid",
                "status": "RECOVERY",
                "created": "2023-05-14T13:37:20Z",
                "activated": "0001-01-01T00:00:00Z",
                "statusChanged": "2023-05-15T01:50:30Z",
                "lastLogin": "2023-05-15T01:59:20Z",
                "lastUpdated": "2023-05-15T01:50:32Z",
                "passwordChanged": "2023-05-15T01:50:32Z",
                "type": {
                    "id": "typeid"
                },
                "profile": {
                    "login": "name.surname@example.com",
                    "email": "name.surname@example.com",
                    "firstName": "name",
                    "lastName": "surname"
                },
                "credentials": {
                    "password": {},
                    "provider": {
                        "type": "OKTA",
                        "name": "OKTA"
                    }
                },
                "_links": {
                    "self": {
                        "href": "https://localhost/api/v1/users/userid"
                    }
                }
            }
        ]
    },
    "device": {
        "id": "deviceid",
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

Full synchronizations will be bounded on either side by "write marker" documents.

{
    "@timestamp": "2022-11-04T09:57:19.786056-05:00",
    "event": {
        "action": "started",
        "start": "2022-11-04T09:57:19.786056-05:00"
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

This is the Device dataset.

Exported fields
Field Description Type
@timestamp Event timestamp. date
asset.category keyword
asset.costCenter keyword
asset.create_date date
asset.id keyword
asset.last_seen date
asset.last_status_change_date date
asset.last_updated date
asset.name keyword
asset.status keyword
asset.type keyword
asset.vendor keyword
data_stream.dataset Data stream dataset. constant_keyword
data_stream.namespace Data stream namespace. constant_keyword
data_stream.type Data stream type. constant_keyword
device.serial_number The unique serial number serves as a distinct identifier for each device, aiding in inventory management and device authentication. keyword
entityanalytics_okta.device._embedded embedded resources related to the device. flattened
entityanalytics_okta.device._links link relations for the device's current status. flattened
entityanalytics_okta.device.activated timestamp when transition to ACTIVE status completed. date
entityanalytics_okta.device.created timestamp when device was created. date
entityanalytics_okta.device.id unique key for device. keyword
entityanalytics_okta.device.last_login timestamp of last login. date
entityanalytics_okta.device.last_updated timestamp when device was last updated. date
entityanalytics_okta.device.password_changed timestamp when password last changed. date
entityanalytics_okta.device.profile.* keyword
entityanalytics_okta.device.profile.registered Whether the device is registered. boolean
entityanalytics_okta.device.profile.secure_hardware_present Whether the device is using secure hardware. boolean
entityanalytics_okta.device.status current status of device. keyword
entityanalytics_okta.device.status_changed timestamp when status last changed. date
entityanalytics_okta.device.transitioning_to_status target status of an in-progress asynchronous status transition. keyword
entityanalytics_okta.device.type device type that determines the schema for the device's profile. flattened
entityanalytics_okta.device.users Users associated with the device. flattened
event.dataset Event dataset. constant_keyword
event.module Event module. constant_keyword
input.type Type of filebeat input. keyword
labels.identity_source keyword
log.offset Log offset. long
user.account.activated_date date
user.account.change_date date
user.account.create_date date
user.account.password_change_date date
user.account.status.deprovisioned boolean
user.account.status.locked_out boolean
user.account.status.password_expired boolean
user.account.status.recovery boolean
user.account.status.suspended boolean
user.geo.city_name keyword
user.geo.country_iso_code keyword
user.geo.name keyword
user.geo.postal_code keyword
user.geo.region_name keyword
user.geo.timezone keyword
user.organization.name keyword
user.profile.department keyword
user.profile.first_name keyword
user.profile.id keyword
user.profile.job_title keyword
user.profile.last_name keyword
user.profile.manager keyword
user.profile.mobile_phone keyword
user.profile.other_identities keyword
user.profile.primaryPhone keyword
user.profile.secondEmail keyword
user.profile.status keyword
user.profile.type keyword

This is the User dataset.

Exported fields
Field Description Type
@timestamp Event timestamp. date
asset.category keyword
asset.costCenter keyword
asset.create_date date
asset.id keyword
asset.last_seen date
asset.last_status_change_date date
asset.last_updated date
asset.name keyword
asset.status keyword
asset.type keyword
asset.vendor keyword
data_stream.dataset Data stream dataset. constant_keyword
data_stream.namespace Data stream namespace. constant_keyword
data_stream.type Data stream type. constant_keyword
entityanalytics_okta.groups.id The ID for the group. keyword
entityanalytics_okta.groups.profile.* Group profile details. object
entityanalytics_okta.user._embedded embedded resources related to the user. flattened
entityanalytics_okta.user._links link relations for the user's current status. flattened
entityanalytics_okta.user.activated timestamp when transition to ACTIVE status completed. date
entityanalytics_okta.user.created timestamp when user was created. date
entityanalytics_okta.user.credentials.provider.name keyword
entityanalytics_okta.user.credentials.provider.type keyword
entityanalytics_okta.user.credentials.recovery_question.is_set boolean
entityanalytics_okta.user.id unique key for user. keyword
entityanalytics_okta.user.last_login timestamp of last login. date
entityanalytics_okta.user.last_updated timestamp when user was last updated. date
entityanalytics_okta.user.password_changed timestamp when password last changed. date
entityanalytics_okta.user.profile.city City or locality component of user's address (locality). keyword
entityanalytics_okta.user.profile.cost_center Name of a cost center assigned to user. keyword
entityanalytics_okta.user.profile.country_code Country name component of user's address (country). keyword
entityanalytics_okta.user.profile.department Name of user's department. keyword
entityanalytics_okta.user.profile.display_name Name of the user, suitable for display to end users. keyword
entityanalytics_okta.user.profile.division Name of user's division. keyword
entityanalytics_okta.user.profile.email Primary email address of user. keyword
entityanalytics_okta.user.profile.employee_number Organization or company assigned unique identifier for the user. keyword
entityanalytics_okta.user.profile.first_name Given name of the user (givenName). keyword
entityanalytics_okta.user.profile.honorific.prefix Honorific prefix(es) of the user, or title in most Western languages. keyword
entityanalytics_okta.user.profile.honorific.suffix Honorific suffix(es) of the user. keyword
entityanalytics_okta.user.profile.last_name Family name of the user (familyName). keyword
entityanalytics_okta.user.profile.locale User's default location for purposes of localizing items such as currency, date time format, numerical representations, and so on. keyword
entityanalytics_okta.user.profile.login Unique identifier for the user (username). keyword
entityanalytics_okta.user.profile.manager.id id of a user's manager. keyword
entityanalytics_okta.user.profile.manager.name displayName of the user's manager. keyword
entityanalytics_okta.user.profile.middle_name Middle name(s) of the user. keyword
entityanalytics_okta.user.profile.mobile_phone Mobile phone number of user. keyword
entityanalytics_okta.user.profile.nick_name Casual way to address the user in real life. keyword
entityanalytics_okta.user.profile.organization Name of user's organization. keyword
entityanalytics_okta.user.profile.postal_address Mailing address component of user's address. keyword
entityanalytics_okta.user.profile.preferred_language User's preferred written or spoken languages. keyword
entityanalytics_okta.user.profile.primary_phone Primary phone number of user such as home number. keyword
entityanalytics_okta.user.profile.second_email Secondary email address of user typically used for account recovery. keyword
entityanalytics_okta.user.profile.state State or region component of user's address (region). keyword
entityanalytics_okta.user.profile.street_address Full street address component of user's address. keyword
entityanalytics_okta.user.profile.timezone User's time zone. keyword
entityanalytics_okta.user.profile.title User's title, such as "Vice President". keyword
entityanalytics_okta.user.profile.url URL of user's online profile (for example: a web page). keyword
entityanalytics_okta.user.profile.user_type Used to describe the organization to user relationship such as "Employee" or "Contractor". keyword
entityanalytics_okta.user.profile.zip_code ZIP code or postal code component of user's address (postalCode). keyword
entityanalytics_okta.user.status current status of user. keyword
entityanalytics_okta.user.status_changed timestamp when status last changed. date
entityanalytics_okta.user.transitioning_to_status target status of an in-progress asynchronous status transition. keyword
entityanalytics_okta.user.type user type that determines the schema for the user's profile. flattened
event.dataset Event dataset. constant_keyword
event.module Event module. constant_keyword
input.type Type of filebeat input. keyword
labels.identity_source keyword
log.offset Log offset. long
user.account.activated_date date
user.account.change_date date
user.account.create_date date
user.account.password_change_date date
user.account.status.deprovisioned boolean
user.account.status.locked_out boolean
user.account.status.password_expired boolean
user.account.status.recovery boolean
user.account.status.suspended boolean
user.geo.city_name keyword
user.geo.country_iso_code keyword
user.geo.name keyword
user.geo.postal_code keyword
user.geo.region_name keyword
user.geo.timezone keyword
user.organization.name keyword
user.profile.department keyword
user.profile.first_name keyword
user.profile.id keyword
user.profile.job_title keyword
user.profile.last_name keyword
user.profile.manager keyword
user.profile.mobile_phone keyword
user.profile.other_identities keyword
user.profile.primaryPhone keyword
user.profile.secondEmail keyword
user.profile.status keyword
user.profile.type keyword
Changelog
Version Details Kibana version(s)
2.1.0 Enhancement (View pull request)
Update Kibana constraint to support 9.0.0.		 8.15.0 or higher
9.0.0 or higher
2.0.0 Enhancement (View pull request)
Split user and device data into their own data streams.		 8.15.0 or higher
1.8.1 Bug fix (View pull request)
Updated SSL description to be uniform and to include links to documentation.		 8.15.0 or higher
1.8.0 Enhancement (View pull request)
Add "event.original" field when "preserve_original_event" is set.		 8.15.0 or higher
1.7.0 Enhancement (View pull request)
Add "preserve_original_event" tag to documents with event.kind manually set to "pipeline_error".		 8.15.0 or higher
1.6.0 Enhancement (View pull request)
Add "preserve_original_event" tag to documents with event.kind set to "pipeline_error".		 8.15.0 or higher
1.5.1 Bug fix (View pull request)
Don't leak collection implementation details.		 8.15.0 or higher
1.5.0 Enhancement (View pull request)
Add support for group membership mapping.

Enhancement (View pull request)
Add system testing support for group membership.		 8.15.0 or higher
1.4.0 Enhancement (View pull request)
Add support for request trace logging.		 8.15.0 or higher
1.3.0 Enhancement (View pull request)
Record whether a user's credentials include a recovery question.		 8.13.0 or higher
1.2.0 Enhancement (View pull request)
Removed import_mappings. Update the kibana constraint to ^8.13.0. Modified the field definitions to remove ECS fields made redundant by the ecs@mappings component template.		 8.13.0 or higher
1.1.0 Enhancement (View pull request)
Set sensitive values as secret.		 8.12.0 or higher
1.0.1 Enhancement (View pull request)
Changed owners		 8.9.0 or higher
1.0.0 Enhancement (View pull request)
Release package as GA.		 8.9.0 or higher
0.8.0 Enhancement (View pull request)
Allow dataset selection.		 —
0.7.0 Enhancement (View pull request)
ECS version updated to 8.11.0.		 —
0.6.1 Bug fix (View pull request)
Fix mapping of group fields		 —
0.6.0 Enhancement (View pull request)
ECS version updated to 8.10.0.		 —
0.5.0 Enhancement (View pull request)
The format_version in the package manifest changed from 2.11.0 to 3.0.0. Removed dotted YAML keys from package manifest. Added 'owner.type: elastic' to package manifest.		 —
0.4.0 Enhancement (View pull request)
Add tags.yml file so that integration's dashboards and saved searches are tagged with "Security Solution" and displayed in the Security Solution UI.		 —
0.3.0 Enhancement (View pull request)
Add user.geo., user.organization., and asset categorization mappings.		 —
0.2.0 Enhancement (View pull request)
Update package to ECS 8.9.0.		 —
0.1.0 Enhancement (View pull request)
Initial Release.		 —