Skip to content

BED-8516: Added API client auth for Jamf collector #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jeff-matthews merged 13 commits into from
Jun 18, 2026
+90 −27
Merged

BED-8516: Added API client auth for Jamf collector #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
780a644
docs: added API client auth for jamf collector
jeff-matthews Jun 8, 2026
2e90108
Filter certifications across all status (#310)
jeff-matthews Jun 9, 2026
446584d
chore: update openapi spec for v0.3.0 (#308)
jeff-matthews Jun 10, 2026
ee3bfc5
Initial guidance for pre-installed extensions (#311)
jeff-matthews Jun 10, 2026
fa0aeb8
Path highlighting, label clipping, and default layout behavior (#309)
jeff-matthews Jun 11, 2026
65f6572
BP-2693: Release notes (2026-06-16) (#312)
jeff-matthews Jun 15, 2026
5c32673
Merge branch 'release/v9.3.0' into openhound-jamf-auth
jeff-matthews Jun 15, 2026
4a82288
Merge branch 'main' into openhound-jamf-auth
jeff-matthews Jun 17, 2026
6045ed8
fix: removed stale file from old merge
jeff-matthews Jun 17, 2026
59ae500
docs: update links to jamf docs
jeff-matthews Jun 18, 2026
d0b08aa
docs: update links to jamf docs
jeff-matthews Jun 18, 2026
46cba4a
style: normalize link text
jeff-matthews Jun 18, 2026
5a5e7f1
docs: apply suggestions from tech review
jeff-matthews Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 80 additions & 19 deletions docs/openhound/collectors/jamf/collect-data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,42 +12,103 @@ This page covers configuring the OpenHound Jamf collector for your Jamf Pro tena
## Prerequisites

* OpenHound installed with the Jamf collector included. Follow the OpenHound [installation](/openhound/community) instructions to set up OpenHound for BloodHound Community Edition. The Jamf collector is included by default in the OpenHound container image.
* A Jamf Pro account with permissions to access the Jamf Pro API. See the options below for recommended roles and permissions.
* Credentials to authenticate against the Jamf Pro API. See the options below for details on supported authentication methods.

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

### Auditor Account (Recommended)
## Choose an authentication method

Create a [new account](https://docs.jamf.com/10.36.0/jamf-pro/install-guide-linux/Jamf_Pro_User_Accounts_and_Groups.html) directly assigned or part of a group assigned the "Auditor" default Jamf Pro role with "Full Access".
The OpenHound Jamf collector supports two authentication methods. Use the API client method whenever possible.

This account will have restricted read permissions to Jamf Pro objects.
### API client (recommended)

### Administrator Account
Authenticate with a [Jamf Pro API client](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html) using the OAuth client credentials flow. API clients are not tied to a user account, can be scoped to a specific API role, and can be rotated or revoked independently.

The OpenHound Jamf collector can authenticate using username and password for an account that has the default "Administrator" role with "Full Access" or member of a group with the "Administrator" role and "Full Access".
To prepare OpenHound credentials for this method:

This is the least secure option and does not follow the best practice of least-privilege.
<Steps>
<Step title="Create an API role">
In Jamf Pro, create an [API role](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Creating_an_API_Role) and grant it the following privileges:

<Expandable title="required privileges">
- Read User
- Read Accounts
- Read Account Groups
- Read Policies
- Read Scripts
- Read Computer Extension Attributes
- Read Sites
- Read Computers
- Read API Integrations
- Read API Roles
- Read SSO Settings
</Expandable>
</Step>

<Step title="Create an API client">
In Jamf Pro, create an [API client](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Creating_an_API_Client).

Assign it the API role from the previous step and set the **Access token lifetime** to `7200` seconds (2 hours).
</Step>

<Step title="Generate a client secret">
In Jamf Pro, generate a [client secret](https://learn.jamf.com/r/en-US/jamf-pro-documentation-current/Generating_a_Client_Secret) for the API client.

Copy the **Client ID** and the **Client secret** (you need both to configure the OpenHound `secrets.toml` file).

<Warning>
The client secret is only displayed once and cannot be retrieved later. If you lose it, you must generate a new one.
</Warning>
</Step>
</Steps>

### Username and password

Authenticate with a Jamf Pro user account. Create a [new account](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Jamf_Pro_User_Accounts_and_Groups.html), or use an existing one, that is directly assigned or a member of a group assigned to one of the following roles with "Full Access":

- **Auditor** (recommended) - Provides restricted read permissions to Jamf Pro objects and follows least privilege.
- **Administrator** - Grants full administrative access. Use only when an Auditor account is not available.

## Configure OpenHound

The following OpenHound configuration parameters are required to run the Jamf collector. These can either be set
via the `[sources.source.jamf]` section of the secrets file or via environment variables using the `SOURCES__SOURCE__JAMF` prefix.
Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.

<Warning>
The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.
</Warning>
Comment on lines +76 to +80

@coderabbitai coderabbitai Bot Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix the Jamf environment-variable prefix to match the documented OpenHound credentials convention.

SOURCES__SOURCE__JAMF__CREDENTIALS appears inconsistent with the established [sources.source.<collector>.credentials] mapping pattern shown elsewhere (SOURCES__<COLLECTOR>__CREDENTIALS). As written, users may set the wrong env vars and fail auth/config loading.

Suggested doc fix 
-Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.
+Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__JAMF__CREDENTIALS` prefix.
...
-  The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.
+  The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__JAMF__CREDENTIALS` prefix.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.
| Parameter Name | Environment Variable | Description |
|----------------|---------------------------------|------------------------------------------------------------------------------------|
| `username` | \{PREFIX\}__USERNAME | The username of the account used to authenticate to the Jamf Pro API. |
| `password` | \{PREFIX\}__PASSWORD | The password of the account used to authenticate to the Jamf Pro API. |
| `host` | \{PREFIX\}__HOST | The full host/url of the Jamf Pro tenant. For example: `https://jamf.example.com`. |
<Warning>
The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__SOURCE__JAMF__CREDENTIALS` prefix.
</Warning>
Credentials for the Jamf collector are configured under the `[sources.source.jamf.credentials]` section of the secrets file, or via environment variables that use the `SOURCES__JAMF__CREDENTIALS` prefix.
<Warning>
The credentials configuration structure changed in a recent release of the OpenHound Jamf collector. If you are upgrading from an earlier version, move existing `username`, `password`, and `host` values from `[sources.source.jamf]` into `[sources.source.jamf.credentials]` and update any matching environment variables to use the new `SOURCES__JAMF__CREDENTIALS` prefix.
</Warning>
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openhound/collectors/jamf/collect-data.mdx` around lines 44 - 48, The
environment-variable prefix in the Jamf collector docs is incorrect; replace
instances of SOURCES__SOURCE__JAMF__CREDENTIALS with the correct convention
SOURCES__JAMF__CREDENTIALS to match the [sources.source.<collector>.credentials]
mapping used elsewhere, and update the warning and surrounding text so examples
and instructions consistently reference SOURCES__JAMF__CREDENTIALS.


| Parameter Name | Environment Variable | Description |
|----------------|---------------------------------|------------------------------------------------------------------------------------|
| `username` | \{PREFIX\}__USERNAME | The username of the account used to authenticate to the Jamf Pro API. |
| `password` | \{PREFIX\}__PASSWORD | The password of the account used to authenticate to the Jamf Pro API. |
| `host` | \{PREFIX\}__HOST | The full host/url of the Jamf Pro tenant. For example: `https://jamf.example.com`. |
### API client parameters

| Parameter name | Environment variable | Description |
|-----------------|-------------------------------|---------------------------------------------------------------------------------------------------|
| `client_id` | \{PREFIX\}__CLIENT_ID | The client ID of the Jamf Pro API client used to authenticate to the Jamf Pro API. |
| `client_secret` | \{PREFIX\}__CLIENT_SECRET | The client secret of the Jamf Pro API client used to authenticate to the Jamf Pro API. |
| `host` | \{PREFIX\}__HOST | The full host URL of the Jamf Pro tenant. For example: `https://tenant.jamfcloud.com`. |

### Example Configuration
```toml title="secrets.toml"
[sources.source.jamf]
username = "myusername"
[sources.source.jamf.credentials]
client_id = "myclientid"
client_secret = "myclientsecret"
host = "https://tenant.jamfcloud.com"
```

### Username and password parameters

| Parameter name | Environment variable | Description |
|----------------|---------------------------|----------------------------------------------------------------------------------------|
| `username` | \{PREFIX\}__USERNAME | The username of the account used to authenticate to the Jamf Pro API. |
| `password` | \{PREFIX\}__PASSWORD | The password of the account used to authenticate to the Jamf Pro API. |
| `host` | \{PREFIX\}__HOST | The full host URL of the Jamf Pro tenant. For example: `https://tenant.jamfcloud.com`. |

```toml title="secrets.toml"
[sources.source.jamf.credentials]
username = "myusername"
password = "mypassword"
host = "https://tenant.jamfcloud.com"
```

## Running OpenHound and Collecting Data
## Run OpenHound and collect data

<RunAndCollect source="Jamf" env="Pro tenant" />
18 changes: 10 additions & 8 deletions docs/openhound/collectors/jamf/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,19 @@ description: Learn about the SpecterOps-supported OpenHound Jamf collector for B

The OpenHound Jamf collector is the SpecterOps-supported tool for retrieving Jamf Pro tenant data for BloodHound.

If you are evaluating collector options for the Jamf extension, this is the recommended path. An alternative collector, [JamfHound](https://github.com/SpecterOps/JamfHound), also exists, but this documentation section focuses specifically on the OpenHound-based collector.
<Note>
If you are evaluating collector options for the Jamf extension, this is the recommended path. An alternative collector ([JamfHound](https://github.com/SpecterOps/JamfHound)) also exists, but this documentation focuses specifically on the OpenHound-based collector.
</Note>

## Authentication Options
## Authentication options

The OpenHound Jamf collector supports two authentication patterns:
The OpenHound Jamf collector supports two authentication methods against the Jamf API:

- [Auditor account](/openhound/collectors/jamf/collect-data): Recommended for most environments because it follows a read-oriented, lower-privilege collection path.
- [Administrator account](/openhound/collectors/jamf/collect-data): Simpler if you already have an admin account available, but less aligned with least privilege.
- [API client (recommended)](/openhound/collectors/jamf/collect-data#api-client-recommended): Authenticate with a Jamf API client using the OAuth client credentials flow. This approach avoids tying collection to a user account and is the preferred option for production environments.
- [Username and password](/openhound/collectors/jamf/collect-data#username-and-password): Authenticate with a Jamf user account. Pair this method with the Auditor role in Jamf to follow least privilege.

## Next Steps
## Next steps

- Review [Configure the Collector](/openhound/collectors/jamf/collect-data)
- Choose an authentication approach based on your available Jamf Pro roles
- Choose an authentication method and assign an appropriate Jamf role
- Review [Configure the collector](/openhound/collectors/jamf/collect-data)
- Import the resulting data with the [Jamf OpenGraph extension](/opengraph/extensions/jamf/getting-started)
Loading