Azure

Automated Set up via PowerShell Script

We have created a PowerShell script that eliminates the need to create the app registration manually. You can find it here.

Experienced with Azure? Here’s a quick summary to get started:

1. Create App Registration
2. Add Permissions for various services:
   • AuditLog: AuditLog.Read.All (Read all audit log data)
   • DeviceManagementConfiguration: DeviceManagementConfiguration.Read.All (Read Microsoft Intune device configurations and policies)
   • DeviceManagementManagedDevices: DeviceManagementManagedDevices.Read.All (Read Microsoft Intune devices)
   • Directory: Directory.Read.All (Read Azure AD data)
   • Reports: Reports.Read.All (Read all usage reports)
   • AdvancedQuery: AdvancedQuery.Read.All (365 Defender)
   • Machine: Machine.Read.All (365 Defender)
   • SharePoint: Sites.Read.All (Read SharePoint data)
   • Teams: Team.ReadBasic.All (Read Teams data)
3. Grant Permissions to the subscriptions you want to inventory.

Set up App registration in Azure

To inventory Azure Resource Manager (Azure RM), vScope needs read permissions for your subscriptions. This guide walks through creating an app in Azure and generating a key.

Prerequisite

Ensure you have permissions to set up applications in Azure. Learn more about roles and permissions here.

Create an App registration

Log in to Azure Resource Manager, search for App registrations, and select it.

Click + New registration to create the vScope application.

Name the application (e.g., vScope), choose Accounts in this organizational directory only, and click Register.

Add API Permissions for Microsoft Graph

In the API Permissions section, click + Add a permission.

Under Microsoft APIs, select Microsoft Graph.

Select Application permissions.

Choose the following permissions and click Add permissions:

• AuditLog: AuditLog.Read.All (Read all audit log data)
• DeviceManagementConfiguration: DeviceManagementConfiguration.Read.All (Read Microsoft Intune device configurations and policies)
• DeviceManagementManagedDevices: DeviceManagementManagedDevices.Read.All (Read Microsoft Intune devices)
• Directory: Directory.Read.All (Read Azure AD data)
• Reports: Reports.Read.All (Read all usage reports)

Grant these permissions by clicking Grant admin consent.

Add API Permissions for Defender

Click + Add a permission again.

Select APIs my organization uses and search for WindowsDefenderATP.

Under Application permissions, enable AdvancedQuery.Read.All in the AdvancedQuery section and Machine.Read.All in the Machine section, then click Add permissions.

Click Grant admin consent to finalize permissions.

Grant Access to Subscriptions

If you have Azure resources to inventory, such as App Services or storage accounts, grant subscription access. Search for Subscriptions and click the key icon.

Select the subscription name.

In Access Control (IAM), click Add role assignment.

Under the Role tab, select Reader.

On the Members tab, confirm the Reader role, then click + Select members.

Enter the application name created in Create an App Registration 1 (e.g., vScope) in the search bar and click Select.

Click Review + assign to save.

Automated set up with PowerShell

This script creates a tenant-local app registration for vScope, grants required Microsoft Graph and Defender application permissions, admin-consents them, and optionally assigns Azure RBAC Reader.

Requirements:

• PowerShell 7+

• Global Admin / Privileged Role Admin / Cloud App Admin

• Modules:

  Install-Module Microsoft.Graph -Scope CurrentUser

  Install-Module Az.Accounts,Az.Resources -Scope CurrentUser # only if using RBAC auto-assign

Step-by-step instructions:

1. Make sure you have an account with the Global Administrator role in Microsoft Entra ID.
2. Open PowerShell on your computer.
3. Install the required modules if they aren’t already installed.
4. Copy the provided script and save it as a .ps1 file on your computer (e.g., myscript.ps1).
5. From the PowerShell terminal, navigate to the folder where you saved the script.
6. Run the script using the usage example provided. The -RbacScope parameter is optional.

Usage example:

.\script.ps1 -DisplayName "vScope App Registration" -GenerateClientSecret
Optional parameter: -RbacScope "/subscriptions/subscription-id"

PowerShell script:

param(
  [Parameter(Mandatory=$true)]
  [string]$DisplayName,

  [switch]$GenerateClientSecret,

  [string]$RbacScope = $null,

  [string]$AzRoleDefinitionName = "Reader"
)

# --------------------------------------------------------
# 📋 Step 1: Define Required Permission Sets
# --------------------------------------------------------

$GraphAppPermissions = @(
  "AuditLog.Read.All",
  "DeviceManagementConfiguration.Read.All",
  "DeviceManagementManagedDevices.Read.All",
  "Directory.Read.All",
  "Reports.Read.All",
  "Sites.Read.All"
)

$DefenderAppPermissions = @(
  "AdvancedQuery.Read.All",
  "Machine.Read.All"
)

# --------------------------------------------------------
# 🎯 Step 2: Connect to Microsoft Graph
# --------------------------------------------------------

Write-Host "Connecting to Microsoft Graph..." -ForegroundColor Cyan
$scopes = @(
  "Application.ReadWrite.All",
  "AppRoleAssignment.ReadWrite.All"
)
Connect-MgGraph -Scopes $scopes | Out-Null

# --------------------------------------------------------
# 🛠️ Step 3: Create the Application and Service Principal
# --------------------------------------------------------

Write-Host "Creating application '$DisplayName'..." -ForegroundColor Cyan
$app = New-MgApplication -DisplayName $DisplayName
$sp  = New-MgServicePrincipal -AppId $app.AppId
Write-Host "App created. AppId: $($app.AppId)" -ForegroundColor Green

# --------------------------------------------------------
# 🔑 Step 4: Optionally Create a Client Secret
# --------------------------------------------------------

$secretValue = $null
if ($GenerateClientSecret.IsPresent) {
  Write-Host "Creating client secret (shown once)..." -ForegroundColor Yellow
  $pwd = Add-MgApplicationPassword -ApplicationId $app.Id -PasswordCredential @{ displayName = "ApplicationSecret" }
  $secretValue = $pwd.SecretText
}

# --------------------------------------------------------
# ⚙️ Step 5: Resolve Resource Service Principals
# --------------------------------------------------------

function Get-ResourceSp {
  param([string]$WellKnownAppId, [string]$FallbackDisplayName)
  $spn = $null
  if ($WellKnownAppId) { $spn = Get-MgServicePrincipal -Filter "appId eq '$WellKnownAppId'" }
  if (-not $spn -and $FallbackDisplayName) { $spn = Get-MgServicePrincipal -Filter "displayName eq '$FallbackDisplayName'" }
  return $spn
}

$graphSp = Get-ResourceSp -WellKnownAppId "00000003-0000-0000-c000-000000000000" -FallbackDisplayName "Microsoft Graph"
if (-not $graphSp) { throw "Could not find Microsoft Graph service principal in this tenant." }

$defenderSp = Get-ResourceSp -WellKnownAppId $null -FallbackDisplayName "WindowsDefenderATP"
if (-not $defenderSp) { Write-Warning "WindowsDefenderATP service principal not found. The Defender permissions step will be skipped."; $DefenderAppPermissions = @() }

# --------------------------------------------------------
# 🛡️ Step 6: Grant Application Permissions
# --------------------------------------------------------

function Grant-AppRole {
  param(
    [Microsoft.Graph.PowerShell.Models.MicrosoftGraphServicePrincipal]$ResourceSp,
    [string]$RoleValue
  )
  $role = $ResourceSp.AppRoles | Where-Object { $_.Value -eq $RoleValue -and $_.AllowedMemberTypes -contains "Application" -and $_.IsEnabled }
  if (-not $role) { throw "App role '$RoleValue' not found on resource '$($ResourceSp.DisplayName)'." }
  New-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $sp.Id -BodyParameter @{
    principalId = $sp.Id
    resourceId  = $ResourceSp.Id
    appRoleId   = $role.Id
  } | Out-Null
  Write-Host "Granted application permission '$RoleValue' on '$($ResourceSp.DisplayName)'." -ForegroundColor Green
}

Write-Host "Granting Microsoft Graph application permissions..." -ForegroundColor Cyan
foreach ($perm in $GraphAppPermissions) { Grant-AppRole -ResourceSp $graphSp -RoleValue $perm }

if ($DefenderAppPermissions.Count -gt 0) {
  Write-Host "Granting Defender for Endpoint application permissions..." -ForegroundColor Cyan
  foreach ($perm in $DefenderAppPermissions) { Grant-AppRole -ResourceSp $defenderSp -RoleValue $perm }
}

# --------------------------------------------------------
# 🌐 Step 7: Optional Azure RBAC Assignment
# --------------------------------------------------------

if ($RbacScope) {
  Write-Host "Assigning Azure RBAC role '$AzRoleDefinitionName' at scope $RbacScope ..." -ForegroundColor Cyan
  try {
    try { Get-AzContext | Out-Null } catch { Connect-AzAccount | Out-Null }
    New-AzRoleAssignment -ObjectId $sp.Id -RoleDefinitionName $AzRoleDefinitionName -Scope $RbacScope | Out-Null
    Write-Host "Azure RBAC role assigned." -ForegroundColor Green
  } catch {
    Write-Warning "Failed to assign Azure RBAC role. Assign later in Portal > Access control (IAM). Error: $($_.Exception.Message)"
  }
}

# --------------------------------------------------------
# 📋 Step 8: Output Configuration Summary
# --------------------------------------------------------

$summary = [pscustomobject]@{
  TenantId            = (Get-MgContext).TenantId
  ApplicationName     = $app.DisplayName
  ApplicationId       = $app.AppId
  ServicePrincipalId  = $sp.Id
  ClientSecret        = $secretValue
  NextSteps           = "Use TenantId, ApplicationId (ClientId) and ClientSecret (or cert) in vScope's Azure RM credential."
}
$summary | Format-List

Set up the Azure RM Probe in vScope

In Azure’s Overview section, copy the Application (client) ID.

Open vScope, navigate to Discovery Manager, create an Azure RM probe (+ Credential), and paste the Application ID.

Go to Certificates & secrets in Azure, then click + New client secret.

Add a description (e.g., vScope), select an expiry date, and click Add.

Copy the client secret value immediately (it will only be shown once) and paste it into the Key field in vScope.

Click Test Credential in vScope. If it’s successful, the indicator should turn green.

Good job! You are now ready to inventory Azure Resource Manager.

Matching Local and Azure Domains

After discovering Azure Resource Manager, we recommend checking out Suggestions under Discovery > Suggestions. Here, you can enhance vScope’s data quality by defining rules that improve how assets are identified.

Caution

Be careful when selecting domains. Incorrect matches may cause vScope to merge unrelated assets into a single asset.

For Azure, it is common to have different domain names in the local Active Directory compared to Azure and Microsoft Entra ID. To help vScope interpret this correctly, you should create a Custom suggestion.

• From the dropdown, select the domains that you consider equivalent (e.g., infrasightlabs.com and isl.com).
• Click Apply to save.
• Rerun a Discovery.

Once applied, and after running next discovery, vScope will recognize these domains as the same, improving its ability to identify unique and duplicate assets accurately.

Common Errors

Error	What happened?	Suggested action
Failed to retrieve…	vScope was not able to retrieve data using the specified API endpoint.	Confirm that the vScope Azure application has the correct API permissions.
SSLHandshakeException	An issue connecting to Azure.	Ensure the connection between vScope and Azure is properly configured.
java.lang.RunTimeException: Found Duplicate ID’s	Microsoft Graph API returns identical values	May be resolved by itself depending on what the Microsoft Graph API returns