-
Notifications
You must be signed in to change notification settings - Fork 10
BP-2335: Integrated Windows Authentication for SharpHound Enterprise #182
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.
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
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
67260ab
docs: initial restructuring
jeff-matthews af7f267
wip: initial draft of IWA for sharphound
jeff-matthews d2cc383
wip: IWA edits
jeff-matthews 6f047fc
wip: edits for IWA requirements
jeff-matthews e463794
wip: edits for create collector client
jeff-matthews 8114ad9
refactor: create snippet for scan options and delete redundant page
jeff-matthews 8bd59f0
wip: edits for adfs config
jeff-matthews ddb33dd
wip: edits for switching collector client auth
jeff-matthews c2b091a
docs: apply suggestions from CR review
jeff-matthews c03a263
docs: apply suggestions from tech review
jeff-matthews 6e95443
Merge branch 'main' into BP-2335-sharphound-wia
jeff-matthews File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
198 changes: 169 additions & 29 deletions
198
docs/collect-data/enterprise-collection/create-collector.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,49 +1,189 @@ | ||
| --- | ||
| title: Create a BloodHound Enterprise Collector Client | ||
| title: Create a Collector Client | ||
| description: Learn how to create a BloodHound Enterprise collector client. | ||
| --- | ||
|
|
||
| <img noZoom src="/assets/enterprise-edition-pill-tag.svg" alt="Applies to BloodHound Enterprise only"/> | ||
|
|
||
| ## Purpose | ||
|
|
||
| This guide explains how to create a BloodHound Enterprise collector client, either of: | ||
| This guide explains how to create a BloodHound Enterprise collector client. It is intended for Administrators who are deploying SharpHound Enterprise or AzureHound Enterprise for data collection. | ||
|
|
||
| * SharpHound Enterprise | ||
| * AzureHound Enterprise | ||
| Collector clients connect your BloodHound Enterprise tenant to your collector applications. They provide the necessary authentication and configuration information for your SharpHound Enterprise or AzureHound Enterprise collector applications to securely upload collected data to your BloodHound Enterprise instance for processing and analysis. | ||
|
|
||
| It should be used by BloodHound Enterprise (BHE) administrators when deploying SharpHound Enterprise or AzureHound Enterprise. | ||
| BloodHound Enterprise supports two types of collector clients: | ||
|
|
||
| - **SharpHound Enterprise** - Collects data from Active Directory environments | ||
| - **AzureHound Enterprise** - Collects data from Entra ID environments | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| * Having deployed a BloodHound Enterprise Tenant | ||
| * Logged in as a user role, which is authorized to create a new collector client, see [Administering users and roles](/manage-bloodhound/auth/users-and-roles) | ||
| - A BloodHound Enterprise <Tooltip headline="tenant" tip="A dedicated instance of BloodHound that contains its own data, configurations, and user access controls.">tenant</Tooltip> | ||
| - Logged in as a user assigned a [role](/manage-bloodhound/auth/users-and-roles) authorized to create a collector client | ||
|
|
||
| <Note>See [SharpHound Enterprise System Requirements](/install-data-collector/install-sharphound/system-requirements) or [AzureHound Enterprise System Requirements](/install-data-collector/install-azurehound/system-requirements) for more information on the requirements for each collector type.</Note> | ||
|
|
||
| ## Process | ||
|
|
||
| 1. In the top right, click settings ⚙️ → **Administration** | ||
| <Frame> | ||
| <img src="/assets/image-69.png" alt=""/> | ||
| </Frame> | ||
| 2. In the top left side, click **Manage Clients** | ||
| <Frame> | ||
| <img src="/assets/image-70.png" alt=""/> | ||
| </Frame> | ||
| 3. On the right side, click **Create Client** and, from the drop-down, select one of the collector clients, for example **Create SharpHound Client** | ||
| <Frame> | ||
| <img src="/assets/image-71.png" alt=""/> | ||
| </Frame> | ||
| 4. In the pop-up window, for example named _New SharpHound Enterprise Client_, input the **Client Name** and click **CREATE** | ||
| <Frame> | ||
| <img src="/assets/image-72.png" alt=""/> | ||
| </Frame> | ||
| 5. The pop-up window _Client Token Info_ will appear; follow the instructions in it - save the key before clicking **CLOSE** | ||
| <Frame> | ||
| <img src="/assets/image-73.png" alt=""/> | ||
| </Frame> | ||
| This guide covers the required steps to create a collector client in your BloodHound Enterprise tenant. | ||
|
|
||
| Optional configuration settings are also explained, but can be skipped during initial setup and configured later if necessary. | ||
|
|
||
| ### AzureHound Enterprise | ||
|
|
||
| AzureHound collector clients use API token-based authentication. When creating an AzureHound collector client, you must save the generated token information and use it to [configure](/install-data-collector/install-azurehound/create-configuration) the AzureHound collector application. | ||
|
|
||
| <Steps> | ||
| <Step title="Open the Manage Clients page"> | ||
| In the left menu, click **Administration** > **Manage Clients**. | ||
| </Step> | ||
|
|
||
| <Step title="Create the client"> | ||
| 1. On the right side of the page, click **Create Client**. | ||
|
|
||
| 1. Select **Create AzureHound Client** from the dropdown menu. | ||
|
|
||
| 1. Complete the required fields: | ||
|
|
||
| | Field | Required | Description | | ||
| |-------|----------|-------------| | ||
| | **Client Name** | Yes | A descriptive name for the collector client (e.g., the name of the domain it collects from or system it runs on) | | ||
| | **Collection Schedule** | No | Optional configuration options for [scheduling](/collect-data/enterprise-collection/collection-schedule) data collection jobs | | ||
|
|
||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/create-azurehound.png" | ||
| alt="A view of the Create Client screen for AzureHound Enterprise" | ||
| /> | ||
| </Frame> | ||
|
|
||
| 1. Click **Create**. | ||
| </Step> | ||
|
|
||
| <Step title="Save the client token"> | ||
| A _Client Token Info_ window will appear with authentication credentials. Copy and save the token information before closing. | ||
|
|
||
| <Note>The token information is required to [configure](/install-data-collector/install-azurehound/create-configuration) the AzureHound collector application.</Note> | ||
|
|
||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/azurehound-client-token-info.png" | ||
| alt="A view of the client token info screen for AzureHound Enterprise" | ||
| /> | ||
| </Frame> | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ### SharpHound Enterprise | ||
|
|
||
| SharpHound Enterprise collector clients support both API token-based authentication and Integrated Windows Authentication (IWA) via Active Directory Federation Services (ADFS). | ||
|
|
||
| When creating a SharpHound Enterprise collector client, you must select the authentication method and provide the required information based on that method. Be sure to save the generated token or configuration information and use it to [configure](/install-data-collector/install-sharphound/local-configuration) the SharpHound Enterprise collector application. | ||
|
|
||
| <Steps> | ||
| <Step title="Open the Manage Clients page"> | ||
| In the left menu, click **Administration** > **Manage Clients**. | ||
| </Step> | ||
|
|
||
| <Step title="Create the client"> | ||
| 1. On the right side of the page, click **Create Client**. | ||
|
|
||
| 1. Select **Create SharpHound Enterprise Client** from the dropdown menu. | ||
|
|
||
| 1. Complete the required fields: | ||
|
|
||
| | Field | Required | Description | | ||
| |-------|----------|-------------| | ||
| | **Client Name** | Yes | A descriptive name for the collector client (e.g., the name of the domain it collects from or system it runs on) | | ||
| | **Collection Schedule** | No | Optional configuration options for [scheduling](/collect-data/enterprise-collection/collection-schedule) data collection jobs | | ||
| | **Advanced Options** | No | Optional domain controller targeting<br/><br/>By default, SharpHound Enterprise will collect data from the Primary Domain Controller as configured by FSMO roles<br/><br/>Specifying a target will prevent cross-trust collection from working unless the targeted LDAP server can respond for all desired domains | | ||
| | **Authentication** | Yes | Authentication method the client will use:<br/><ul><li>**BHE Authentication**: Traditional API token-based authentication (default)</li><li>**Integrated Windows Authentication**: Windows-based authentication via ADFS</li></ul> | | ||
| | **Issuer ID** | Yes<br/><br/>(*IWA only*) | The ADFS well-known endpoint URL, typically: `https://adfs.example.com/.well-known/openid-configuration` | | ||
| | **Issuer Address Override** | No<br/><br/>(*IWA only*) | An optional override for the token issuer address if your ADFS configuration uses a different issuer URL for token validation | | ||
|
|
||
| <Tabs> | ||
| <Tab title="BHE Authentication"> | ||
| The following screenshot shows the client creation form when **BHE Authentication** is selected. | ||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/create-sharphound-bhe-auth.png" | ||
| alt="A view of the Create Client screen for SharpHound Enterprise" | ||
| /> | ||
| </Frame> | ||
| </Tab> | ||
|
|
||
| <Tab title="Integrated Windows Authentication"> | ||
| The following screenshot shows the client creation form when **Integrated Windows Authentication** is selected. Note the additional required **Issuer ID** field and optional **Issuer Address Override**. | ||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/create-sharphound-iwa-auth.png" | ||
| alt="A view of the Create Client screen for SharpHound Enterprise IWA" | ||
| /> | ||
| </Frame> | ||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| 1. Click **Create**. | ||
| </Step> | ||
|
|
||
| <Step title="Save the client token or configuration"> | ||
| A pop-up window will appear and display the client token (for BHE Authentication) or client ID information (for Integrated Windows Authentication). Follow the instructions in it before clicking **Close**. | ||
|
|
||
| <Note> | ||
| **Switching Authentication Methods** | ||
|
|
||
| If you are switching an existing SharpHound Enterprise collector client to a different authentication method, this step replaces the current credentials. | ||
|
|
||
| - Switching to **Integrated Windows Authentication** invalidates existing API tokens and requires you to update the `settings.json` file and remove the `auth.json` file. | ||
| - Switching to **BHE Authentication** generates a new token and requires you to update the `auth.json` file and disable IWA in the `settings.json` file. | ||
| </Note> | ||
|
|
||
| <Tabs> | ||
| <Tab title="BHE Authentication"> | ||
| A _Client Token Info_ window will appear with authentication credentials. Copy and save the token information before closing. | ||
|
|
||
| <Note>The token information is required to [configure](/install-data-collector/install-sharphound/local-configuration#auth-json) the SharpHound Enterprise collector application in the `auth.json` file.</Note> | ||
|
|
||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/sharphound-client-token-info.png" | ||
| alt="A view of the client token info screen for SharpHound Enterprise" | ||
| /> | ||
| </Frame> | ||
| </Tab> | ||
|
|
||
| <Tab title="Integrated Windows Authentication"> | ||
| A _Client Configuration Info_ window will appear with the Client ID required to set up ADFS. | ||
|
|
||
| <Note>The Client ID and configuration details are required to [configure ADFS](/install-data-collector/install-sharphound/configure-adfs-iwa) and to [configure](/install-data-collector/install-sharphound/local-configuration) the SharpHound Enterprise collector application in the `settings.json` file.</Note> | ||
|
|
||
| <Frame> | ||
| <img | ||
| src="/images/data_collectors/sharphound-client-config-info.png" | ||
| alt="A view of the client configuration info screen for SharpHound Enterprise IWA" | ||
| /> | ||
| </Frame> | ||
| </Tab> | ||
| </Tabs> | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Outcome | ||
|
|
||
| The collector client will appear in the **Manage Clients** table with a **Status** of **Unconfigured**. | ||
| BloodHound Enterprise displays collector clients in the table on the **Manage Clients** page with a **Status** of **Unconfigured**. | ||
|
|
||
| <Frame> | ||
| <img src="/assets/image-74.png" alt=""/> | ||
| <img | ||
| src="/images/data_collectors/create-collector-outcome.png" | ||
| alt="A view of the clients table showing a newly created AzureHound and SharpHound Enterprise collector clients with a status of Unconfigured" | ||
| /> | ||
| </Frame> | ||
|
|
||
| ## Next Steps | ||
|
|
||
| - SharpHound Enterprise clients: | ||
| - **BHE Authentication**: Use the token information to [configure](/install-data-collector/install-sharphound/local-configuration#auth-json) the SharpHound Enterprise collector application in the `auth.json` file. | ||
| - **Integrated Windows Authentication**: Follow the [ADFS configuration guide](/install-data-collector/install-sharphound/configure-adfs-iwa) to set up ADFS, then [configure](/install-data-collector/install-sharphound/local-configuration#settings-json) the SharpHound Enterprise collector application in the `settings.json` file. | ||
|
|
||
| - AzureHound Enterprise clients: | ||
| - Use the token information to [configure](/install-data-collector/install-azurehound/create-configuration) the AzureHound collector application. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.