« Okta Integration Oracle »
Elastic Docs ›Elastic integrations ›Okta

Okta Entity Analytics

edit

Okta Entity Analytics

edit

Version

1.7.0 (View all)

Compatible Kibana version(s)

8.15.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 Entities 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.

Compatibility

edit

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

Data streams

edit

The Okta Entity Analytics integration collects one type of data: user.

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

Requirements

edit
  • 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.
Installing and managing an Elastic Agent:
edit

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

Install a Fleet-managed Elastic Agent (recommended):
edit

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.

Install Elastic Agent in standalone mode (advanced users):
edit

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.

Install Elastic Agent in a containerized environment:
edit

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.

Setup

edit
To collect data from Okta, follow the below steps:
edit
  • 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.
Enabling the integration in Elastic:
edit
  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.

Usage

edit

The Okta provider periodically contacts the Okta API, retrieving updates for users, updates its internal cache of user metadata, and ships updated user 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 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 during that event. Changes on a user can come in many forms, whether it be a change to the user’s metadata, or a user 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.

Sample Events

edit

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"
  }
}

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"
    }
}

Logs reference

edit
User
edit

This is the User dataset.

Example

An example event for user looks as following:

{
    "@timestamp": "2023-08-11T07:01:21.235Z",
    "agent": {
        "ephemeral_id": "dbb88a7d-16aa-44e4-8bef-c707be5ac5e2",
        "id": "28086f58-96fe-486b-9ef2-4ca0bd13a4e5",
        "name": "docker-fleet-agent",
        "type": "filebeat",
        "version": "8.9.0"
    },
    "asset": {
        "category": "entity",
        "create_date": "2013-06-24T16:39:18.000Z",
        "id": "00ub0oNGTSWTBKOLGLNR",
        "last_seen": "2013-06-24T17:39:19.000Z",
        "last_status_change_date": "2013-06-24T16:39:19.000Z",
        "last_updated": "2013-07-02T21:36:25.344Z",
        "status": "ACTIVE",
        "type": "okta_user",
        "vendor": "OKTA"
    },
    "data_stream": {
        "dataset": "entityanalytics_okta.user",
        "namespace": "ep",
        "type": "logs"
    },
    "ecs": {
        "version": "8.11.0"
    },
    "elastic_agent": {
        "id": "28086f58-96fe-486b-9ef2-4ca0bd13a4e5",
        "snapshot": false,
        "version": "8.9.0"
    },
    "entityanalytics_okta": {
        "user": {
            "activated": "2013-06-24T16:39:19.000Z",
            "created": "2013-06-24T16:39:18.000Z",
            "credentials": {
                "provider": {
                    "name": "OKTA",
                    "type": "OKTA"
                }
            },
            "id": "00ub0oNGTSWTBKOLGLNR",
            "last_login": "2013-06-24T17:39:19.000Z",
            "last_updated": "2013-07-02T21:36:25.344Z",
            "password_changed": "2013-07-02T21:36:25.344Z",
            "profile": {
                "email": "isaac.brock@example.com",
                "first_name": "Isaac",
                "last_name": "Brock",
                "login": "isaac.brock@example.com",
                "mobile_phone": "555-415-1337"
            },
            "status": "ACTIVE",
            "status_changed": "2013-06-24T16:39:19.000Z"
        }
    },
    "event": {
        "agent_id_status": "verified",
        "category": [
            "iam"
        ],
        "dataset": "entityanalytics_okta.user",
        "ingested": "2023-08-11T07:01:22Z",
        "kind": "asset",
        "type": [
            "user",
            "info"
        ]
    },
    "input": {
        "type": "entity-analytics"
    },
    "labels": {
        "identity_source": "entity-analytics-entityanalytics_okta.user-418d01f7-61b7-4df5-8d71-9e0ce541334e"
    },
    "related": {
        "user": [
            "00ub0oNGTSWTBKOLGLNR",
            "isaac.brock@example.com",
            "Isaac",
            "Brock"
        ]
    },
    "tags": [
        "preserve_duplicate_custom_fields",
        "forwarded",
        "entityanalytics_okta-user"
    ],
    "user": {
        "account": {
            "activated_date": "2013-06-24T16:39:19.000Z",
            "change_date": "2013-06-24T16:39:19.000Z",
            "create_date": "2013-06-24T16:39:18.000Z",
            "password_change_date": "2013-07-02T21:36:25.344Z",
            "status": {
                "deprovisioned": false,
                "locked_out": false,
                "password_expired": false,
                "recovery": false,
                "suspended": false
            }
        },
        "email": "isaac.brock@example.com",
        "id": "00ub0oNGTSWTBKOLGLNR",
        "name": "isaac.brock@example.com",
        "profile": {
            "first_name": "Isaac",
            "last_name": "Brock",
            "mobile_phone": "555-415-1337",
            "status": "ACTIVE"
        }
    }
}
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

edit
Changelog
Version Details Kibana version(s)

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.

—
« Okta Integration Oracle »