Skip to main content
Applies to BloodHound Enterprise and CE
The OktaHound collector is currently in beta. It will be replaced by a generic OpenGraph collector in a future release.
This page covers downloading, configuring, and running the beta OktaHound collector against your Okta organization.

​
Authentication Options

Okta supports multiple authentication methods for applications like the OktaHound collector to access the Okta API: Register OktaHound 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 OktaHound 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.

​
Download the Collector

Download the latest beta release of OktaHound specific to your operating system from the releases page on GitHub and extract the archive.

​
Configure Authentication

Rename the okta.sample.oauth.yaml template file to okta.yaml and fill in the Okta organization URI, client ID, and private key from the application registration process.
You must convert the private key from JSON to YAML.
okta:
  client:
    oktaDomain: "https://TODO.okta.com"
    authorizationMode: "PrivateKey"
    clientId: "TODO"
    privateKey:
      "d": "TODO"
      "p": "TODO"
      "q": "TODO"
      "dp": "TODO"
      "dq": "TODO"
      "qi": "TODO"
      "kty": "RSA"
      "e": "AQAB"
      "kid": "TODO"
      "n": "TODO"
If you choose API token authentication (not recommended), rename okta.sample.token to okta.yaml, then set the Okta organization URI and API token: 
okta:
  client:
    oktaDomain: "https://TODO.okta.com"
    authorizationMode: "SSWS"
    token: "TODO"

​
Run the Collector

Run the following command to start collecting data from your Okta organization: 
OktaHound collect --output ./output --verbosity Trace

​
Command Line Options

The collect subcommand supports the following options:
OptionShortDefaultDescription
--output-o./outputPath to the OpenGraph output directory
--domain-dOkta domain URL (e.g. https://contoso.okta.com). Overrides okta.yaml setting if provided.
--token-tSSWS API token. Overrides okta.yaml setting if provided.
--skip-mfaSkip collecting user authentication factors (MFA)
--zip-zCompress each exported JSON output file after it is written
--export-ad-nodes-aExport the Active Directory subgraph output file
--verbosity-vInformationSet output verbosity (Trace, Debug, Information, Warning, Error, Critical)

​
API Rate Limiting

Okta enforces API rate limits to mitigate denial-of-service attacks. The OktaHound collector sometimes hits the limit of 20 calls per second to the /api/v1/apps/* and /oauth2/v1/clients/* endpoints for the Integrator Free Plan.
By default, the client is configured to retry each HTTP request up to 3 times with increasing delays, which effectively mitigates this problem.