> ## Documentation Index
> Fetch the complete documentation index at: https://specterops-fetch-json-component.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the Collector

> Run the OktaHound collector to gather data from your Okta organization.

<img noZoom src="https://mintcdn.com/specterops-fetch-json-component/pkiaFEhjWYPnhxMb/assets/enterprise-AND-community-edition-pill-tag.svg?fit=max&auto=format&n=pkiaFEhjWYPnhxMb&q=85&s=c83d7e4a67c741a979c0e77bf15c1252" alt="Applies to BloodHound Enterprise and CE" width="482" height="45" data-path="assets/enterprise-AND-community-edition-pill-tag.svg" />

<Callout icon="bullhorn" color="#FFC107">
  The OktaHound collector is currently in **beta**. It will be replaced by a generic OpenGraph collector in a future release.
</Callout>

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:

### OAuth 2.0 Service Application (Recommended)

Register OktaHound as a [service application](/opengraph/extensions/oktahound/okta-app-registration) 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](https://github.com/SpecterOps/OktaHound/releases) 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](/opengraph/extensions/oktahound/okta-app-registration).

<Note>You must convert the private key from JSON to YAML.</Note>

```yaml theme={null}
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:

```yaml theme={null}
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:

```shell theme={null}
OktaHound collect --output ./output --verbosity Trace
```

## Command Line Options

The `collect` subcommand supports the following options:

| Option              | Short | Default       | Description                                                                                   |
| ------------------- | ----- | ------------- | --------------------------------------------------------------------------------------------- |
| `--output`          | `-o`  | `./output`    | Path to the OpenGraph output directory                                                        |
| `--domain`          | `-d`  |               | Okta domain URL (e.g. `https://contoso.okta.com`). Overrides `okta.yaml` setting if provided. |
| `--token`           | `-t`  |               | SSWS API token. Overrides `okta.yaml` setting if provided.                                    |
| `--skip-mfa`        |       |               | Skip collecting user authentication factors (MFA)                                             |
| `--zip`             | `-z`  |               | Compress each exported JSON output file after it is written                                   |
| `--export-ad-nodes` | `-a`  |               | Export the Active Directory subgraph output file                                              |
| `--verbosity`       | `-v`  | `Information` | Set output verbosity (`Trace`, `Debug`, `Information`, `Warning`, `Error`, `Critical`)        |

## API Rate Limiting

Okta [enforces API rate limits](https://developer.okta.com/docs/reference/rl-global-mgmt/) 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**.

<Tip>By default, the client is configured to retry each HTTP request up to 3 times with increasing delays, which effectively mitigates this problem.</Tip>