> ## Documentation Index
> Fetch the complete documentation index at: https://bloodhound.specterops.io/llms.txt
> Use this file to discover all available pages before exploring further.
# AzureHound Enterprise Azure Configuration
> This section details creating and configuring an Enterprise Application for AzureHound within Microsoft Entra ID, including API permissions, roles, and authentication certificate.
## Create the AzureHound Enterprise app
1. Log into the [Microsoft Entra admin center](https://entra.microsoft.com/) as a user with the [Global Administrator] role,
or the following less privileged roles:
* [Privileged Role Administrator] AND
* [Application Administrator] OR [Cloud Application Administrator]
[Global Administrator]: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#global-administrator
[Privileged Role Administrator]: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#privileged-role-administrator
[Cloud Application Administrator]: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator
[Application Administrator]: https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#application-administrator
2. In the left menu, select **App registrations**.
3. Click **New registration**.
4. In the **Name** field, give the application an identifying name in your organization. Make sure the supported account type is set to the "Accounts in this organizational directory only (Single tenant)" option. A URI is not required. Then click **Register**.
5. In the **Overview** menu, copy the **Application (client) ID** and **Directory (tenant) ID** to be used later in [AzureHound Enterprise Local Configuration](/install-data-collector/install-azurehound/create-configuration).
6. Continue to the next section: "Grant Microsoft Graph Permissions".
## Grant Microsoft Graph Permissions
1. In the AzureHound application, select **API Permissions**.
2. Remove the default **User.Read** delegated permission from the application, as it is not needed for data collection. Confirm the operation in the dialog window that appears after selecting the **Remove permission** option from the context menu.
3. Select **Add a permission**.
4. Click on **Microsoft Graph**.
5. Select **Application permissions**.
6. Search for the **Directory.Read.All** permission and check the box next to it.
7. Search for the **RoleManagement.Read.All** permission and check the box next to it.
8. (Optional step to collect AZUser.LastSuccessfulSignInDateTime) Search for the **AuditLog.Read.All** permission and check the box next to it.
9. In the bottom of the window, select **Add permissions**.
10. Click on **Grant admin consent for \**.
11. Click **Yes** on the confirmation dialog.
12. After being redirected to API Permissions again, you should see both permissions as **Granted**.
13. Continue to the next section: "Add application authentication certificate".
## Add application authentication certificate
This section requires you have authentication material.
We highly recommend using certificate-based authentication. If you do not already have a certificate created, follow the article [AzureHound Enterprise Local Configuration](/install-data-collector/install-azurehound/create-configuration) and then return back here.
1. Select the **Certificates & secrets** section on the left.
2. Click on **Certificates**.
3. Click **Upload certificate**.
4. Locate the **cert.pem** file created during AzureHound setup (either on your own, or utilizing the instructions at [AzureHound Enterprise Local Configuration](/install-data-collector/install-azurehound/create-configuration)).
5. Click the folder icon and locate the "cert.pem" file. Add a description if desired.
6. In the bottom of the window, select **Add**.
7. Continue to the next section to optionally configure application branding.
## Configure application branding (optional)
*Note: All steps in this section are optional and do not affect the functionality of the collector.*
1. Download the [AzureHound Enterprise icon](/assets/icons/entra-bhe-app-icon.png) to your computer.
2. Still on the AzureHound application in the Entra ID admin center, open the **Branding & properties** section.
3. Click the **Select a file** button and browse to the file you previously downloaded.
4. Provide a human-readable **Name** for the application, e.g., **BloodHound Enterprise Collector (AzureHound)**.
5. Type your BloodHound Enterprise tenant URL into the **Home page URL** field. This is for record keeping only.
6. Click the **Save** button and review the results.
7. Continue to the next section to assign the Directory Readers role on your Entra ID tenant.
## Assign "Directory Readers" role on the Entra ID tenant
1. In the left menu, select **Roles & admins**.
2. Search for the role **Directory Readers** and click the role name or description.
*Note: Clicking the checkbox sometimes prevents clicking on the role itself.*
3. In the "Directory Readers" role, select **Add assignments**.
4. Click **No member selected** to open the search window.
5. Search for the previously created service principal with either its name, application ID, or object ID. Select it by clicking on it.
6. Click **Select**.
7. Validate that your principal is displayed and click **Next**.
8. Ensure that the Assignment type is **Active** and the **Permanently assigned** box is checked. Provide a justification and click **Assign**.
9. Confirm the service principal is a Directory Reader by refreshing this view.
10. Continue to the next section to assign the Reader role on your Azure subscriptions.
## Grant "Reader" role on all Azure subscriptions
*Note: 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. If you skip this section, you will see a warning in the logs for each collection indicating the lack of ability to collect this data accordingly.*
1. Log into the [Azure portal](https://portal.azure.com/) as a user with the [User Access Administrator](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles/privileged#user-access-administrator) role.
2. Search for and select the **Management groups** item in the top search bar.
3. Select **Tenant Root Group**.
4. Select **Access control (IAM)**.
5. Select **Role assignments**.
6. Click **Add**, then **Add role assignment**.
7. Find the **Reader** role and select it.
8. Click **Members**.
9. Click **Select members**.
10. Search for and click on your previously created service principal.
11. Validate the principal selected, then click **Select**.
12. Click the tab **Review + Assign**.
13. Click **Review + Assign** at the bottom of the page.
14. Confirm the role is present by refreshing this view. You may need to alter the filter to see this role.
15. Continue to [Run and Upgrade AzureHound (Windows, Docker, or Kubernetes)](/install-data-collector/install-azurehound/installation-options)
## Scripted app registration
As an alternative to the manual app registration process described in this document, you can use **PowerShell** to achieve the same.
Below is a sample PowerShell script that performs all the required steps,
with the exception of [configuring the authentication certificate](#add-application-authentication-certificate).
```powershell theme={null}
<#
.SYNOPSIS
Registers the Azure Data Exporter for BloodHound Enterprise (AzureHound)
as an application in Entra ID.
.DESCRIPTION
This script registers the Azure Data Exporter for BloodHound Enterprise (AzureHound)
as an on-prem application in Microsoft Entra ID and Azure,
including all the necessary read permissions.
The required PowerShell modules can be installed
from the PowerShell Gallery using the following command:
Install-Module -Scope AllUsers -Repository PSGallery -Force -Name @(
Microsoft.Graph.Applications,
Microsoft.Graph.Authentication,
Microsoft.Graph.Identity.DirectoryManagement,
Az.Resources,
Az.Accounts
)
.NOTES
Version: 1.1
#>
#Requires -Version 5
#Requires -Modules Microsoft.Graph.Applications,Microsoft.Graph.Authentication
#Requires -Modules Microsoft.Graph.Identity.DirectoryManagement
#Requires -Modules Az.Resources,Az.Accounts
#region Entra ID
# Connect to Microsoft Entra ID through the Microsoft Graph API
# Note: The -TenantId parameter is also required when using an External ID.
Connect-MgGraph -NoWelcome -ContextScope Process -Scopes @(
'User.Read',
'Application.ReadWrite.All',
'AppRoleAssignment.ReadWrite.All',
'RoleManagement.ReadWrite.Directory'
)
# Register the AzureHound application
[string] $appName = 'BloodHound Enterprise Collector'
[string] $appDescription =
'Azure Data Exporter for BloodHound Enterprise (AzureHound)'
# TODO: Optionally provide the actual URL your BloodHound Enterprise tenant
[string] $homePage = 'https://specterops.io/bloodhound-enterprise'
[hashtable] $infoUrls = @{
MarketingUrl = 'https://specterops.io/bloodhound-enterprise'
TermsOfServiceUrl = 'https://specterops.io/terms-of-service'
PrivacyStatementUrl = 'https://specterops.io/privacy-policy'
SupportUrl = 'https://support.bloodhoundenterprise.io/'
}
[hashtable] $webUrls = @{
HomePageUrl = $homePage
}
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphApplication] $registeredApp =
New-MgApplication -DisplayName $appName `
-Description $appDescription `
-Info $infoUrls `
-Web $webUrls `
-SignInAudience 'AzureADMyOrg'
# Configure the application logo
[string] $logoUrl =
'https://bloodhound.specterops.io/assets/icons/entra-bhe-app-icon.png'
[string] $tempLogoPath = New-TemporaryFile
Invoke-WebRequest -Uri $logoUrl `
-OutFile $tempLogoPath `
-UseBasicParsing `
-ErrorAction Stop
try {
Set-MgApplicationLogo -ApplicationId $registeredApp.Id `
-ContentType 'image/png' `
-InFile $tempLogoPath
}
finally {
# Delete the local copy of the logo from temp
Remove-Item -Path $tempLogoPath
}
# Make sure the app instance property lock is enabled
Update-MgApplication `
-ApplicationId $registeredApp.Id `
-ServicePrincipalLockConfiguration @{
IsEnabled = $true
AllProperties = $true
}
# Create the associated service principal object
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphServicePrincipal] $servicePrincipal =
New-MgServicePrincipal -DisplayName $appName `
-AppId $registeredApp.AppId `
-AccountEnabled `
-ServicePrincipalType Application `
-Notes $appDescription `
-Homepage $homePage `
-Tags 'WindowsAzureActiveDirectoryIntegratedApp','HideApp'
# Fetch the Microsoft Graph applicaton ID,
# which should be 00000003-0000-0000-c000-000000000000
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphServicePrincipal] $microsoftGraph =
Get-MgServicePrincipal -Filter "DisplayName eq 'Microsoft Graph'"
# Fetch the Directory.Read.All scope ID,
# which should be 7ab1d382-f21e-4acd-a863-ba3e13f7da61
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphAppRole] $readDirectoryScope =
$microsoftGraph.AppRoles | Where-Object Value -eq 'Directory.Read.All'
# Fetch the RoleManagement.Read.All scope ID,
# which should be c7fbd983-d9aa-4fa7-84b8-17382c103bc4
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphAppRole] $readRolesScope =
$microsoftGraph.AppRoles | Where-Object Value -eq 'RoleManagement.Read.All'
# Delegate the required API permissions
Update-MgApplication -ApplicationId $registeredApp.Id -RequiredResourceAccess @{
ResourceAppId = $microsoftGraph.AppId # 00000003-0000-0000-c000-000000000000
ResourceAccess = @(@{
id = $readDirectoryScope.Id # 7ab1d382-f21e-4acd-a863-ba3e13f7da61
type = 'Role'
},@{
id = $readRolesScope.Id # c7fbd983-d9aa-4fa7-84b8-17382c103bc4
type = 'Role'
})
}
# Approve the permissions on the tenant
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphAppRoleAssignment] $readRolesAdminConsent =
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $servicePrincipal.Id `
-PrincipalId $servicePrincipal.Id `
-ResourceId $microsoftGraph.Id `
-AppRoleId $readRolesScope.Id
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphAppRoleAssignment] $readDirectoryAdminConsent =
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $servicePrincipal.Id `
-PrincipalId $servicePrincipal.Id `
-ResourceId $microsoftGraph.Id `
-AppRoleId $readDirectoryScope.Id
# Fetch the template ID of the Directory Readers role,
# which should be 88d8e3e3-8f55-4a1e-953a-9b9898b8876b
[Microsoft.Graph.PowerShell.Models.MicrosoftGraphDirectoryRole] $directoryReadersRole =
Get-MgDirectoryRole -Filter "displayName eq 'Directory Readers'"
# Get the environment-specific Microsoft Graph API endpoint
# Azure Global: https://graph.microsoft.com
# Azure USGov: https://graph.microsoft.us
[string] $graphEndpoint =
(Get-MgEnvironment -Name (Get-MgContext).Environment).GraphEndpoint
# OData IDs need to be used when assigning role membership,
# e.g., https://graph.microsoft.com/v1.0/serviceprincipals/{46615ae4-da39-4403-8de2-606e10774ae0}
[string] $servicePrincipalOdataId =
"$graphEndpoint/v1.0/serviceprincipals/{$($servicePrincipal.Id)}"
# Assign the Directory Readers Entra ID Role to the service principal
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $directoryReadersRole.Id `
-OdataId $servicePrincipalOdataId
# Fetch the info about the current user
[Microsoft.Graph.PowerShell.Models.IMicrosoftGraphDirectoryObject] $currentUser =
Invoke-MgGraphRequest -Method GET -Uri '/v1.0/me'
# OData IDs need to be used when assigning application ownership,
# e.g., https://graph.microsoft.com/v1.0/users/{bca3617a-4c54-45eb-9a32-744c1938242e}
[string] $currentUserOdataId = "$graphEndpoint/v1.0/users/{$($currentUser.Id)}"
# Assign the current user as the application object owner
New-MgApplicationOwnerByRef -ApplicationId $registeredApp.Id `
-OdataId $currentUserOdataId
# Assign the current user as the service principal owner
New-MgServicePrincipalOwnerByRef -ServicePrincipalId $servicePrincipal.Id `
-OdataId $currentUserOdataId
# Sign out from Microsoft Graph
Disconnect-MgGraph | Out-Null
#endregion Entra ID
#region Azure (Optional)
# Optionally enable browser-based login on Windows 10 and later
Update-AzConfig -EnableLoginByWam $false
# Authenticate against Azure Resource Manager
Connect-AzAccount -Environment AzureCloud -Scope Process
# Fetch the identifier of the Reader role
[string] $rootScope = '/'
[Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition] $azureReaderRole =
Get-AzRoleDefinition -Scope $rootScope -Name 'Reader'
if (-not (Test-Path -Path 'variable:servicePrincipal')) {
# Fetch the service principal if the Azure part of the script is executed independently
[Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.IMicrosoftGraphServicePrincipal] $servicePrincipal =
Get-AzADServicePrincipal -DisplayName 'BloodHound Enterprise Collector'
}
# Fetch the Tenant Root Group
[guid] $currentTenantId = (Get-AzContext).Tenant.Id
[Microsoft.Azure.Commands.Resources.Models.ManagementGroups.PSManagementGroup] $rootManagementGroup =
Get-AzManagementGroup -GroupName $currentTenantId
# Assign the Reader role on all Azure subscriptions to AzureHound
[Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleAssignment] $readerRoleAssignment =
New-AzRoleAssignment -ObjectId $servicePrincipal.Id `
-Scope $rootManagementGroup.Id `
-RoleDefinitionId $azureReaderRole.Id
# Sign out from Azure Resource Manager
Disconnect-AzAccount -Scope Process
#endregion Azure (Optional)
```