Configure the Collector

Configure the OpenHound Okta collector to gather data from your Okta organization.

Okta enforces API rate limits by default. OpenHound is configured to retry each HTTP request up to 10 times with increasing delays.

This page covers configuring the OpenHound Okta collector for your Okta organization.

Prerequisites

• OpenHound installed with the Okta collector included. Follow the OpenHound installation instructions to set up OpenHound for BloodHound Community Edition. The Okta collector is included by default in the OpenHound container image.
• An Okta account with permissions to access the Okta API. See the options below for recommended roles and permissions.

The OpenHound setup instructions for BloodHound Community Edition also apply to BloodHound Enterprise users, for now.

OAuth 2.0 Service Application (Recommended)

Register the OpenHound Okta collector as a service application in Okta.

Grant the application limited read-only permissions, then configure authentication with either a symmetric client secret or an asymmetric RSA public/private key pair.

Use an RSA public/private key pair when possible, because it provides stronger security than a symmetric client secret.

API Token (SSWS)

The OpenHound Okta collector can also authenticate using API tokens (also known as SSWS tokens) associated with specific Okta Super Administrator accounts. This is the least secure option, but the easiest one to set up.

Configure OpenHound

The following OpenHound configuration parameters are required to run the Okta collector. These can either be set via the [sources.source.okta.credentials] section of the secrets file or via environment variables using the SOURCES__OKTA__CREDENTIALS prefix.

Option 1: Service Application with JSON key file

Use this option when you store the Okta private key in a file. Set private_key_path to the path of the complete private key JSON that Okta displays when you generate the key pair.

Parameter Name	Environment Variable	Description
base_url	{PREFIX}__BASE_URL	The base URL of the Okta organization. For example: https://spectoropspreview.oktapreview.com.
client_id	{PREFIX}__CLIENT_ID	The client ID of the Okta service application used to authenticate to the Okta API.
private_key_path	{PREFIX}__PRIVATE_KEY_PATH	The path to the private key (.json) used for authentication.

Example Configuration

secrets.toml

[sources.source.okta.credentials]
base_url = "https://mytenant.oktapreview.com"
client_id = "myclientid"
private_key_path = "/path/to/private/key.json"

Option 2: Service Application with base64-encoded JSON key string

Use this option when you store the Okta private key in a text-based secret.

Parameter Name	Environment Variable	Description
base_url	{PREFIX}__BASE_URL	The base URL of the Okta organization. For example: https://spectoropspreview.oktapreview.com.
client_id	{PREFIX}__CLIENT_ID	The client ID of the Okta service application used to authenticate to the Okta API.
private_key_b64	{PREFIX}__PRIVATE_KEY_B64	The private key (.json) encoded as a base64 string.

Example Configuration

secrets.toml

[sources.source.okta.credentials]
base_url = "https://mytenant.oktapreview.com"
client_id = "myclientid"
private_key_b64 = "<base64-encoded-complete-okta-private-key-json>"

Set private_key_b64 to the base64-encoded contents of the complete private key JSON that Okta displays when you generate the key pair.

The private key JSON includes the key identifier (kid). Keep this property in the JSON; you do not retrieve or configure kid separately. The collector uses it to identify the signing key when it requests an access token.

The private key JSON has the following general structure. The values below are placeholders and are not a usable key.

{
  "kty": "RSA",
  "kid": "<key-id-generated-by-okta>",
  "n": "<public-modulus>",
  "e": "AQAB",
  "d": "<private-exponent>",
  "p": "<first-prime-factor>",
  "q": "<second-prime-factor>",
  "dp": "<first-factor-exponent>",
  "dq": "<second-factor-exponent>",
  "qi": "<first-factor-coefficient>"
}

Keep the complete private key JSON and its base64-encoded value secret. Okta displays the private key only when you generate it. If you do not have the JSON, generate and register a new key pair as described in the Okta app registration guide.

Option 3: API Token (SSWS)

Use this option when you want to authenticate with an API token (SSWS) associated with a specific Okta Super Administrator account.

Parameter Name	Environment Variable	Description
base_url	{PREFIX}__BASE_URL	The base URL of the Okta organization. For example: https://spectoropspreview.oktapreview.com.
token	{PREFIX}__TOKEN	The API token (SSWS) used for authentication.

Example Configuration

secrets.toml

[sources.source.okta.credentials]
base_url = "https://mytenant.oktapreview.com"
token = "<api-token>"

Pagination settings

The Okta collector requests explicit page sizes for resources that support large result sets. You can tune these defaults with the following DLT source configuration environment variables:

Environment variable	Default	Purpose
SOURCES__SOURCE__OKTA__APPLICATION_USERS_PAGE_SIZE	500	Application users per page, from 1 through 500
SOURCES__SOURCE__OKTA__GROUPS_PAGE_SIZE	200	Expanded groups per page, from 1 through 200
SOURCES__SOURCE__OKTA__APPLICATION_GROUP_ASSIGNMENTS_PAGE_SIZE	200	Application-group assignments per page, from 20 through 200
SOURCES__SOURCE__OKTA__GROUP_PUSH_MAPPINGS_PAGE_SIZE	1000	Group push mappings per page, from 1 through 1,000
SOURCES__SOURCE__OKTA__IDENTITY_PROVIDER_USERS_PAGE_SIZE	200	Identity-provider users per page, from 1 through 200
SOURCES__SOURCE__OKTA__ENDPOINT_CONCURRENCY	2	Maximum simultaneous requests per endpoint family
SOURCES__SOURCE__OKTA__RATE_LIMIT_MAX_ELAPSED_SECONDS	900	Maximum elapsed retry window for an individual 429 request
SOURCES__SOURCE__OKTA__RATE_LIMIT_REMAINING_RESERVE	1	Requests held in reserve when pacing against a rate-limit window

Application-group assignments are collected from each application’s public assignment endpoint, and the collector retains Okta’s assignment timestamp, priority, and profile field names without publishing assignment profile values to the graph.

If the initial expanded group page repeatedly times out on large Okta tenants, the collector retries that first page with successively halved page sizes before failing. With the default GROUPS_PAGE_SIZE of 200, that fallback sequence is 200, then 100, then 50.

Running OpenHound and Collecting Data

After you set the required configuration parameters, run OpenHound to start the collector and collect data from your . The collector will generate JSON files in the output directory that can be uploaded to BloodHound for analysis.