Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Aug 14, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.next.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ automatic splitting at root level, if root level element is an array. {pull}3415
- Add support for registered owners and users to AzureAD entity analytics provider. {pull}36092[36092]
- Added support for Okta OAuth2 provider in the httpjson input. {pull}36273[36273]
- Add support of the interval parameter in Salesforce setupaudittrail-rest fileset. {issue}35917[35917] {pull}35938[35938]
- Add device handling to Okta input package for entity analytics. {pull}36049[36049]

*Auditbeat*

Expand Down
145 changes: 130 additions & 15 deletions x-pack/filebeat/docs/inputs/input-entity-analytics.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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"]
----
Expand Down Expand Up @@ -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": "[email protected]",
"email": "[email protected]",
"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

Expand Down Expand Up @@ -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`

Expand Down
5 changes: 5 additions & 0 deletions x-pack/filebeat/input/entityanalytics/provider/okta/conf.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
Loading