From 99e6589b2c641c56344bd9ed93874d54a4808e2a Mon Sep 17 00:00:00 2001 From: chemamartinez Date: Thu, 14 Aug 2025 08:53:36 +0200 Subject: [PATCH 1/3] Add support for oauth2 --- .../_dev/build/docs/README.md | 39 ++++++- .../_dev/deploy/docker/docker-compose.yml | 15 +++ .../deploy/docker/files/config_oauth2.yml | 106 ++++++++++++++++++ packages/entityanalytics_okta/changelog.yml | 5 + .../system/test-oauth2-jwk-json-config.yml | 67 +++++++++++ .../test/system/test-oauth2-oin-config.yml | 53 +++++++++ .../agent/stream/entity-analytics.yml.hbs | 21 ++++ .../data_stream/entity/manifest.yml | 73 +++++++++++- packages/entityanalytics_okta/docs/README.md | 39 ++++++- packages/entityanalytics_okta/manifest.yml | 4 +- 10 files changed, 415 insertions(+), 7 deletions(-) create mode 100644 packages/entityanalytics_okta/_dev/deploy/docker/files/config_oauth2.yml create mode 100644 packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-jwk-json-config.yml create mode 100644 packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-oin-config.yml diff --git a/packages/entityanalytics_okta/_dev/build/docs/README.md b/packages/entityanalytics_okta/_dev/build/docs/README.md index db1efb675b4..e9b45a2b628 100644 --- a/packages/entityanalytics_okta/_dev/build/docs/README.md +++ b/packages/entityanalytics_okta/_dev/build/docs/README.md @@ -23,7 +23,7 @@ The Okta Entity Analytics integration collects two types of data: user and devic Elastic Agent must be installed. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). -The minimum **kibana.version** required is **8.9.0**. +The minimum **kibana.version** required is **9.2.0**. ## Setup @@ -40,6 +40,43 @@ The minimum **kibana.version** required is **8.9.0**. 4. While adding the integration, add the URL and API Token that you got earlier. 5. Save the integration. +## Types Of Authentication +### API Token +In the administration dashboard for your Okta account, navigate to Security>API and in the Tokens tab click the "Create token" button to create a new token. + +Copy the token value and retain this to configure the provider. Note that the token will not be presented again, so it must be copied now. + +You should paste this token into the `Okta API Token` configuration option to start collecting entity analytics logs. + +### Oauth2 +**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. + +### Okta Integration Network (OIN) +The Okta Integration Network provides a simple integration authentication based on OAuth2, but using an API key. +In this type of authentication, we only require an API Key for authenticating the client. +1. Your Okta domain URL. [ Example: https://dev-123456.okta.com ] +2. Your Okta service app Client ID. +3. Your Okta service app Client Secret. + +**Steps to configure Okta OIN authenticaton:** +1. Log into your Okta account, navigate to `Applications` on the left-hand side, click on the `Browse App Catalog` button and search for "Elastic". +2. Click on the Elastic EntityAnalytics app card and then click `Add Integration`, and then `Install & Authorize`. +3. Copy the Client Secret. +4. Navigate to the Fleet integration configuration page for the integration. +5. Set the "Domain" field from the Okta Domain URL of the Okta app. +6. Set the "Client ID" field with the Client ID provided by the Okta app. +7. Set the "Client Secret" field to the Client Secret provided by the Okta app. + ## Usage 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. diff --git a/packages/entityanalytics_okta/_dev/deploy/docker/docker-compose.yml b/packages/entityanalytics_okta/_dev/deploy/docker/docker-compose.yml index 2eb9440d43f..aacdef0e3fa 100644 --- a/packages/entityanalytics_okta/_dev/deploy/docker/docker-compose.yml +++ b/packages/entityanalytics_okta/_dev/deploy/docker/docker-compose.yml @@ -15,3 +15,18 @@ services: - --config=/files/config.yml - --tls-cert=/files/certificate.crt - --tls-key=/files/private.key + entityanalytics_okta_oauth2: + image: docker.elastic.co/observability/stream:v0.18.0 + hostname: trial-xxxxxxx-admin.okta.com + ports: + - 443 + volumes: + - ./files:/files:ro + environment: + PORT: "443" + command: + - http-server + - --addr=:443 + - --config=/files/config_oauth2.yml + - --tls-cert=/files/certificate.crt + - --tls-key=/files/private.key diff --git a/packages/entityanalytics_okta/_dev/deploy/docker/files/config_oauth2.yml b/packages/entityanalytics_okta/_dev/deploy/docker/files/config_oauth2.yml new file mode 100644 index 00000000000..b6f5fcaeb18 --- /dev/null +++ b/packages/entityanalytics_okta/_dev/deploy/docker/files/config_oauth2.yml @@ -0,0 +1,106 @@ +rules: + # OAuth2 token endpoint + - path: /oauth2/v1/token + methods: ["POST"] + request_headers: + Content-Type: + - "application/x-www-form-urlencoded" + query_params: + grant_type: "client_credentials" + scope: "okta.logs.read" + client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" + client_assertion: "{client_assertion:.*}" + responses: + - status_code: 200 + body: | + {{ minify_json ` + { + "token_type": "Bearer", + "expires_in": 3600, + "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", + "scope": "okta.users.read" + } + `}} + # OIN token endpoint + - path: /oauth2/v1/token + methods: ["POST"] + request_headers: + Content-Type: + - "application/x-www-form-urlencoded" + Authorization: + - "Basic dGVzdC1jbGllbnQtaWQ6dGVzdC1jbGllbnQtc2VjcmV0" + query_params: + grant_type: "client_credentials" + scope: "okta.logs.read" + responses: + - status_code: 200 + body: | + {{ minify_json ` + { + "token_type": "Bearer", + "expires_in": 3600, + "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9", + "scope": "okta.users.read" + } + `}} + - path: /api/v1/users + methods: ["GET"] + request_headers: + Authorization: + - "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" + responses: + - status_code: 200 + body: | + {{ minify_json ` + [ + { + "id": "00ub0oNGTSWTBKOLGLNR", + "status": "ACTIVE", + "created": "2013-06-24T16:39:18.000Z", + "activated": "2013-06-24T16:39:19.000Z", + "statusChanged": "2013-06-24T16:39:19.000Z", + "lastLogin": "2013-06-24T17:39:19.000Z", + "lastUpdated": "2013-07-02T21:36:25.344Z", + "passwordChanged": "2013-07-02T21:36:25.344Z", + "profile": { + "firstName": "Isaac", + "lastName": "Brock", + "email": "isaac.brock@example.com", + "login": "isaac.brock@example.com", + "mobilePhone": "555-415-1337" + }, + "credentials": { + "password": { + "value": "tlpWENT2m" + }, + "recovery_question": { + "question": "Who's a major player in the cowboy scene?", + "answer": "Annie Oakley" + }, + "provider": { + "type": "OKTA", + "name": "OKTA" + } + } + } + ] + `}} + - path: /api/v1/users/00ub0oNGTSWTBKOLGLNR/groups + methods: ["GET"] + request_headers: + Authorization: + - "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9" + responses: + - status_code: 200 + body: | + {{ minify_json ` + [ + { + "id": "ODc3ZTBjNGZjY2Y4YmRi", + "profile": { + "description": "All users in your organization", + "name": "Everyone" + } + } + ] + `}} \ No newline at end of file diff --git a/packages/entityanalytics_okta/changelog.yml b/packages/entityanalytics_okta/changelog.yml index fe91a0285d0..07c6ab66487 100644 --- a/packages/entityanalytics_okta/changelog.yml +++ b/packages/entityanalytics_okta/changelog.yml @@ -1,4 +1,9 @@ # newer versions go on top +- version: "3.0.0" + changes: + - description: Add support for Okta OIN and OAuth2 authentication. + type: enhancement + link: https://github.com/elastic/integrations/pull/99999 - version: "2.5.1" changes: - description: Map roles data to ECS. diff --git a/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-jwk-json-config.yml b/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-jwk-json-config.yml new file mode 100644 index 00000000000..39bb8bfd6db --- /dev/null +++ b/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-jwk-json-config.yml @@ -0,0 +1,67 @@ +input: entity-analytics +service: entityanalytics_okta +data_stream: + vars: + okta_domain: trial-xxxxxxx-admin.okta.com + client_id: test-client-id + jwk_json: | + { + "kty": "RSA", + "kid": "test-key-id", + "use": "sig", + "alg": "RS256", + "n": "test-modulus", + "e": "AQAB", + "d": "test-private-exponent", + "p": "test-first-prime-factor", + "q": "test-second-prime-factor", + "dp": "test-first-factor-crt-exponent", + "dq": "test-second-factor-crt-exponent", + "qi": "test-crt-coefficient" + } + okta_scopes: + - okta.users.read + dataset: users + enrich_user_roles: false + preserve_duplicate_custom_fields: true + preserve_original_event: true + enable_request_tracer: true + ssl: | + certificate_authorities: + - | + -----BEGIN CERTIFICATE----- + MIIFszCCA5ugAwIBAgIUdyvMXQ1pOUhZnhb77AODd1TsD/AwDQYJKoZIhvcNAQEL + BQAwaTELMAkGA1UEBhMCWFgxFTATBgNVBAcMDERlZmF1bHQgQ2l0eTEcMBoGA1UE + CgwTRGVmYXVsdCBDb21wYW55IEx0ZDElMCMGA1UEAwwcdHJpYWwteHh4eHh4eC1h + ZG1pbi5va3RhLmNvbTAeFw0yNDA3MTcxMjE0MThaFw0zNDA3MTUxMjE0MThaMGkx + CzAJBgNVBAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0Rl + ZmF1bHQgQ29tcGFueSBMdGQxJTAjBgNVBAMMHHRyaWFsLXh4eHh4eC1hZG1pbi5v + a3RhLmNvbTAeFw0yNDA3MTcxMjE0MThaFw0zNDA3MTUxMjE0MThaMGkxCzAJBgNV + BAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0RlZmF1bHQg + Q29tcGFueSBMdGQxJTAjBgNVBAMMHHRyaWFsLXh4eHh4eC1hZG1pbi5va3RhLmNv + bTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCAgEAog4k0+wjq9Jv6V8Sypui + plJWSR4R3qfGKOcMKFrmJygr9O6cDEEWPypN8ppPXBRlbu7CC2Qz/q6tkyQIu54b + g2m3W0cnHHWmWPDfDABLz5MguinCFsNBnvb67qE6qdCFB8P/WT9fTrKIEi307L2t + 4x1oRIh99+XVFXL54YCHfYrMeYngdkWPQ4qk5rLoxot+zGnQAqpuKv1CaZ9xnfLr + 7O/8OLW/R6JJzfLFcGmUsjtcv+5VGZPOspx33R9YtBFL8Be4vXYt0yT7xxadXRFu + bZEAQWASFPpdW4w/J2erg6hOxUs8bGyN4Z9Wgr8azNQa14cSA3c/7/yCF7ECofsD + Zg5Qzga7WQJoz/z6VhyTjnMDcnDMrzu2NnTtAJL6l0x6g5phne4RisjotbSE3gPj + /cOKyUiH5MDjL2mI6XJyfn2GlhuUAX+ccJIwoco4/6siFXpUdkGca488/gy/tAcQ + AIqLQL1hCQw8DR29aP0p14/7PZFuBRJP9TdDD4HcwkFL3ODNS1xsHEjq2yeB7jX+ + 8Ua0ivln/lzvB7JHPbvIaGF2c7YEXyW+BSHWIwvgjY/7faNuGK1H5B9M7egSgBW7 + 2QCJGP/Yih46ezrRCMA3iu2Yuuo7NRoeY0pNcsiRWQr0NVVuDALhF/4GmbdINJ95 + mkMW0t5HUrESMTu8cJYG2p8CAwEAAaNTMFEwHQYDVR0OBBYEFIrTq92mf6r2X7UO + xFsH3VyEJvKmMB8GA1UdIwQYMBaAFIrTq92mf6r2X7UOxFsH3VyEJvKmMA8GA1Ud + EwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggIBAApF/gOfd5O6POYXrehWPFE+ + X11cjlSCPTQcscHb6bjqKpDE5TPuWdIRZZh8+faRXisXKc1zzA87ZbU3mkBc38Ab + pV8y3wQ4AAwxTze9XpoynOr/UC4WPuizXXaDKspsuaMO+jRLHstiDWvHFVxZrNWa + f+lTzznhRm5rg/GiNFk7CSpgg3YRrdqLKPrTAzOKX8ADu1imHaC6avEcoIkUcnYg + KzrcDTa8tofjUwv4hyNNI+TsfgKHVVX9vymQy6+u95mtPzDnY1E81Veao9UMwUKk + hYlHMWgwnmmfvgSa6emD90Bs+jV58sJsLcg8KTniOh0KCQN5gRug2gLBD6kBHnUh + NmX5UE65einftsTypM98zKTvlbrg68D7lYuTHRX2fCknGqvXCC/i5Jh6jVHghyck + fcG6b5fcrrky2Hy+s0akey/9IGBwZ19ShAfRErGihauRbUjY2UlK7Ffl+rxM3OZB + 27nAYsdWyNj4Du8sdl6n0jy39hhnIfJOOFUy4J/NckH1QqK1il1nGX2Z14G0PrPI + lWWjlw1Ojy5Y3YSSuCaMXS0gjJ47n0GQUQjaR5kPJsd7oryw4O7MSRN1kXMDTjjT + kkUf/bHk8iusvXnetZuNAcfdpDth9C3frypGJxVgKGTWBDNFmdM1s/RJFqMRzpL8 + 9T56eNS5aXOzj3WzkK8e + -----END CERTIFICATE----- diff --git a/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-oin-config.yml b/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-oin-config.yml new file mode 100644 index 00000000000..3b0b0d8aace --- /dev/null +++ b/packages/entityanalytics_okta/data_stream/entity/_dev/test/system/test-oauth2-oin-config.yml @@ -0,0 +1,53 @@ +input: entity-analytics +service: entityanalytics_okta +data_stream: + vars: + okta_domain: trial-xxxxxxx-admin.okta.com + client_id: test-client-id + client_secret: test-client-secret + okta_scopes: + - okta.users.read + dataset: users + enrich_user_roles: false + preserve_duplicate_custom_fields: true + preserve_original_event: true + enable_request_tracer: true + ssl: | + certificate_authorities: + - | + -----BEGIN CERTIFICATE----- + MIIFszCCA5ugAwIBAgIUdyvMXQ1pOUhZnhb77AODd1TsD/AwDQYJKoZIhvcNAQEL + BQAwaTELMAkGA1UEBhMCWFgxFTATBgNVBAcMDERlZmF1bHQgQ2l0eTEcMBoGA1UE + CgwTRGVmYXVsdCBDb21wYW55IEx0ZDElMCMGA1UEAwwcdHJpYWwteHh4eHh4eC1h + ZG1pbi5va3RhLmNvbTAeFw0yNDA3MTcxMjE0MThaFw0zNDA3MTUxMjE0MThaMGkx + CzAJBgNVBAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0Rl + ZmF1bHQgQ29tcGFueSBMdGQxJTAjBgNVBAMMHHRyaWFsLXh4eHh4eC1hZG1pbi5v + a3RhLmNvbTAeFw0yNDA3MTcxMjE0MThaFw0zNDA3MTUxMjE0MThaMGkxCzAJBgNV + BAYTAlhYMRUwEwYDVQQHDAxEZWZhdWx0IENpdHkxHDAaBgNVBAoME0RlZmF1bHQg + Q29tcGFueSBMdGQxJTAjBgNVBAMMHHRyaWFsLXh4eHh4eC1hZG1pbi5va3RhLmNv + bTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCAgEAog4k0+wjq9Jv6V8Sypui + plJWSR4R3qfGKOcMKFrmJygr9O6cDEEWPypN8ppPXBRlbu7CC2Qz/q6tkyQIu54b + g2m3W0cnHHWmWPDfDABLz5MguinCFsNBnvb67qE6qdCFB8P/WT9fTrKIEi307L2t + 4x1oRIh99+XVFXL54YCHfYrMeYngdkWPQ4qk5rLoxot+zGnQAqpuKv1CaZ9xnfLr + 7O/8OLW/R6JJzfLFcGmUsjtcv+5VGZPOspx33R9YtBFL8Be4vXYt0yT7xxadXRFu + bZEAQWASFPpdW4w/J2erg6hOxUs8bGyN4Z9Wgr8azNQa14cSA3c/7/yCF7ECofsD + Zg5Qzga7WQJoz/z6VhyTjnMDcnDMrzu2NnTtAJL6l0x6g5phne4RisjotbSE3gPj + /cOKyUiH5MDjL2mI6XJyfn2GlhuUAX+ccJIwoco4/6siFXpUdkGca488/gy/tAcQ + AIqLQL1hCQw8DR29aP0p14/7PZFuBRJP9TdDD4HcwkFL3ODNS1xsHEjq2yeB7jX+ + 8Ua0ivln/lzvB7JHPbvIaGF2c7YEXyW+BSHWIwvgjY/7faNuGK1H5B9M7egSgBW7 + 2QCJGP/Yih46ezrRCMA3iu2Yuuo7NRoeY0pNcsiRWQr0NVVuDALhF/4GmbdINJ95 + mkMW0t5HUrESMTu8cJYG2p8CAwEAAaNTMFEwHQYDVR0OBBYEFIrTq92mf6r2X7UO + xFsH3VyEJvKmMB8GA1UdIwQYMBaAFIrTq92mf6r2X7UOxFsH3VyEJvKmMA8GA1Ud + EwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggIBAApF/gOfd5O6POYXrehWPFE+ + X11cjlSCPTQcscHb6bjqKpDE5TPuWdIRZZh8+faRXisXKc1zzA87ZbU3mkBc38Ab + pV8y3wQ4AAwxTze9XpoynOr/UC4WPuizXXaDKspsuaMO+jRLHstiDWvHFVxZrNWa + f+lTzznhRm5rg/GiNFk7CSpgg3YRrdqLKPrTAzOKX8ADu1imHaC6avEcoIkUcnYg + KzrcDTa8tofjUwv4hyNNI+TsfgKHVVX9vymQy6+u95mtPzDnY1E81Veao9UMwUKk + hYlHMWgwnmmfvgSa6emD90Bs+jV58sJsLcg8KTniOh0KCQN5gRug2gLBD6kBHnUh + NmX5UE65einftsTypM98zKTvlbrg68D7lYuTHRX2fCknGqvXCC/i5Jh6jVHghyck + fcG6b5fcrrky2Hy+s0akey/9IGBwZ19ShAfRErGihauRbUjY2UlK7Ffl+rxM3OZB + 27nAYsdWyNj4Du8sdl6n0jy39hhnIfJOOFUy4J/NckH1QqK1il1nGX2Z14G0PrPI + lWWjlw1Ojy5Y3YSSuCaMXS0gjJ47n0GQUQjaR5kPJsd7oryw4O7MSRN1kXMDTjjT + kkUf/bHk8iusvXnetZuNAcfdpDth9C3frypGJxVgKGTWBDNFmdM1s/RJFqMRzpL8 + 9T56eNS5aXOzj3WzkK8e + -----END CERTIFICATE----- diff --git a/packages/entityanalytics_okta/data_stream/entity/agent/stream/entity-analytics.yml.hbs b/packages/entityanalytics_okta/data_stream/entity/agent/stream/entity-analytics.yml.hbs index c62ee137a72..6d3fe56d037 100644 --- a/packages/entityanalytics_okta/data_stream/entity/agent/stream/entity-analytics.yml.hbs +++ b/packages/entityanalytics_okta/data_stream/entity/agent/stream/entity-analytics.yml.hbs @@ -9,7 +9,28 @@ id: {{id}} sync_interval: {{sync_interval}} update_interval: {{update_interval}} okta_domain: {{okta_domain}} +{{#if client_id}} +oauth2.client.id: {{client_id}} +oauth2.token_url: {{okta_domain}}/oauth2/v1/token +{{#if client_secret}} +oauth2.client.secret: {{client_secret}} +{{/if}} +oauth2.scopes: +{{#each okta_scopes as |scope|}} + - {{scope}} +{{/each}} +{{#if jwk_json}} +oauth2.jwk_json: {{jwk_json}} +{{/if}} +{{#if jwk_file}} +oauth2.jwk_file: {{jwk_file}} +{{/if}} +{{#if key_pem}} +oauth2.jwk_pem: {{escape_string key_pem}} +{{/if}} +{{else if okta_token}} okta_token: {{okta_token}} +{{/if}} dataset: {{dataset}} {{#if enrich_user_roles}} {{! We include groups in the list when enriching roles, since the default input is to enrich with groups. }} diff --git a/packages/entityanalytics_okta/data_stream/entity/manifest.yml b/packages/entityanalytics_okta/data_stream/entity/manifest.yml index e6053019474..42fa653a5c7 100644 --- a/packages/entityanalytics_okta/data_stream/entity/manifest.yml +++ b/packages/entityanalytics_okta/data_stream/entity/manifest.yml @@ -14,15 +14,82 @@ streams: multi: false required: true show_user: true - description: The Okta domain. + description: The URL of your Okta domain. For example, https://dev-123456.okta.com. - name: okta_token type: password title: Okta API Token multi: false - required: true + required: false + show_user: true + description: | + The API Key of your Okta service application. This is required for standard API Key based authentication only. + Do not use this field if you are using standard OAuth2 authentication or Okta Integration Network (OIN) app authentication. + secret: true + - name: client_id + type: text + title: Client ID + multi: false + required: false + show_user: true + description: | + The Client ID of your Okta service application. + This is required for standard OAuth2 authentication and OIN app authentication. + Do not use this field if you are using API Key based authentication. + - name: client_secret + type: password + title: Client Secret + multi: false + required: false + show_user: true + description: | + The Client Secret of your Okta service application. + This is required for standard OAuth2 authentication and OIN app authentication. + Do not use this field if you are using API Key based authentication. + secret: true + - name: jwk_json + type: password + title: JWK JSON + multi: false + required: false show_user: true - description: The Okta API token, used for authentication. + description: | + The private JSON Web Key (JWK) of your Okta service application. + This is only required for OAuth2 authentication. Do not use this field if you are using API Key based authentication. + Only one of JWK JSON, PEM Encoded Key or JWK File may be used. secret: true + - name: key_pem + type: textarea + title: PEM Encoded Key + multi: false + required: false + show_user: true + description: | + The private key of your Okta service application in PEM format. + This is only required for OAuth2 authentication. Do not use this field if you are using API Key based authentication. + Only one of JWK JSON, PEM Encoded Key or JWK File may be used. + - name: jwk_file + type: text + title: JWK File + multi: false + required: false + show_user: true + description: | + The path to the file containing the private JSON Web Key (JWK) of your Okta service application. + This is only required for OAuth2 authentication. Do not use this field if you are using API Key based authentication. + Only one of JWK JSON, PEM Encoded Key or JWK File may be used. + - name: okta_scopes + type: text + title: Okta Scopes + multi: true + required: false + show_user: true + default: + - okta.users.read + - okta.devices.read + description: | + This is the list of 'okta.*' scopes that your Okta service application has access to. + This is required for standard OAuth2 authentication and OIN app authentication. + Do not use this field if you are using API Key based authentication. - name: dataset type: select title: Okta Dataset diff --git a/packages/entityanalytics_okta/docs/README.md b/packages/entityanalytics_okta/docs/README.md index 110e71ab957..836e4c1ac4a 100644 --- a/packages/entityanalytics_okta/docs/README.md +++ b/packages/entityanalytics_okta/docs/README.md @@ -23,7 +23,7 @@ The Okta Entity Analytics integration collects two types of data: user and devic Elastic Agent must be installed. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). -The minimum **kibana.version** required is **8.9.0**. +The minimum **kibana.version** required is **9.2.0**. ## Setup @@ -40,6 +40,43 @@ The minimum **kibana.version** required is **8.9.0**. 4. While adding the integration, add the URL and API Token that you got earlier. 5. Save the integration. +## Types Of Authentication +### API Token +In the administration dashboard for your Okta account, navigate to Security>API and in the Tokens tab click the "Create token" button to create a new token. + +Copy the token value and retain this to configure the provider. Note that the token will not be presented again, so it must be copied now. + +You should paste this token into the `Okta API Token` configuration option to start collecting entity analytics logs. + +### Oauth2 +**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. + +### Okta Integration Network (OIN) +The Okta Integration Network provides a simple integration authentication based on OAuth2, but using an API key. +In this type of authentication, we only require an API Key for authenticating the client. +1. Your Okta domain URL. [ Example: https://dev-123456.okta.com ] +2. Your Okta service app Client ID. +3. Your Okta service app Client Secret. + +**Steps to configure Okta OIN authenticaton:** +1. Log into your Okta account, navigate to `Applications` on the left-hand side, click on the `Browse App Catalog` button and search for "Elastic". +2. Click on the Elastic EntityAnalytics app card and then click `Add Integration`, and then `Install & Authorize`. +3. Copy the Client Secret. +4. Navigate to the Fleet integration configuration page for the integration. +5. Set the "Domain" field from the Okta Domain URL of the Okta app. +6. Set the "Client ID" field with the Client ID provided by the Okta app. +7. Set the "Client Secret" field to the Client Secret provided by the Okta app. + ## Usage 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. diff --git a/packages/entityanalytics_okta/manifest.yml b/packages/entityanalytics_okta/manifest.yml index 55fba6de18e..bb3fa148b90 100644 --- a/packages/entityanalytics_okta/manifest.yml +++ b/packages/entityanalytics_okta/manifest.yml @@ -1,14 +1,14 @@ format_version: "3.0.2" name: entityanalytics_okta title: Okta Entity Analytics -version: "2.5.1" +version: "3.0.0" description: "Collect Identities from Okta with Elastic Agent." type: integration categories: - security conditions: kibana: - version: "^8.18.3 || ^9.0.2" + version: "^9.2.0" elastic: subscription: "basic" screenshots: From 938f76230e1dc8bc7924e98a593acdb88449ed8a Mon Sep 17 00:00:00 2001 From: chemamartinez Date: Thu, 14 Aug 2025 09:22:25 +0200 Subject: [PATCH 2/3] Update changelog --- packages/entityanalytics_okta/changelog.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/entityanalytics_okta/changelog.yml b/packages/entityanalytics_okta/changelog.yml index 07c6ab66487..4f351dd160e 100644 --- a/packages/entityanalytics_okta/changelog.yml +++ b/packages/entityanalytics_okta/changelog.yml @@ -3,7 +3,7 @@ changes: - description: Add support for Okta OIN and OAuth2 authentication. type: enhancement - link: https://github.com/elastic/integrations/pull/99999 + link: https://github.com/elastic/integrations/pull/14933 - version: "2.5.1" changes: - description: Map roles data to ECS. From cd6a2591843945fe50e19fe70d2a7e934b980bca Mon Sep 17 00:00:00 2001 From: chemamartinez Date: Thu, 16 Oct 2025 14:16:00 +0200 Subject: [PATCH 3/3] Update changelog --- packages/entityanalytics_okta/changelog.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/entityanalytics_okta/changelog.yml b/packages/entityanalytics_okta/changelog.yml index 4f351dd160e..c9f067a9c64 100644 --- a/packages/entityanalytics_okta/changelog.yml +++ b/packages/entityanalytics_okta/changelog.yml @@ -3,7 +3,7 @@ changes: - description: Add support for Okta OIN and OAuth2 authentication. type: enhancement - link: https://github.com/elastic/integrations/pull/14933 + link: https://github.com/elastic/integrations/pull/15668 - version: "2.5.1" changes: - description: Map roles data to ECS.