-
Notifications
You must be signed in to change notification settings - Fork 4.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
x-pack/filebeat/input/entityanalytics/provider/okta: add device handling
WIP: needs validation against real API.
- Loading branch information
Showing
7 changed files
with
520 additions
and
79 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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": "[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 | ||
|
|
||
|
|
@@ -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` | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.