x-pack/filebeat/input/entityanalytics/provider/okta: add device handling

WIP: needs validation against real API.
elastic · Aug 8, 2023 · 3512daf · 3512daf
1 parent b60c9c6
commit 3512daf
Show file tree

Hide file tree

Showing 7 changed files with 520 additions and 79 deletions.
diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc
@@ -256,6 +256,7 @@ automatic splitting at root level, if root level element is an array. {pull}3415
 - Add support for localstack based input integration testing {pull}35727[35727]
 - Allow parsing bytes in and bytes out as long integer in CEF processor. {issue}36100[36100] {pull}36108[36108]
 - Add support for registered owners and users to AzureAD entity analytics provider. {pull}36092[36092]
+- Add device handling to Okta input package for entity analytics. {pull}36049[36049]
 
 *Auditbeat*
 

diff --git a/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc b/x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc
@@ -308,8 +308,8 @@ Override the default authentication scopes. Only change if directed to do so.
 [id="provider-okta"]
 ==== Okta User Identities (`okta`)
 
-The `okta` provider allows the input to retrieve users from the Okta user
-API.
+The `okta` provider allows the input to retrieve users and devices from the
+Okta user API.
 
 [float]
 ==== Setup
@@ -322,30 +322,34 @@ this to configure the provider. Note that the token will not be presented
 again, so it must be copied now. This value will use given to the provider
 via the `okta_token` configuration field.
 
+Devices API access needs to be activated by Okta support.
+
 [float]
 ==== How It Works
 
 [float]
 ===== Overview
 
 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.
+users and devices, updates its internal cache of user metadata, and ships
+updated user/device 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.
+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 and devices during that event. Changes
+on a user or device can come in many forms, whether it be a change to the
+user's metadata, or a user was added or deleted.
 
 [float]
 ===== API Interactions
 
-The provider periodically retrieves changes to user metadata from the
-Okta User API. This is done through calls to:
+The provider periodically retrieves changes to user/device metadata from the
+Okta User and Device APIs. This is done through calls to:
 
 - https://developer.okta.com/docs/reference/api/users/#list-users[/api/v1/users]
+- https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/#tag/Device/operation/listDevices[/api/v1/devices]
 
 Updates are tracked by the provider by retaining a record of the time of the last
 noted update in the returned user list. During provider updates the Okta provider
@@ -355,10 +359,10 @@ since the provider's recorded last update.
 [float]
 ===== Sending User Metadata to Elasticsearch
 
-During a full synchronization, all users stored in state will be sent to the
-output, while incremental updates will only send users which have been updated.
-Full synchronizations will be bounded on either side by write marker documents,
-which will look something like this:
+During a full synchronization, all users/devices stored in state will be sent
+to the output, while incremental updates will only send users and devices
+that have been updated. Full synchronizations will be bounded on either side
+by write marker documents, which will look something like this:
 
 ["source","json",subs="attributes"]
 ----
@@ -425,6 +429,110 @@ Example user document:
 }
 ----
 
+Device documents will show the current state of the device, including any
+associated users.
+
+Example device document:
+
+["source","json",subs="attributes"]
+----
+{
+    "@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"
+    }
+}
+----
+
 [float]
 ==== Configuration
 
@@ -455,6 +563,13 @@ The Okta domain. Field is required.
 
 The Okta secret token, used for authentication. Field is required.
 
+[float]
+===== `collect_device_details`
+
+Whether the input should collect device and device-associated user details
+from the Okta API. Device details must be activated on the Okta account for
+this option.
+
 [float]
 ===== `sync_interval`
 

diff --git a/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go b/x-pack/filebeat/input/entityanalytics/provider/okta/conf.go
@@ -41,6 +41,11 @@ type conf struct {
 	OktaDomain string `config:"okta_domain" validate:"required"`
 	OktaToken  string `config:"okta_token" validate:"required"`
 
+	// WantDevices indicates that device details
+	// should be collected. This is optional as
+	// the devices API is not necessarily activated.
+	WantDevices bool `config:"collect_device_details"`
+
 	// SyncInterval is the time between full
 	// synchronisation operations.
 	SyncInterval time.Duration `config:"sync_interval"`