> ## 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.

# Getting Started

> Learn how to get started with OktaHound, an OpenGraph extension and data collector for Okta organizations.

<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" />

## Prerequisites

Before you begin, ensure that the following prerequisites are met:

| Prerequisite                                                                               | Description                                                                                  |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| [Ensure graph database is PostgreSQL](/opengraph/requirements#version-requirements)        | For best performance, BloodHound requires PostgreSQL as the graph database rather than Neo4j |
| [Create an API service application](/opengraph/extensions/oktahound/okta-app-registration) | Provides the necessary authentication for OktaHound to access your Okta environment          |
| [Configure and run the collector](/opengraph/extensions/oktahound/collect-data)            | Collects data from your Okta environment and generates JSON files for upload to BloodHound   |

## Register the Extension (BloodHound Enterprise Only)

The BloodHound extension feature is currently available in preview exclusively for BloodHound Enterprise customers. To get started, contact your account team.

The OktaHound extension includes a schema that tells BloodHound how to model and analyze data from your Okta organization. You must register the extension before you upload data generated by the OktaHound collector.

Choose the registration approach that best fits your environment:

* **Simple (recommended):** Upload all required and optional schemas up front.
* **Specific:** Upload the required schemas first, then upload only the optional supporting schemas for the collectors you actively use.

<Note>Hybrid edge data references node kinds across collectors. If the supporting schemas aren't uploaded first, you may encounter missing node kind errors when uploading or exploring hybrid data (`okta-graph-hybrid.json`).</Note>

### Required Schemas

The OktaHound extension bundle includes the required OktaHound schema as well as a required SCIM schema.

<Warning>Always upload the `bh-scim-extension.json` schema. It provides a shared model for provisioned users and groups across cloud identity providers and applications, which avoids creating integration-specific edges for each provider and app combination.</Warning>

### Optional Schemas

OktaHound also includes optional supporting schemas for related data sources. These schemas enable additional node and edge types in BloodHound that are relevant to Okta environments.

If you use Okta with any of the supported data sources in your environment, upload the corresponding schema to ensure that the data is properly modeled in BloodHound.

| Data source | Optional schema file             |
| ----------- | -------------------------------- |
| GitHub      | `bhe-github-extension.json`      |
| Jamf        | `bhe-jamfhound-extension.json`   |
| 1Password   | `bhce-1passhound-extension.json` |
| Snowflake   | `bhce-snowflake-extension.json`  |

## Register Custom Node Icons (Community Edition Only)

Skip this step if you already uploaded an extension schema, as the schema registers the node icons automatically.

If you haven't registered an extension schema, register the Okta and SCIM custom node types by uploading the [bh-okta-custom-nodes.json](https://github.com/SpecterOps/OktaHound/blob/main/Src/Extensions/bh-okta-custom-nodes.json) and [bh-scim-custom-nodes.json](https://github.com/SpecterOps/OktaHound/blob/main/Src/Extensions/bh-scim-custom-nodes.json) files using the [BloodHound API](/opengraph/custom-icons).

## Upload Data to BloodHound

After you complete the prerequisites and register the extension or node icons, upload the data collected by OktaHound to BloodHound.

The OktaHound collector generates multiple JSON files. Each file contains a different subset of data about your Okta environment, such as general configuration data, Active Directory (AD) integration data, and hybrid attack path data.

<Note>AD integration data is generated only when you run collection with the [`--export-ad-nodes`](/opengraph/extensions/oktahound/collect-data#command-line-options) option. Use this option only when you want AD context without running LDAP enumeration with SharpHound, or if you do not have direct AD access but do have the required rights in Okta.</Note>

Upload the generated JSON files to BloodHound in the following order:

<Steps>
  <Step title="okta-graph.json (required)">
    Upload core Okta users, groups, applications, roles, and relationships.
  </Step>

  <Step title="okta-graph-ad.json (optional)">
    Upload Okta/AD integration data (generated only when you run collection with the `--export-ad-nodes` option).
  </Step>

  <Step title="okta-graph-hybrid.json (optional)">
    Upload hybrid attack path data that links Okta and other supported data sources.
  </Step>
</Steps>

## Import Cypher Queries

OktaHound provides [custom Cypher queries](/opengraph/extensions/oktahound/reference/queries) to help you identify attack paths and misconfigurations in your Okta environment. These queries are included in the `queries` directory of the OktaHound extension.

To use these queries, you must first [import](/analyze-data/explore/cypher-search#import-and-export) the `queries/*.json` files into BloodHound. You can then run the queries on the **Explore** page.

<Note>Cypher queries that reference node or edge kinds not present in the database will fail without the extension schema (for example: `failed to translate kinds: unable to map kinds: Okta_ApiServiceIntegration`). Community Edition users can work around this by removing the unrecognized node and edge kinds from the queries until the extension schema becomes available for BloodHound Community Edition.</Note>

<Tip>OktaHound also provides [specialized queries](/opengraph/extensions/oktahound/reference/privilege-zone-rules) in a separate `PrivilegeZoneRules` directory for creating or updating [Cypher-based](/analyze-data/privilege-zones/rules#cypher) Privilege Zone rules.</Tip>

## Next Steps

* Explore the [Okta node types](/opengraph/extensions/oktahound/reference/schema#nodes) and [edge types](/opengraph/extensions/oktahound/reference/schema#edges) in the schema reference
* Try the [Okta Cypher queries](/opengraph/extensions/oktahound/reference/queries) on the **Explore** page
* Learn about [Okta attack paths](/opengraph/extensions/oktahound/overview#okta-attack-paths) and what to look for
* Use OktaHound's [specialized queries](/opengraph/extensions/oktahound/reference/privilege-zone-rules) to create or update [Cypher-based](/analyze-data/privilege-zones/rules#cypher) Privilege Zone rules
* Join the `#okta` channel on the [BloodHound Community Slack](https://slack.specterops.io/) for questions and discussion