BED-6715: AzureHound managed identity authentication#118
BED-6715: AzureHound managed identity authentication#118jeff-matthews wants to merge 14 commits intomainfrom
Conversation
WalkthroughDocumentation for AzureHound installation and configuration reorganized to support dual authentication paths (Azure Managed Identity — recommended — and Certificate). Content consolidated into tab-driven flows, new managed identity recommendation snippet added, Mermaid workflow diagram introduced, prerequisites expanded, and scripted PowerShell registration retained and rewritten. Changes
Sequence Diagram(s)(omitted — changes are documentation restructures without new runtime control-flow requiring diagram) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/install-data-collector/install-azurehound/azure-configuration.mdx (1)
156-172: Clarify that Microsoft Graph permissions require admin consent.While the steps correctly guide users through granting admin consent, the learning preferences indicate that documentation should explicitly state that Microsoft Graph application permissions (Directory.Read.All and RoleManagement.Read.All) require admin consent.
Consider adding a clarifying note before this step to emphasize that admin consent is a required next step after adding permissions.
Based on learnings, add an explicit note like:
<Step title="Grant admin consent"> + + The Microsoft Graph API permissions (Directory.Read.All and RoleManagement.Read.All) require admin consent to function correctly. + After adding the required permissions, you must grant admin consent for the application to use them.docs/install-data-collector/install-azurehound/create-configuration.mdx (1)
2-2: Update title to include "Enterprise" for consistency.The page title "Create an AzureHound Configuration" should be "Create an AzureHound Enterprise Configuration" to match terminology conventions used elsewhere in the documentation and to be explicit that this is an Enterprise-specific feature.
-title: Create an AzureHound Configuration +title: Create an AzureHound Enterprise Configuration
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (20)
docs/assets/azurehound-install-app-registrations.pngis excluded by!**/*.pngdocs/assets/azurehound-install-branding-result.pngis excluded by!**/*.pngdocs/assets/azurehound-install-branding.pngis excluded by!**/*.pngdocs/assets/azurehound-install-upload-logo.pngis excluded by!**/*.pngdocs/assets/image-103.pngis excluded by!**/*.pngdocs/assets/image-106.pngis excluded by!**/*.pngdocs/assets/image-108.pngis excluded by!**/*.pngdocs/assets/image-110.pngis excluded by!**/*.pngdocs/assets/image-111.pngis excluded by!**/*.pngdocs/assets/image-113.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/admin-consent-granted.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/app-registration-details.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/directory-read-all.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/grant-admin-consent.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/ms-graph-api-permission-type.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/register-app.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/remove-default-permission.pngis excluded by!**/*.pngdocs/images/data_collectors/azurehound/rolemanagement-read-all.pngis excluded by!**/*.pngdocs/images/data_collectors/grant_admin_consent.pngis excluded by!**/*.pngdocs/images/data_collectors/rolemanagement_read_all.pngis excluded by!**/*.png
📒 Files selected for processing (3)
docs/install-data-collector/install-azurehound/azure-configuration.mdx(1 hunks)docs/install-data-collector/install-azurehound/create-configuration.mdx(4 hunks)docs/snippets/hounds/manged-id-recommendation.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 42
File: docs/install-data-collector/install-azurehound/system-requirements.mdx:70-73
Timestamp: 2025-08-08T15:57:55.743Z
Learning: For AzureHound docs (docs/install-data-collector/install-azurehound/system-requirements.mdx), prefer explicitly stating:
- Directory Reader must be permanently active (not PIM-eligible only).
- Microsoft Graph application permissions (Directory.Read.All, RoleManagement.Read.All) require admin consent.
- Azure Reader role phrasing: “on all Azure subscriptions, ideally assigned at the tenant root group (root management group) scope.”
📚 Learning: 2025-08-08T15:57:55.743Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 42
File: docs/install-data-collector/install-azurehound/system-requirements.mdx:70-73
Timestamp: 2025-08-08T15:57:55.743Z
Learning: For AzureHound docs (docs/install-data-collector/install-azurehound/system-requirements.mdx), prefer explicitly stating:
- Directory Reader must be permanently active (not PIM-eligible only).
- Microsoft Graph application permissions (Directory.Read.All, RoleManagement.Read.All) require admin consent.
- Azure Reader role phrasing: “on all Azure subscriptions, ideally assigned at the tenant root group (root management group) scope.”
Applied to files:
docs/install-data-collector/install-azurehound/azure-configuration.mdxdocs/snippets/hounds/manged-id-recommendation.mdxdocs/install-data-collector/install-azurehound/create-configuration.mdx
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/install-data-collector/install-azurehound/create-configuration.mdx
🔇 Additional comments (5)
docs/install-data-collector/install-azurehound/azure-configuration.mdx (2)
334-334: Excellent explicit coverage of permanent assignment requirement.Line 334 correctly and explicitly states "Ensure that the Assignment type is Active and the Permanently assigned box is checked." This properly addresses the requirement that Directory Reader must be permanently active (not PIM-eligible only), as noted in prior documentation guidance.
197-234: Well-structured Managed Identity configuration section.The new Managed Identity subsection provides clear step-by-step guidance that:
- References Microsoft documentation for detailed context
- Explicitly recommends User-Assigned Managed Identity (reinforced via imported recommendation component)
- Includes proper links and navigation hints for users
The structure using Steps component makes the flow easy to follow.
docs/install-data-collector/install-azurehound/create-configuration.mdx (3)
10-22: Excellent prerequisites table expansion.The prerequisites table properly documents all required information for both authentication paths:
- Existing prerequisites are clearly explained with links
- New Managed Identity and Certificate prerequisites are properly scoped (lines 21-22) with accurate field names and references
- Prerequisite descriptions correctly link to their configuration sections
The organization makes it clear which items are conditionally required based on the chosen authentication method.
102-201: Excellent dual-path authentication flow with tab interface.The multi-tab authentication structure (lines 107-201) provides:
- Clear guidance to select between Azure Managed Identity (recommended) and Certificate
- Strong recommendation for Managed Identity at line 105
- Comprehensive step-by-step instructions for each path with expected CLI prompts and outputs
- Proper emphasis on User-Assigned Managed Identity type with helpful note on locating the Client ID (line 140)
- Proper context about certificate characteristics (lines 174-180)
- Consistent structure and formatting within both tabs
The tabbed interface makes both paths equally discoverable while still guiding users toward the recommended Managed Identity approach.
67-77: Version references correctly updated.CLI version references are properly updated from v2.0.5 to v2.8.1 at lines 67 and 77, with consistent formatting throughout the configuration flow examples.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/install-data-collector/install-azurehound/azure-configuration.mdx (2)
334-334: Add explicit clarification that Directory Reader must not be PIM-eligible only.Line 334 correctly specifies "Permanently assigned" but per learnings from prior reviews, the documentation should explicitly clarify that the Directory Reader role must be permanently active and not assigned as PIM-eligible only. This distinction helps avoid misconfiguration.
Consider adding a note before or after line 334:
1. Ensure that the Assignment type is **Active** and the **Permanently assigned** box is checked. Enter a justification and click **Assign**. + + <Note>The Directory Reader role must be permanently assigned, not PIM-eligible only. Ensure **Permanently assigned** is selected to avoid authentication failures.</Note>Based on learnings, this explicit guidance reduces support burden.
347-368: Clarify Azure Reader role assignment guidance to align with best practices.Lines 347–368 guide assigning the Reader role at the Tenant Root Group scope, which aligns with best practices. However, the language could be more explicit about this being the recommended approach, per established guidance. Currently, line 347 says "If you do not have any management groups, you may either create your Tenant Root Group..." which sounds optional rather than recommended.
Consider revising line 347 to explicitly recommend assignment at the tenant root group scope:
-If you do not have any management groups, you may either create your Tenant Root Group following the prompts in the middle of the screen to ensure future visibility if another administrator begins use of subscriptions, or you may skip this section altogether. +The Reader role should be assigned on all Azure subscriptions, ideally at the Tenant Root Group (root management group) scope to ensure visibility of all current and future subscriptions. If you do not have a Tenant Root Group configured, create one following the prompts in the Azure portal. Skipping this step may result in missing data during collection.Based on learnings, this guidance is preferred for AzureHound docs.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/install-data-collector/install-azurehound/azure-configuration.mdx(1 hunks)docs/install-data-collector/install-azurehound/create-configuration.mdx(4 hunks)docs/snippets/hounds/managed-id-recommendation.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/snippets/hounds/managed-id-recommendation.mdx
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 42
File: docs/install-data-collector/install-azurehound/system-requirements.mdx:70-73
Timestamp: 2025-08-08T15:57:55.743Z
Learning: For AzureHound docs (docs/install-data-collector/install-azurehound/system-requirements.mdx), prefer explicitly stating:
- Directory Reader must be permanently active (not PIM-eligible only).
- Microsoft Graph application permissions (Directory.Read.All, RoleManagement.Read.All) require admin consent.
- Azure Reader role phrasing: “on all Azure subscriptions, ideally assigned at the tenant root group (root management group) scope.”
📚 Learning: 2025-08-08T15:57:55.743Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 42
File: docs/install-data-collector/install-azurehound/system-requirements.mdx:70-73
Timestamp: 2025-08-08T15:57:55.743Z
Learning: For AzureHound docs (docs/install-data-collector/install-azurehound/system-requirements.mdx), prefer explicitly stating:
- Directory Reader must be permanently active (not PIM-eligible only).
- Microsoft Graph application permissions (Directory.Read.All, RoleManagement.Read.All) require admin consent.
- Azure Reader role phrasing: “on all Azure subscriptions, ideally assigned at the tenant root group (root management group) scope.”
Applied to files:
docs/install-data-collector/install-azurehound/create-configuration.mdxdocs/install-data-collector/install-azurehound/azure-configuration.mdx
📚 Learning: 2025-10-02T18:01:39.059Z
Learnt from: StephenHinck
Repo: SpecterOps/bloodhound-docs PR: 67
File: docs/collect-data/enterprise-collection/privileged-collection.mdx:7-7
Timestamp: 2025-10-02T18:01:39.059Z
Learning: In the BloodHound documentation repository, "BloodHound" as a standalone name refers to the entire product family and is appropriate to use when content applies to all products in the family (Enterprise and Community Edition). "BloodHound Enterprise" should be used only when referring specifically to Enterprise-only features or capabilities.
Applied to files:
docs/install-data-collector/install-azurehound/create-configuration.mdx
🔇 Additional comments (5)
docs/install-data-collector/install-azurehound/create-configuration.mdx (2)
102-202: Dual-path authentication flow is well-structured.The tab-based separation of Managed Identity (recommended, lines 108–153) and Certificate (lines 155–200) authentication methods provides clear guidance. Both paths include:
- Clear prompts showing expected CLI output
- Step-by-step navigation
- Links to supporting documentation (e.g., line 140, 174–180)
- Consistent BloodHound Enterprise URL entry (lines 148–152, 195–199)
The Managed Identity tab appropriately emphasizes that configuration requires prior identity creation (line 112), and both tabs flow naturally into the collector client configuration step that follows.
6-6: Import verified and file is correctly available.The managed identity recommendation snippet at
/snippets/hounds/managed-id-recommendation.mdxexists and is properly imported. The component is correctly rendered at line 110 in the Managed Identity tab. No issues found.docs/install-data-collector/install-azurehound/azure-configuration.mdx (3)
42-51: Strong role-based access guidance for app registration creation.Lines 42–51 clearly specify required Microsoft Entra admin center roles (Global Administrator, or Privileged Role Administrator + Application Administrator/Cloud Application Administrator) with inline links to Microsoft role definitions. This guidance prevents common permission-related configuration failures.
93-184: API permissions assignment section is clear and well-structured.The steps correctly guide users to:
- Remove the unnecessary default User.Read permission (lines 106–117)
- Add both required Microsoft Graph permissions with visual aids (lines 119–154)
- Grant admin consent and verify completion (lines 156–182)
The guidance aligns with learnings that Microsoft Graph permissions require admin consent, and includes frames showing expected UI state at each step, which reduces configuration errors.
6-6: Managed identity recommendation snippet is correctly referenced and rendered.The import at line 6 correctly references
/snippets/hounds/managed-id-recommendation.mdx, the file exists with appropriate content, and the component is properly rendered at line 206 in the Managed Identity subsection. The snippet content aligns with the intended recommendation about User-Assigned Managed Identity.
jeff-matthews
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/install-data-collector/install-azurehound/create-configuration.mdx`:
- Line 22: In the row that begins with "**Certificate and private key**",
replace the word "identifies" with wording that conveys authentication use
(e.g., "used to authenticate the AzureHound Enterprise application") so the
sentence reads that the certificate and private key are used to authenticate the
application; keep the rest of the sentence and the note about the CLI generating
the key unchanged.
🧹 Nitpick comments (1)
docs/install-data-collector/install-azurehound/create-configuration.mdx (1)
264-277: Consider clarifying the configuration summary for Managed Identity authentication.The example output shows certificate-related files (
key.pem,cert.pem) and the message "Ensure certificate is uploaded...", but this only applies to Certificate authentication. Users who configured Managed Identity may see different output. Consider either:
- Adding a separate example for Managed Identity authentication, or
- Adding a note before the example clarifying this shows Certificate authentication output.
| | **AzureHound token** | Provides the authentication key for the AzureHound Enterprise [collector client](/collect-data/enterprise-collection/create-collector) that you must create in BloodHound Enterprise. | | ||
| | **BloodHound Enterprise URL** | The URL of your BloodHound Enterprise tenant (for example, `https://enterprise.bloodhoundenterprise.io/`). | | ||
| | **Managed Identity Client ID** | If using [Azure Managed Identity](/install-data-collector/install-azurehound/azure-configuration#managed-identity-recommended) authentication, identifies the Managed Identity assigned to the Entra ID [app registration](/install-data-collector/install-azurehound/azure-configuration). | | ||
| | **Certificate and private key** | If using [Certificate](/install-data-collector/install-azurehound/azure-configuration#certificate) authentication, identifies the certificate and private key to authenticate the AzureHound Enterprise application. The AzureHound Enterprise CLI tool can generate this for you during the configuration process if needed. | |
There was a problem hiding this comment.
Minor wording issue: "identifies" doesn't fit this context.
The certificate doesn't "identify" itself—it's used to authenticate. Consider rewording for clarity.
-| **Certificate and private key** | If using [Certificate](/install-data-collector/install-azurehound/azure-configuration#certificate) authentication, identifies the certificate and private key to authenticate the AzureHound Enterprise application. The AzureHound Enterprise CLI tool can generate this for you during the configuration process if needed. |
+| **Certificate and private key** | If using [Certificate](/install-data-collector/install-azurehound/azure-configuration#certificate) authentication, the certificate and private key used to authenticate the AzureHound Enterprise application. The AzureHound Enterprise CLI tool can generate this for you during the configuration process if needed. |🤖 Prompt for AI Agents
In `@docs/install-data-collector/install-azurehound/create-configuration.mdx` at
line 22, In the row that begins with "**Certificate and private key**", replace
the word "identifies" with wording that conveys authentication use (e.g., "used
to authenticate the AzureHound Enterprise application") so the sentence reads
that the certificate and private key are used to authenticate the application;
keep the rest of the sentence and the note about the CLI generating the key
unchanged.
1 participant
Purpose
This pull request (PR) adds documentation for configuring the Azure Managed Identity authentication option for AzureHound data collection (introduced in v8.3.0).
Some end-to-end testing is still required to validate, but I may need some help from Engineering with that (or someone who has configured an AzureHound collector before).
Note
The new section intentionally directs users to the relevant Microsoft docs rather than reproducing that content in our docs because I didn't identify any unique BloodHound nuances that would otherwise require it.
Additional info
StepcomponentStaging
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.