Okta Entity Analytics

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.

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 for standard deployments. For more details, check the Elastic Agent installation instructions.

The minimum kibana.version required is 9.5.0.

Elastic Managed integrations are only supported on Elastic Cloud Serverless and Elastic Cloud Hosted deployments. An Elastic Managed integration lets you ingest data from a cloud source while avoiding the orchestration, management, and maintenance associated with standard ingest infrastructure. Elastic runs the collector for you, so you can focus on your data instead of the infrastructure that collects it. This functionality is in beta and is subject to change. Beta features are not subject to the support SLA of official GA features.

For more information, refer to Elastic Managed integrations and the Elastic Managed integrations FAQ.

The Okta API is a public HTTPS endpoint, so no special connectivity configuration is required.

When using an Elastic Managed integration, the JWK file authentication option is not available because it relies on a file on the agent's local filesystem. Use API token or JWK JSON (inline key) authentication instead.

1. Get the required domain namespace, which should be preceded by an organization's subdomain (tenant) or configured custom domain.
2. Gather credentials for the authentication method you will use. For API token authentication, create an Okta API token following this guide. For OAuth2, create an API Services application and keys as described under OAuth2 in the Types of authentication section.

1. In Kibana, navigate to Management > Integrations.
2. In the search bar, type Okta Entity Analytics.
3. Select the Okta Entity Analytics integration and add it.
4. While adding the integration, enter your Okta domain and the fields for your authentication method. Use your domain without https:// (for example: dev-123456.okta.com). Refer to Types of authentication for API token and OAuth2 fields.
5. Save the integration.

1. In the administration dashboard for your Okta account, go to Security > API.
2. Open the Tokens tab and click Create token to create a new token.
3. Copy the token value and retain it for configuration. The token is only shown once—copy it before you leave the page.
4. Paste the token into the Okta API Token configuration option to start collecting entity analytics logs.

In this type of authentication, the following information is required:

1. Your Okta domain URL. [ Example: https://dev-123456.okta.com ]
2. Your Okta service app Client ID.
3. Your Okta service app JWK Private Key.
4. The Okta scopes that are required for OAuth2. By default they are set to okta.users.read and okta.devices.read which are the ones required to read user and device logs.

Steps to acquire Okta OAuth2 credentials:

1. Acquire an Okta dev or user account with privileges to mint tokens with the okta.* scopes.
2. Log into your Okta account, navigate to Applications on the left-hand side, click on the Create App Integration button and create an API Services application.
3. Click on the created app, note down the Client ID and select the option for Public key/Private key.
4. Generate your own Private/Public key pair in the JWK format and save it in one of the available formats.

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 send the entire list of users and devices in state. Incremental updates send only records that changed since the last sync. Changes include metadata updates, additions, and deletions. 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.

By default this integration uses minimal-state sync, which routes user and device documents directly to the user and device data streams. Existing policies are updated to use minimal-state sync on upgrade. Minimal-state sync requires Elastic Agent 9.5.0 or later; older agents use the legacy sync.

This integration provides an asset inventory, a point-in-time snapshot of which users and devices exist and their current properties. It does not provide an audit trail of who changed what, or when. If you need to track administrative changes to Okta objects, use the Okta integration's system log data stream, which collects the Okta System Log.

User documents map the Okta user to the ECS user fields as follows: user.id is the Okta user id (for example 00ub0oNGTSWTBKOLGLNR), user.name is the login (profile.login) and user.email is the primary email (profile.email). The Okta integration's System Log uses the same values for user.id and user.name. Its user.email holds the actor's login instead, because the System Log does not include the primary email. To correlate System Log events with these user documents, use user.id.

Users should ensure that full synchronization and incremental updates are not performed so frequently that they are impossible to complete within the Okta rate limits for the endpoints that are being used — for user entity analytics: /api/v1/users; and for device entity analytics: /api/v1/devices — and the volume of data that is expected from the API endpoints. Currently, Okta limits requests to /api/v1/users and /api/v1/devices to fetch at most 200 entities per request. Rate limit usage can be monitored via the Okta rate limit dashboard, and general information about Okta management rate limits is available from the Okta documentation here.

A user document:

{
  "@timestamp": "2023-07-04T09:57:19.786056-05:00",
  "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": "http://example.com/api/v1/users/userid"
      }
    }
  },
  "user": {
    "id": "userid"
  },
  "labels": {
    "identity_source": "okta-1"
  }
}

A device document:

{
    "@timestamp": "2023-07-04T09:57:19.786056-05:00",
    "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": "http://example.com/api/v1/devices/deviceid/lifecycle/activate"
            },
            "self": {
                "hints": {
                    "allow": [
                        "GET",
                        "PATCH",
                        "PUT"
                    ]
                },
                "href": "http://example.com/api/v1/devices/deviceid"
            },
            "users": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "http://example.com/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": "http://example.com/api/v1/users/userid"
                    }
                }
            }
        ]
    },
    "device": {
        "id": "deviceid",
    },
    "labels": {
        "identity_source": "okta-1"
    }
}

This is the Device dataset.

This is the User dataset.

This integration includes one or more Kibana dashboards that visualizes the data collected by the integration. The screenshots below illustrate how the ingested data is displayed.