The error code RoleAssignmentRequestAcrsValidationFailed, followed by the failed claim claims=%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%20%22value%22%3A%22c1%22%7D%7D%7D (unescaped it looks like this claims={"access_token":{"acrs":{"essential":true, "value":"c1"}}}) means the method used for authenticating the current session isn’t sufficient to run the selected action.

For me, it was when I activated the PIM-protected Azure Directory Role that required FIDO2 (Passkey) authentication strength (enforced via Azure Conditional Access Policy).

Anyway, if something like this happens, you need to reauthenticate using the failed claim and repeat the action.

How to authenticate to Azure/Graph with PowerShell using a specific claim

How to authenticate using a specific claim slightly differs based on the accessed service.

Making an Azure connection

• We need to extract the claim from the Invoke-AzRestMethod response body

• Unescape the HTML string and convert it to base64

• Use such a claim in the Claims parameter of the Connect-AzAccount to fulfill interactively auth requirements

# invoke some request that needs extra claim (FIDO2)
$response = Invoke-AzRestMethod -Uri $restUri -Method PUT -Payload ($requestBody | ConvertTo-Json -Depth 10)

# when PIM requires FIDO/Passkey or specific MFA, the API returns 400 with a claims challenge
$exception = ($response.Content | ConvertFrom-Json).error.message

# reauthenticate using claim challenge
if ($exception -and $exception -match 'claims=([^"]+)') {
    $claimsChallenge = $matches[1]
    $claimsChallenge = [System.Uri]::UnescapeDataString($claimsChallenge)

    Write-Verbose "Claims challenge detected: $claimsChallenge"

    # convert plaintext claim to base64
    $bytes = [System.Text.Encoding]::ASCII.GetBytes($claimsChallenge)
    $encodedClaimsChallenge = [Convert]::ToBase64String($bytes)
    #TIP tenant parameter is required to avoid error: WARNING: Unable to acquire token for tenant '<tenantid>' with error 'InteractiveBrowserCredential authentication failed: Redirect Uri mismatch.  Expected (/favicon.ico) Actual (/). '
    $null = Connect-AzAccount -Claims $encodedClaimsChallenge -Tenant (Get-AzContext).tenant.id -ErrorAction Stop -WarningAction SilentlyContinue
}

# now you can retry failed request
Write-Verbose "Retrying activation request..."
$response = Invoke-AzRestMethod -Uri $restUri -Method PUT -Payload ($requestBody | ConvertTo-Json -Depth 10)

Making a Graph connection (with default scopes)

• It’s very similar to making just an Azure connection, with a slight difference. The claim is saved in the error message instead of the response body (when using Invoke-MgGraphRequest)

• And you need to reauthenticate to the Graph api after new access token retrieval

try {
    $uri = "v1.0/roleManagement/directory/roleAssignmentScheduleRequests"
    $response = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ErrorAction Stop
} catch {
    # When PIM requires FIDO/Passkey or specific MFA, the API returns 403 with a claims challenge.
    $exception = $_.ErrorDetails.Message

    # reauthenticate using claim challenge
    if ($exception -and $exception -match 'claims=([^"]+)') {
        $claimsChallenge = $matches[1]
        $claimsChallenge = [System.Uri]::UnescapeDataString($claimsChallenge)

        Write-Verbose "Claims challenge detected: $claimsChallenge"

        # convert plaintext claim to base64
        $bytes = [System.Text.Encoding]::ASCII.GetBytes($claimsChallenge)
        $encodedClaimsChallenge = [Convert]::ToBase64String($bytes)
        #TIP tenant parameter is required to avoid error: WARNING: Unable to acquire token for tenant '<tenantid>' with error 'InteractiveBrowserCredential authentication failed: Redirect Uri mismatch.  Expected (/favicon.ico) Actual (/). '
        $null = Connect-AzAccount -Claims $encodedClaimsChallenge -Tenant (Get-AzContext).tenant.id -ErrorAction Stop -WarningAction SilentlyContinue
    }

    # Re-connect Graph SDK using the Strong Token
    $secureToken = (Get-AzAccessToken -ResourceTypeName MSGraph).Token
    Connect-MgGraph -AccessToken $secureToken -NoWelcome

    Write-Verbose "Retrying activation request..."
    $response = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ErrorAction Stop
}

Making a Graph connection (with specific scopes)

• It again starts with the Azure reauthentication

• But because we have to specify custom Graph api scopes, we cannot use Connect-AzAccount to retrieve the access token

• Instead, we will need:

  • A list of required Graph Api scopes ($scope)

    • (RoleAssignmentSchedule.ReadWrite.Directory to activate the PIM role)

  • To import the Microsoft.Identity.Client.dll library to be able to create a web request with the required scopes using [Microsoft.Identity.Client.PublicClientApplicationBuilder]

  • To have a claim JSON string ($claim)

    • can look like '{"access_token":{"acrs":{"essential":true, "value":"c1"}}}'

      • c1 is the ID of the authentication context defined in Azure Conditional Access policies

So, to authenticate using the specified claim, use Get-PIMGraphTokenWithClaim function from my AzurePIMStuff module.

$claimsChallenge = "<claim>"
# create new auth token
$secureToken = Get-PIMGraphTokenWithClaim -Claim $claimsChallenge
# re-connect Graph SDK using the Strong Token
Connect-MgGraph -AccessToken $secureToken -NoWelcome

Or if you need a different kind of scopes, etc, create the request using the following code

#region prepare
$clientId = "14d82eec-204b-4c2f-b7e8-296a70dab67e" # "Microsoft Graph PowerShell" application ID
$scope = "<list of required scopes>"
# for actiovation of the PIM roles you will require "RoleAssignmentSchedule.ReadWrite.Directory"
$scope += "RoleAssignmentSchedule.ReadWrite.Directory"
# acrs == Authentication context
# c1 == id of the authentication context defined in Azure Conditional Access policies
$claim = '{"access_token":{"acrs":{"essential":true, "value":"c1"}}}'
#endregion prepare

#region authenticate using given claims
# Load Microsoft.Identity.Client.dll Assembly ([Microsoft.Identity.Client.PublicClientApplicationBuilder] type) from Az.Accounts module
if (!("Microsoft.Identity.Client.PublicClientApplicationBuilder" -as [Type])) {
    # to avoid dll conflicts try loaded modules first
    $modulePath = (Get-Module Az.Accounts | Sort-Object Version -Descending | Select-Object -First 1).ModuleBase

    if (!$modulePath) {
        $modulePath = (Get-Module Az.Accounts -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1).ModuleBase
    }
    if ($modulePath) {
        $dllPath = Get-ChildItem -Path $modulePath -Filter "Microsoft.Identity.Client.dll" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1
        if ($dllPath) {
            Add-Type -Path $dllPath.FullName
        } else {
            throw "Microsoft.Identity.Client.dll not found in Az.Accounts module."
        }
    } else {
        throw "No Az.Accounts module found. Please install the Az PowerShell module."
    }
}

# Build Public Client App
$pca = [Microsoft.Identity.Client.PublicClientApplicationBuilder]::Create($clientId).WithAuthority("https://login.microsoftonline.com/$tenantId").WithRedirectUri("http://localhost").Build()

# Create Interactive Request
$request = $pca.AcquireTokenInteractive($scope)

$request = $request.WithClaims($claim)

# Execute and return Token
$token = $request.ExecuteAsync().GetAwaiter().GetResult().AccessToken
$secureToken = ConvertTo-SecureString $token -AsPlainText -Force
#endregion authenticate using given claims

# Re-connect Graph SDK using the Strong Token
Connect-MgGraph -AccessToken $secureToken -NoWelcome

How to retrieve the claim

How to retrieve the claim of the failed request depends on the used command

Invoke-AzRestMethod

• Invoke-AzRestMethod stores the claim challenge in the response body

# invoke some request that needs extra claim (FIDO2)
$response = Invoke-AzRestMethod -Uri $restUri -Method PUT -Payload ($requestBody | ConvertTo-Json -Depth 10)

# when PIM requires FIDO/Passkey or specific MFA, the API returns 400 with a claims challenge
$exception = ($response.Content | ConvertFrom-Json).error.message

if ($exception -and $exception -match 'claims=([^"]+)') {
    $claimsChallenge = $matches[1]
    $claimsChallenge = [System.Uri]::UnescapeDataString($claimsChallenge)

    $claimsChallenge
}

Invoke-MgGraphRequest

• Invoke-MgGraphRequest stores the claim challenge in the thrown error object

try {
    $uri = "v1.0/roleManagement/directory/roleAssignmentScheduleRequests"
    $response = Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ErrorAction Stop
} catch {
    # When PIM requires FIDO/Passkey or specific MFA, the API returns 403 with a claims challenge.
    $exception = $_.ErrorDetails.Message

    if ($exception -and $exception -match 'claims=([^"]+)') {
        $claimsChallenge = $matches[1]
        $claimsChallenge = [System.Uri]::UnescapeDataString($claimsChallenge)

        $claimsChallenge
    }
}

How to translate the authentication context ID to DisplayName

In my examples, I use c1 as an authentication context ID.

In the Azure portal, the Authentication contexts menu doesn’t show the ID. But you can use the Developer Tools browser feature to get it. And as you can see, it belongs to the PIM_Elevation_PassKey context in my case.

You can, of course, use the Graph api beta/identity/conditionalAccess/authenticationContextClassReferences to retrieve authentication contexts as well.

Invoke-MgGraphRequest -Uri "beta/identity/conditionalAccess/authenticationContextClassReferences"

Real-world examples

Activating the Azure Resource PIM role (IAM)

• Invoke-PIMResourceRoleActivation from my AzurePIMStuff module.

Activating the Azure Directory PIM role

• Invoke-PIMDirectoryRoleActivation from my AzurePIMStuff module.

What is it good for?

The code replaces the Windows VM images in the specified Azure Local cluster(s) with the latest compatible version available in the Marketplace. So whenever you create a new VM, you will use the updated OS version.

Requirements

Image name

• Image must have a suffix -<number> (i.e. Windows2025-01), so if the image gets replaced with the new one, the <number> can be increased to emphasize the change

Permissions

• IAM (RBAC) assignments for the subscription where the HCI cluster is located

  • Azure Stack HCI Administrator - to be able to manage Azure Local VM Images

  • Reader - to be able to query cluster health, VM Images, and other required resources

PowerShell

• Core (to be able to use parallel processing)

PowerShell modules

• Az (Az.Accounts, Az.ResourceGraph)

• Azure Cli

• AzureLocalStuff

How to use it?

• Create Azure Automation Runbook

• Add required PowerShell modules

• Grant required IAM role assignments to the Automation Account Managed Identity

• Customize the $azureLocalClusterList variable to match your environment in the AzureLocalVMImageUpdater.ps1 script

  

• Use modified code in your Runbook

• Set the Runbook schedule and watch the magic :)

It happens that the hardware hash of your Autopilot device gets changed. Thanks to the replacement of the motherboard or some other issue. This can lead to future problems when your users need to reinstall the operating system, but the Autopilot process doesn’t kick in because of a hash mismatch.

You can retrieve Autopilot devices with a hash mismatch using the following PowerShell code:

Connect-MgGraph

Invoke-MgGraphRequest -Uri "beta/deviceManagement/windowsAutopilotDeviceIdentities" | 
Get-MgGraphAllPages | ? RemediationState -NE 'noRemediationRequired' | 
select DisplayName,SerialNumber,RemediationState

And the result can look like this

• AutomaticRemediationRequired means Intune should automatically remediate this issue (you can ignore it)

• ManualRemediationRequired and Unknown mean you have to solve this on your own

In the Intune portal, you can see the issues in Profile status column like below

The problem is that the change of the autopilot hash is not possible for already enrolled devices 😕

Solution

So, how to fix the autopilot hash mismatch?

By creating automation that gathers the current hash for problematic devices using an on-demand remediation script. This way, you can easily import the retrieved hash when the device needs to be reset without bothering your users.

If you implement my solution, you will see new on-demand remediations, like in the screenshot below, named in form _invCmd_<datetime>_<serialNumber>_getAutopilotHash

And using the following code, you will be able to get the remediation result (hash string) and import it to the Autopilot database

$hash = Get-IntuneRemediationResult | select -ExpandProperty ProcessedOutput # choose the correct remediation (based on device serialNumber)

Upload-IntuneAutopilotHash -psObject $hash -Verbose

Prerequisites

• Option to use Intune on-demand remediations

• Option to create an Azure Automation or an Enterprise Application that will be used in an on-prem scheduled task

• Automation account Graph api permissions

  • DeviceManagementManagedDevices.Read.All

  • DeviceManagementManagedDevices.PrivilegedOperations.All

  • DeviceManagementServiceConfig.Read.All

  • DeviceManagementConfiguration.ReadWrite.All

  • DeviceManagementScripts.ReadWrite.All

• Automation code PowerShell modules

  • Microsoft.Graph.Authentication

  • Microsoft.Graph.DeviceManagement

  • Microsoft.Graph.Beta.DeviceManagement

  • CommonStuff

  • MSGraphStuff

  • IntuneStuff

How to

In automation of your choice (Azure Automation or on-prem scheduled task), run the PowerShell script autopilotHashFix.ps1

Don’t forget to grant all Graph Api application permissions mentioned in the Prerequisites step, and also install all required PowerShell modules!

Summary

Use Intune on-demand remediations to get Autopilot devices hash for all devices, where the uploaded hash doesn’t match the current one.

This way, you will be ready to import the correct one when the OS reinstall needs to be done without any employee interaction.

Introduction & Problem Statement

Picture this: You're tasked with auditing 200 virtual machines across multiple Azure subscriptions. Your PowerShell script needs to check VM status, retrieve configurations, and gather diagnostic information. Using the traditional approach, this means making 600+ individual API calls to Azure Resource Manager (ARM) - three calls per VM.

The result? Your script crawls along for 30+ minutes, constantly hits throttling limits, and occasionally fails with timeout errors. Meanwhile, your manager is asking why the monthly audit report is always late, and you're spending more time babysitting scripts than actually analyzing the data.

What if I told you the same audit could be completed in under 3 minutes with just 30 API calls?

That's the power of Azure Resource Manager API batching. A lesser-known but incredibly powerful Azure capability that can reduce your API calls by up to 80%. In this guide, we'll explore two PowerShell functions that make this possible: New-AzureBatchRequest and Invoke-AzureBatchRequest hosted in the AzureCommonStuff module.

Understanding the Challenge

Why Individual API Calls Don't Scale

Azure Resource Manager implements rate limiting to protect the service infrastructure. The current limits are:

• Read operations: 12,000 requests per hour per subscription

• Write operations: 1,200 requests per hour per subscription

While these numbers might seem generous, they disappear quickly in automation scenarios. Consider a simple VM inventory script:

• 100 VMs × 3 API calls each = 300 requests

• That's 2.5% of your hourly read quota in a single script run

The Performance Tax

Every individual API call carries overhead:

• Network latency: 50-200ms per request, depending on your location

• Authentication processing: Token validation for each request

• Connection overhead: TCP handshake and SSL negotiation

• JSON processing: Multiple small payloads instead of one optimized batch

Common Workarounds and Their Limitations

Most PowerShell developers try these approaches:

1. Sequential processing with delays - Slow and still hits limits

2. Parallel processing with ForEach-Object -Parallel - Actually makes throttling worse

3. Custom retry logic - Adds complexity but doesn't solve the root problem

These approaches treat the symptoms, not the cause. We need a fundamentally different approach.

The Hidden Solution

Azure Resource Manager supports an undocumented batch API endpoint that combines up to 20 individual requests into a single HTTP call. This isn't in the official documentation, but it's the same mechanism the Azure portal uses behind the scenes (as shown in the image below 👇). It's stable, reliable, and incredibly powerful once you know how to use it.

Solution Overview

How Batching Works

Instead of making individual API calls, we package multiple requests into a single batch operation. Azure processes these requests concurrently on the server side and returns all results in one response.

# Traditional approach (slow)
$vmData = @()
foreach ($vmName in $vmNames) {
    $vm = Get-AzVM -ResourceGroupName $rgName -Name $vmName
    $vmData += $vm
}
# Result: 100 VMs = 100 API calls

# Batching approach (fast)
$batchRequests = New-AzureBatchRequest -url "/subscriptions/$subscriptionId/resourceGroups/$rgName/providers/Microsoft.Compute/virtualMachines/<placeholder>?api-version=2023-07-01" -placeholder $vmNames
$vmData = Invoke-AzureBatchRequest -batchRequest $batchRequests
# Result: 100 VMs = 5 API calls (batches of 20)

Key Concepts

Batch Request Objects: Each request contains a method (GET, POST, etc.), URL, and optional headers. The batch system processes these concurrently.

Placeholder Pattern: When you need similar requests with different IDs, the placeholder system generates requests automatically without manual loops.

Error Isolation: If one request in a batch fails, the others continue processing. Each response includes its own status code and error details.

How It Works

New-AzureBatchRequest

Function New-AzureBatchRequest creates standardized request objects that can be batched together:

• URL Flexibility: You can use absolute URLs (https://management.azure.com/...) or relative URLs (/subscriptions/...). The function handles both seamlessly.

• Placeholder Magic: The real power comes from the placeholder parameter. Instead of writing loops, you specify a URL template with <placeholder> and provide an array of values:

# Instead of this manual loop:
$requests = @()
foreach ($subscriptionId in $subscriptionIds) {
    $requests += @{
        Name = "sub_$subscriptionId"
        HttpMethod = "GET"
        URL = "/subscriptions/$subscriptionId/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01"
    }
}

# Use this elegant approach:
$requests = New-AzureBatchRequest -url "/subscriptions/<placeholder>/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" -placeholder $subscriptionIds

Invoke-AzureBatchRequest

Function Invoke-AzureBatchRequest handles the complex orchestration of sending batches and processing responses:

• Automatic Chunking: The function automatically splits your requests into chunks of 20 (Azure's limit) and processes them sequentially.

• Response Beautification: By default, the function extracts just the data you need from Azure's verbose response format, making results much easier to work with.

Step-by-Step Walkthrough

Let's trace through a complete batching operation:

Step 1: Create Batch Requests

# Get VM status across multiple resource groups
$resourceGroups = @('rg-web-servers', 'rg-database-servers', 'rg-cache-servers')
$subscriptionId = (Get-AzContext).Subscription.Id

$requests = New-AzureBatchRequest -url "/subscriptions/$subscriptionId/resourceGroups/<placeholder>/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" -placeholder $resourceGroups

Behind the scenes, this creates three request objects:

# Generated request objects (simplified)
@(
    @{ Name = "123456"; HttpMethod = "GET"; URL = "/subscriptions/abc.../resourceGroups/rg-web-servers/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" },
    @{ Name = "789012"; HttpMethod = "GET"; URL = "/subscriptions/abc.../resourceGroups/rg-database-servers/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" },
    @{ Name = "345678"; HttpMethod = "GET"; URL = "/subscriptions/abc.../resourceGroups/rg-cache-servers/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" }
)

Step 2: Execute the Batch

$allVMs = Invoke-AzureBatchRequest -batchRequest $requests

The function:

1. Validates all URLs and request objects

2. Chunks requests into groups of 20

3. Sends each chunk as a single HTTP POST to Azure's batch endpoint

4. Processes responses and handles errors

5. Beautifies results by extracting just the VM data

Step 3: Work with Results

# Results are ready to use immediately
$windowsVMs = $allVMs | Where-Object { $_.storageProfile.osDisk.osType -eq 'Windows' }
$runningVMs = $allVMs | Where-Object { $_.powerState -eq 'VM running' }

Write-Host "Found $($allVMs.Count) total VMs, $($windowsVMs.Count) Windows VMs, $($runningVMs.Count) running"

Practical Examples

Real-World Scenario: Security Compliance Audit

Here's a more complex example that demonstrates the power of batching for compliance scenarios:

# Scenario: Audit network security groups, storage accounts, and key vaults across subscriptions
$subscriptionIds = (Get-AzSubscription | Where-Object State -eq 'Enabled').Id

# Build audit requests for multiple resource types
$auditRequests = @()

# Network Security Groups
$auditRequests += New-AzureBatchRequest -url "/subscriptions/<placeholder>/providers/Microsoft.Network/networkSecurityGroups?api-version=2024-03-01" -placeholder $subscriptionIds -name "NSGs"

# Storage Accounts  
$auditRequests += New-AzureBatchRequest -url "/subscriptions/<placeholder>/providers/Microsoft.Storage/storageAccounts?api-version=2023-05-01" -placeholder $subscriptionIds -name "Storage"

# Key Vaults
$auditRequests += New-AzureBatchRequest -url "/subscriptions/<placeholder>/providers/Microsoft.KeyVault/vaults?api-version=2024-11-01" -placeholder $subscriptionIds -name "KeyVaults"

# Execute all requests efficiently
Write-Host "Starting audit of $($subscriptionIds.Count) subscriptions..."
$auditResults = Invoke-AzureBatchRequest -batchRequest $auditRequests

# Process results by resource type
$nsgs = $auditResults | Where-Object { $_.RequestName -like "NSGs_*" }
$storageAccounts = $auditResults | Where-Object { $_.RequestName -like "Storage_*" }
$keyVaults = $auditResults | Where-Object { $_.RequestName -like "KeyVaults_*" }

# Generate compliance report
Write-Host "Audit Summary:"
Write-Host "- Network Security Groups: $($nsgs.Count)"
Write-Host "- Storage Accounts: $($storageAccounts.Count)"  
Write-Host "- Key Vaults: $($keyVaults.Count)"

# Check for common security issues
$publicStorageAccounts = $storageAccounts | Where-Object { $_.properties.allowBlobPublicAccess -eq $true }
if ($publicStorageAccounts) {
    Write-Warning "Found $($publicStorageAccounts.Count) storage accounts with public blob access enabled"
}

Performance comparison for this scenario:

• Traditional approach: 600+ API calls, 15-20 minutes

• Batching approach: 30 API calls, 2-3 minutes

Combining different HTTP Methods

While most scenarios use GET requests, you can batch other operations too:

# Batch different types of operations
$mixedRequests = @()

# GET requests for current state
$mixedRequests += New-AzureBatchRequest -url "/subscriptions/$subscriptionId/resourceGroups/<placeholder>/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01" -placeholder $resourceGroups -name "GetVMs"

# POST requests for operations (example: restart VMs)
$vmIds = @('vm1', 'vm2', 'vm3')
$mixedRequests += New-AzureBatchRequest -url "/subscriptions/$subscriptionId/resourceGroups/$rgName/providers/Microsoft.Compute/virtualMachines/<placeholder>/restart?api-version=2024-11-01" -placeholder $vmIds -method "POST" -name "RestartVMs"

# Execute mixed batch
$results = Invoke-AzureBatchRequest -batchRequest $mixedRequests

# Check operation results
$getResults = $results | Where-Object { $_.RequestName -like "GetVMs_*" }
$restartResults = $results | Where-Object { $_.RequestName -like "RestartVMs_*" }

Multiple KQL queries

[System.Collections.Generic.List[object]] $batchRequest = @()

$queryUrl = "https://management.azure.com/providers/Microsoft.ResourceGraph/resources?api-version=2021-03-01"

$diskQuery = @"
ExtensibilityResources
    | where type =~ "microsoft.azurestackhci/virtualmachineinstances"
"@

$batchRequest.add((New-AzureBatchRequest -method POST -url $queryUrl -content @{ query = $diskQuery } -name "diskInfo" ))

$nicQuery = @"
resources
| where type =~ "Microsoft.AzureStackHCI/networkinterfaces" and
    properties.provisioningState =~ "succeeded"
"@

$batchRequest.add((New-AzureBatchRequest -method POST -url $queryUrl -content @{ query = $nicQuery } -name "nicInfo"))

# Invoking two KQL queries in a batch to get Azure Stack HCI VM disk and NIC information
$batchResult = Invoke-AzureBatchRequest -batchRequest $batchRequest

$vmListDiskInfo = $batchResult | ? RequestName -EQ "diskInfo"
$vmListNicInfo = $batchResult | ? RequestName -EQ "nicInfo"

Troubleshooting Tips

When things don't work as expected, try these approaches:

# Enable verbose output to see what's happening
$VerbosePreference = 'Continue'
$results = Invoke-AzureBatchRequest -batchRequest $requests -Verbose

# Check for failed requests by examining raw responses
Invoke-AzureBatchRequest -batchRequest $requests -dontBeautifyResult

# Test individual URLs before batching
$testUrl = "/subscriptions/$subscriptionId/resourceGroups/$rgName/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01"
try {
    $testResult = Invoke-AzRestMethod -Uri "https://management.azure.com$testUrl" -Method GET
    Write-Host "Test successful: $($testResult.StatusCode)"
} catch {
    Write-Error "URL test failed: $_"
}

Tips and Considerations

Performance Optimization

Use Resource Graph Query: If possible, gather your data from the Resource Graph Table, which will always be faster than api calls. Nice example of getting IAM assignments.

Monitor Your Quotas: Even with batching, be mindful of overall API limits across your entire environment. Use Get-AzConsumptionUsageDetail to monitor usage patterns.

Common Mistakes to Avoid

URL Template Errors: Make sure your placeholder strings don't conflict with actual URL parameters:

# Wrong - conflicts with OData filter syntax
$badUrl = "/virtualMachines?$filter=name eq '<placeholder>'"

# Right - placeholder in path segment
$goodUrl = "/virtualMachines/<placeholder>"

Authentication Scope Issues: Ensure your PowerShell session has permissions for all resources you're querying. Cross-subscription batching requires appropriate access.

Api version errors: Ensure you append a valid api version (api-version=2023-07-01 for example) to each URL request!

".../resourceGroups/$rgName/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01"

If you are unsure what api to use:

• Check official documentation.

• Use a random one, and when the request fails with a 400 error, check the error message for the list of correct api versions.

• Use the official corresponding Az cmdlet with -debug parameter (Get-AzStorageAccount -debug) and check the 'Absolute uri' output.

• Use developer tools (F12) in your browser when using the Azure Portal and check the request URL there.

Getting Started

These functions are part of the AzureCommonStuff module on PowerShell Gallery. Here's how to install it:

# Install the module (one-time setup)
Install-Module AzureCommonStuff

# Import the module in your session
Import-Module AzureCommonStuff

# Verify the functions are available
Get-Command New-AzureBatchRequest, Invoke-AzureBatchRequest

# Get help
Get-Help New-AzureBatchRequest -Examples
Get-Help Invoke-AzureBatchRequest -Examples

Prerequisites

Before using these functions, make sure you have:

• PowerShell 5.1 or PowerShell 7+

• Az PowerShell module installed (Install-Module Az)

• Authenticated Azure session (Connect-AzAccount)

• Appropriate permissions for the resources you want to access

Summary

Azure Resource Manager API batching transforms the way you interact with Azure at scale. By reducing API calls and execution times, these PowerShell functions unlock new possibilities for automation, reporting, and compliance scenarios.

The functions New-AzureBatchRequest and Invoke-AzureBatchRequest leverage an undocumented but stable Azure API that's used by the Azure portal itself. While it's not officially documented, it's proven reliable across multiple Azure updates and represents a significant competitive advantage for anyone doing serious Azure automation work.

Start experimenting with small batches, measure the performance improvements, and gradually adopt batching across your Azure automation portfolio. Your scripts will run faster, your users will be happier, and you'll spend less time waiting for operations to complete and more time solving interesting problems.

Meet the device-backup-pipeline pipeline 🙂

Why Automate Device Backups?

• Disaster Recovery: Quickly restore device secrets if Intune or Azure AD data is lost by accident or targeted attack.

• Audit & Compliance: Maintain a historical record of device security data.

• Change Tracking: Easily see when device keys or credentials change.

Pipeline Overview

This pipeline runs every day at 5 am and performs the following steps:

1. Authenticates to Microsoft Graph using a secure service connection (Workload Federating identity).

2. Exports device data (including BitLocker, LAPS, and FileVault keys) from Intune/Azure AD.

3. Validates the backup to ensure all critical data is present.

4. Exports each device’s data as a JSON file organized by OS and device serial number.

5. Commits and tags the backup in your private Azure DevOps repository.

Benefits

• Fully automated: No manual steps required.

• Version-controlled: Every backup is committed and tagged in Azure DevOps repository.

• Secure: Uses Azure DevOps service connections a.k.a. no stored secrets + supports AES encryption for the stored secrets

• Auditable: All device security data is available for review and recovery.

• Customizable: You choose what to back up

How to set this up

The pipeline device-backup-pipeline.yml itself is stored in my GitHub.

In general, you need to:

• Create a private Azure DevOps repository

• Set up a new pipeline (based on device-backup-pipeline.yml content)

• Give the pipeline account Contribute permission so that it can push changes to the repository

• Create a Workload Federating identity (WIF) so that the running pipeline has access to Intune and Azure via the Graph Api

If you want to encrypt the stored secrets:

• Create a strong password and save it to Azure KeyVault

• Grant the WIF identity the Key Vault Secrets User role over the created secret

I will not go into detail about how to create an Azure DevOps repository, create the pipeline, or grant permissions to it. It’s all described in one of my previous posts already.

The only two things that are specific to this pipeline are:

• Graph Api permissions

• Pipeline variables that need to be set to fit your environment

What Graph Api permissions need to be granted to the pipeline service connection principal:

• DeviceManagementManagedDevices.Read.All

• BitlockerKey.Read.All

• DeviceLocalCredential.Read.All

• DeviceManagementConfiguration.Read.All

• DeviceManagementManagedDevices.PrivilegedOperations.All

• User.ReadBasic.All

• Device.Read.All

Pipeline variables

Before you can run the pipeline, you have to set the variables section! Each variable is commented, so it should be quite straightforward.

Security concerns

This repository will contain highly sensitive data, so you must be very cautious about who has access, where the data is stored, and other security considerations.

There are some general tips

• Use the built-in encryption feature

  • AES encryption will protect the secrets, just make sure only the right persons have access to the KeyVault encryption key!

• Make sure the repository is set to private (not public)

• Make sure only relevant people have access to the repository

• Use a self-hosted agent (on a Tier-0 server) to run the pipeline

What the backup structure looks like

The backup structure looks like this 👇

So you have device data exported as JSON files, separated into two folders MacOS and Windows based on the device operating system. The device serial number is considered a unique identifier; hence, it is used as the JSON file name.

FAQ

• How to decrypt a secret?

  • Just use the following PowerShell code

    •       $encryptionKey = Get-AzKeyVaultSecret -VaultName "<someKeyVaultName>" -Name "<someSecretName>"
            $encryptionKeyValue = $encryptionKey.SecretValue | ConvertFrom-SecureString -AsPlainText
            $decryptedText = ConvertFrom-EncryptedString -EncryptedText "<encryptedSecret>" -Key $encryptionKeyValue
      

• What happens when the device gets deleted from the Azure/Intune

  • Device backup a.k.a. <deviceSerial>.json file will stay intact in your backup

• What happens when the device gets reinstalled?

  • The device backup (JSON file) will be updated with the new information

• What if I need to see what the LAPS password was set to a week ago (I restored the device from the backup, or for any other reason)

  • Use the History tab in the DevOps portal to show the previous device backup versions

    

Conclusion

With this Azure DevOps pipeline, you can rest easy knowing your Intune device security data is safely backed up, versioned, and ready for disaster recovery or audit. Adapt the scripts to your environment, and you’ll have a powerful, hands-off backup solution for your device secrets.

It enables parallel execution of up to 20 Graph API calls, which is fantastic, but there is one tiny little problem. You have to write your own logic for managing pagination, throttling, server-side errors recovery, and more.

Well, you don’t have to anymore, because of my new functions New-GraphBatchRequest, Invoke-GraphBatchRequest hosted in the PowerShell module MSGraphStuff 👍.

Performance boost examples

In the image below, you can see the huge performance boost provided by using batching. From 50 seconds, I was able to pull all my Intune policies in just 11 seconds. And the difference can be even bigger in larger environments 😎

There is a table of some of my other functions that were rewritten to use batching, along with the performance gain I achieved.

TL;DR

1. Install my PowerShell module MSGraphStuff

   1.        Install-Module MSGraphStuff
      

2. Create a batch request using New-GraphBatchRequest function

   1.         $batchRequest = @(
                 # Azure app registrations
                 New-GraphBatchRequest -url "/applications" -id "Apps"
                 # Azure enterprise applications
                 New-GraphBatchRequest -url "/servicePrincipals" -id "SPs"
                 # Azure users
                 New-GraphBatchRequest -url "/users" -id "Users"
                 # Azure groups
                 New-GraphBatchRequest -url "/groups" -id "Groups"
                 # Intune devices
                 New-GraphBatchRequest -url "/deviceManagement/managedDevices" -id "IntuneDevices"
                 # ... you can add as many Api urls as you wish
             )
      

3. Invoke the batch request using Invoke-GraphBatchRequest function to get the results

   1.        $batchResult = Invoke-GraphBatchRequest -batchRequest $batchRequest -graphVersion "beta" -Verbose
      
             # output all results at once
             $batchResult
      
             # split the results by the request id, so you can use them separately
             $apps = $batchResult | ? RequestId -eq "Apps"
             $sps = $batchResult | ? RequestId -eq "SPs"
             $users = $batchResult | ? RequestId -eq "Users"
             $groups = $batchResult | ? RequestId -eq "Groups"
             $intuneDevices = $batchResult | ? RequestId -eq "IntuneDevices"
      

Graph Api Batching introduction

What is Graph Api batching?

According to the official documentation, Graph Api JSON batching allows clients to combine multiple requests into a single JSON object and a single HTTP call, reducing network roundtrips and improving efficiency. Microsoft Graph supports batching up to 20 requests into the JSON object.

To put it simply, batching allows you to process up to 20 Graph Api requests at the same time 😎

Most of the Microsoft portals use batching under the hood, btw.

Batching advantages

1. Huge performance boost

   Parallel processing of up to 20 requests.

2. Reduced Network Overhead
   Instead of sending multiple HTTP requests, batching consolidates them into one, reducing the number of round-trips between client and server.

3. Bypassing URL length limitations

   In cases where the filter clause is complex, the URL length might surpass limitations built into browsers or other HTTP clients. You can use JSON batching as a workaround for running these requests because the lengthy URL simply becomes part of the request payload.

Batching drawbacks (and how I solved them)

1. You need to know the requested Graph Api URL

   1. PROBLEM: You cannot use PowerShell commands like Get-MgUser, but the under-the-hood-used URL instead.

   2. SOLUTION: Check the Tips to find out how to determine the correct API URL.

2. Complex error handling

   1. PROBLEM: Each sub-request in a batch can succeed or fail independently, requiring more sophisticated error-handling logic.

   2. SOLUTION: Invoke-GraphBatchRequest handles all server-side errors by retrying the request.

3. Rate limiting still applies

   1. PROBLEM: Batching doesn’t bypass Microsoft Graph’s throttling policies. If you exceed limits, your batch requests can still be throttled.

   2. SOLUTION: Invoke-GraphBatchRequest retries the request(s) after the time specified in the server response.

4. Pagination still applies

   1. PROBLEM: Each sub-request in a batch can return only one page of the total number of results, requiring special handling logic.

   2. SOLUTION: Invoke-GraphBatchRequest handles pagination by creating another batch of paginated requests (URLs taken from @odata.nextLink property).

5. Separate API versions

   1. PROBLEM: You can’t combine requests against beta and v1.0 api endpoints in the same batch.

   2. SOLUTION: Currently, none. But it’s in my to-do to allow requesting both api versions in the Invoke-GraphBatchRequest (by separating the batches by inner logic).

6. 20 requests per batch limitation

   1. PROBLEM: When sending a batch request to https://graph.microsoft.com/<apiVersion>/$batch you cannot send more than 20 requests per batch.

   2. SOLUTION: Invoke-GraphBatchRequest handles batch-requests-limit by automatically splitting batch requests into chunks of 20.

7. Payload size limits

   1. PROBLEM: The total size of a batch request is limited (typically 4 MB), which can be restrictive for large data operations.

   2. SOLUTION: None. In the size of my company, I haven’t encountered this limitation.

Frankly, those drawbacks kept me away from using batching for quite a long time.

One of the things that finally made me adopt the batching and solve the mentioned issues was working on my Get-IntuneDeviceHardware function. A Graph Api URL that needs to be used to get hardware information requires querying devices one by one, which can be super slow!

Use cases

Information that can be gathered only one-at-a-time

As mentioned, Intune device hardware inventory data must be requested device by device (Get-IntuneDeviceHardware). The same applies to discovered apps (Get-IntuneDiscoveredApp) or getting Bitlocker keys, FileVault keys, or a lot of PIM-related stuff.

You are making more than one Graph Api request in your code

It doesn’t make sense to use batching for one request. But more than one? Worth it!

Automatic Api throttling on specific URIs when ‘expand’ is used

For example, when working with /deviceManagement/configurationPolicies?$expand=settings,assignments you will encounter automatic throttling on the server side. To overcome this problem, you have to split the calls: /deviceManagement/configurationPolicies/<policyId>/settings, /deviceManagement/configurationPolicies/<policyId>/assignments. Btw, this is what I am doing in my improved Get-IntunePolicy function, where thanks to batching, I was able to reduce the run time from 60 seconds to just 8 (in my environment).

Tips

How to create a batch request for the Invoke-GraphBatchRequest function

Invoke-GraphBatchRequest function accepts an array of requests PSObjects (via batchRequest parameter) where at minimum, you have to specify the following properties:

• Request id

  • can be later used to separate the results

• HTTP method

  • GET in most cases

• Request url

  • in relative form (without the 'https://graph.microsoft.com/<apiversion>' prefix)

You can create it manually like below

# create batch request
$batchRequest = @(
        [PSCustomObject]@{
            id     = "app"
            method = "GET"
            URL    = "applications" # stands for https://graph.microsoft.com/<apiversion>/applications
        },
        [PSCustomObject]@{
            id     = "sp"
            method = "GET"
            URL    = "servicePrincipals" # stands for https://graph.microsoft.com/<apiversion>/servicePrincipals
        }
)

Or via my function New-GraphBatchRequest like this

$batchRequest = @((New-GraphBatchRequest -Url "applications" -Id "app"), (New-GraphBatchRequest -Url "servicePrincipals" -Id "sp"))

And then use it like

# run batch request
$allResults = Invoke-GraphBatchRequest -batchRequest $batchRequest

# separate the results by request id
$applicationList = $allResults | ? RequestId -eq "app"
$servicePrincipalList = $allResults | ? RequestId -eq "sp"

See the documentation and examples for more details.

How to create dozens of requests where only the ID part of the URL is changing

This is exactly why I’ve created New-GraphBatchRequest function originally, because you can give it a URL with <placeholder> string inside (url parameter), plus an array of strings (placeholder parameter) to generate a customized URL request for each of them.

$deviceId = (Get-MgBetaDeviceManagementManagedDevice -Property id -All).Id

New-GraphBatchRequest -url "/deviceManagement/managedDevices/<placeholder>?`$select=id,devicename&`$expand=DetectedApps" -placeholder $deviceId

How to find out the Graph Api request URL

OK, so you have some function or script that uses official Graph Api SDK cmdlets a.k.a. Get-MgUser, Get-MgDevice, … and you want to know what URLs are used under the hood?

You have the following options:

• You can add -Debug switch to any -Mg* cmdlet and it will return the called URL (including the used filter and property parameters)

• 

  You can find any -Mg* cmdlet using Find-MgGraphCommand to get the called (relative) base URL

• 

Or if you like, you can search the official documentation :)

Or maybe you want to know how the data that you can see on some Intune/Azure/… portal is gathered? In such case, use the developer tools feature (F12) in your browser and on the tab Network search for graph string.

As you can see Azure portal uses batching for Groups retrieval :)

When batching is NOT used, you can get the requested URL in the Headers sub-tab

Summary

Graph Api Batching is a great way to improve the performance of your scripts, but you have to use functions like mine Invoke-GraphBatchRequest (MSGraphStuff module) to overcome the lack of built-in support for pagination, throttling, and server-side errors handling.

Happy coding 😎

This function allows you to easily identify the differences in settings between two Intune Security baselines. For instance, when Microsoft introduces a new Security Baseline for Windows 10, you can quickly see how it varies from your currently deployed baseline.

How to use

Install-Module IntuneStuff

Connect-MgGraph -Scope DeviceManagementConfiguration.Read.All

Compare-IntuneSecurityBaseline

When you invoke Compare-IntuneSecurityBaseline, you will be interactively asked to select the baseline type.

And then select two baselines of such type to compare.

Function exports both baselines as JSON objects and makes the comparison.

The result will be objects that look like this 👇

What do the object columns contain

• Result - type of change (whether the setting differs or is missing completely)

• Setting - name of the setting as is in the exported JSON file

  • JSON name doesn’t match the setting names in the Intune GUI. Use just one of the keywords when searching the GUI (for example when searching for device_vendor_msft_policy_config_defender_submitsamplesconsent search the GUI for ‘samples’ or ‘consent’).

• OldBslnValue - JSON value of the first baseline setting

• NewBslnValue - JSON value of the second baseline setting

Summary

With the function Compare-IntuneSecurityBaseline in place, we can now easily compare our current baselines with their newly released versions. Such information can help to decide which settings need to be modified to avoid breaking our environment etc 🙂

Below is a short PowerShell script to identify the usage of the free GitHub Copilot addon version in Visual Studio Code (VSC) IDE across your Windows clients.

You can run it via PowerShell remoting or like in my case via Intune on-demand remediation.

Install-Module IntuneStuff

# code will check VSC log files for usage of free_limited_copilot copilot sku
$code = { 
    Get-ChildItem -Path "C:\Users\*" | ? Name -NE "Public" | % {
        Get-ChildItem -Path ($_.FullName + "\AppData\Roaming\Code\logs\*") -Recurse -Include "GitHub Copilot Chat.log" -ErrorAction SilentlyContinue | % {
            $matchedContext = Select-String -Path $_.FullName -Pattern "sku: free_limited_copilot" -Context 1

            if ($matchedContext) {
                $userLine = @($matchedContext)[0] -split "`n" | ? { $_ -match "Got Copilot token for" }
                $user = ([regex]"Got Copilot token for (.+)$").Matches($userLine).captures.groups[1].value

                if ($user) {
                    "On $env:COMPUTERNAME in '$($_.FullName)' user '$($user.trim())' is using free copilot"
                } else {
                    "On $env:COMPUTERNAME in '$($_.FullName)' this info was found:`n$matchedContext"
                }
            }
        }
    } 
}

# invoke given code against all Windows Intune-managed devices
Invoke-IntuneCommand -scriptBlock $code -waitTime 20

In this post, I’ll demonstrate how to create this automation within your Azure tenant and provide all the necessary PowerShell code.

Below is an example of the email your user will receive if a vulnerable .NET app is found on their device 👇

As shown, the email includes a list of vulnerable apps, their versions, clickable CVEs, and details on how each app was detected.

But why should we make users update their apps in the first place?

• Users can install software on their own avoiding any interruptions

• Automatic update of the app can cause compatibility issues

  • this applies mostly to developer tools like Visual Studio, Python, .Net, NodeJS, etc

These are some of the reasons why involving your users in the app update process can be necessary.

But just informing the users without any sort of "punishment" wouldn't be sufficient. That is the reason why we are sending a second email in case the user doesn't fix the issue in time. This second email can be sent to the user manager, security team, etc. Or another more brutal approach can be chosen like isolating the device 😎.

Summary

After you finish this tutorial you will have:

• Azure Automation that will monitor vulnerabilities on company devices and send email notifications based on the set thresholds to the device owner

  • first email by default 30 days after the first vuln. detection

    • TIP: A list of apps that should trigger immediate notification is supported

  • second email by default 14 days after the first one

• (optional) Azure KeyVault that will safely store SendGrid API key

• Azure Storage blob that will be used as persistent storage for Azure Automation runbook

Prerequisites

• License for 'Microsoft Defender Vulnerability Management'

  • Official licensing FAQ

• Permission to create Azure Automation and assign required Microsoft Defender for Endpoint API permissions

• Willing to pay 1$/month for required Azure services (Storage, Automation, and KeyVault)

  • Or rewrite the code and host it on-premises for free

• SendGrid account (API token) for sending notification emails

  • Runbook code can be customized to use any SMTP service, sending Teams messages, etc.

Let's go

Create Automation Account

Create a new Automation Account named VulnerableApps.

Make a note of the ID of the automatically created System Managed Identity. You will need it later when granting permission.

Create a Runbook

Inside the Automation Account create a new PowerShell 5.1 Runbook and copy-paste code from my VulnerableApps.ps1 script

Now modify #region CORE variables section to suit your environment and save the result!

$sendGridParam has to contain values set in the section Create Azure KeyVault for storing SendGrid API key.

Grant required permissions for accessing Microsoft Defender API

In order for our automation to be able to read data from the Microsoft Defender API, it is necessary to assign it the following WindowsDefenderATP permissions:

• User.Read.All

• SecurityRecommendation.Read.All

• Alert.Read.All

• Software.Read.All

• Vulnerability.Read.All

• Machine.Read.All

• AdvancedQuery.Read.All

You can do it easily using my function Grant-AzureServicePrincipalPermission (part of the AzureApplicationStuff module) or manually in the Azure portal

# example code, you need to adjust it to match your environment!

Connect-AzAccount 

Grant-AzureServicePrincipalPermission -servicePrincipalId 'yourManagedIdentityId' -permissionType application -permissionList 'User.Read.All','SecurityRecommendation.Read.All','Alert.Read.All','Software.Read.All','Vulnerability.Read.All','Machine.Read.All','AdvancedQuery.Read.All' -resourceAppId 'fc780465-2017-40d4-a0c5-307022471b92'

Import required modules

Runbook code depends on several other modules that I've created, so in order for it to work, we need to import them into our Automation Account environment.

Required modules:

• AzureResourceStuff

• M365DefenderStuff

• CommonStuff

• PSSendGrid

You can do it easily using my function New-AzureAutomationModule or New-AzureAutomationRuntimeModule in case you are using Runtime Environments (both functions are part of the AzureResourceStuff module) which has a huge benefit of importing but just required modules, but also their required dependencies 👍.

Or you can import the modules manually in the Automation account settings.

# example code, you need to adjust it to match your environment!

Connect-AzAccount -Tenant "contoso.onmicrosoft.com" -SubscriptionName "AutomationSubscription"

'AzureResourceStuff','M365DefenderStuff','CommonStuff','PSSendGrid' | % {
    New-AzureAutomationModule -resourceGroupName XXX -automationAccountName YYY -moduleName $_
}

Create an Azure Storage Account for storing Runbook persistent data

Because Azure Automation Runbook doesn't have the option to store complex persistent data, we need to store such data in Azure Blob storage.

In the subscription where you host your Runbook please create the following structure:

• Resource Group Name named PersistentRunbookVariables

  • In that group create a Storage Account named persistentvariablesstore

    • In that Storage Account create a container named variables

Grant Runbook Managed Identity permissions to the Azure Storage Account container

Grant our Managed Identity Storage Blob Data Contributor IAM role over Storage Account container created in the previous step. So it can modify files in this container.

Create Azure KeyVault for storing SendGrid API key

For sending emails via SendGrid I am using my function Send-EmailViaSendGrid. This function supports retrieval of the SendGrid API key directly from Azure KeyVault, which is an ideal solution for Azure Automations.

The only thing you have to do is to create such a secret in the existing KeyVault (or some newly created one) and set $sendGridParam hashtable values accordingly in your Runbook code.

Grant Runbook Managed Identity permissions to read stored SendGrid token

Grant our Managed Identity Key Vault Secrets User IAM role over the created secret to allow it to read it.

Gotchas

• Defender vulnerability report doesn't have to be 100% accurate, because if app is incorrectly uninstalled therefore some registry keys or files remain on the device disk, Defender can still detect it even though the app isn't installed. In such rare cases, you need to manually remove some leftovers.

• If you use MDT for software installation, apps are installed under a built-in administrator account, which can lead to situations where the vulnerable app is detected in the built-in administrator profile/registry! This can be a significant problem for your users because it can be hard for them to remove such leftover data.

  • This can be solved by removing the built-in admin profile (not the account, just the profile data). For example, using Intune remediation script and PSH code

      Get-CimInstance -Class Win32_UserProfile | ? { $_.SID -like "*-500" } | Remove-CimInstance
    

Tips

• Inform your users about those notifications beforehand! So they don't consider them as a scam 😀

• You can exclude the specific application from this notification automation, for example, because it is the last existing version, so your users cannot update it anyway

  • Just update the $exclusionList variable in the automation code

      <#
      - 'CveId' and/or 'ProductName' property/ies (string) have to be defined
      - 'ProductVersion' (string) is optional
          - property values can be extracted from $vulnerabilityPerMachine.vulnswdata
      - 'ValidUntil' (datetime) is optional (since this date, exclustion will be ignored)
          - BEWARE that in Azure pipeline EN date has to be used a.k.a. month.day.year!!!
      #>
    
      $exclusionList = @(
          [PSCustomObject]@{
              CveId       = 'CVE-2024-32002'
              ProductName = 'visual_studio_2022'
              ValidUntil  = (Get-Date 8.1.2024) # M.d.yyyy
          }
      )
    

• Check this article if you want to update all installed applications gradually using Winget

  • exceptions can be made

• If your helpdesk interactively logs in to employees' computers, you can avoid identifying such accounts as device owners by altering the following line of code in the runbook

•         $user = Get-M365DefenderMachineUser -header $header -machineId $machineId | ? { $_.logonTypes -like '*Interactive*' -and $_.accountName -ne "administrator" }
  

Today I will show you some of my PowerShell commands (M365DefenderStuff module) with a focus on the 'Microsoft Defender Vulnerability Management' part.

The main benefit of using my module instead of direct API calls is built-in support for pagination, throttling, time-outs, and other nasty things 😎.

Prerequisites

• In general license for using Microsoft Defender solution

• Special license for using 'Microsoft Defender Vulnerability Management' in case you want to see found vulnerabilities on your clients

  • Official licensing FAQ

Before we begin

Install M365DefenderStuff module

To be able to use my PowerShell commands, you must first install the M365DefenderStuff module from the PowerShell Gallery.

Install-Module M365DefenderStuff

Control your M365 Defender via PowerShell

Authenticate

Import-Module Az.Accounts

Connect-AzAccount

Get all/selected machine

# get all machines
Get-M365DefenderMachine

# get just specific machine
Get-M365DefenderMachine -machineId 'fff5e5e26cb0848d66bbb0bc83de6bceb4a1b2e1'

Get the machine owner (the user who logs in)

Get-M365DefenderMachineUser -machineId 'fff5e5e26cb0848d66bbb0bc83de6bceb4a1b2e1'

Get detected software

# get all detected applications
Get-M365DefenderSoftware

# get just specific application
Get-M365DefenderSoftware -softwareId 'adobe-_-creative_cloud'

Get detected vulnerabilities

# get all found vulnerabilities (can take several minutes to complete!)
Get-M365DefenderVulnerability

# get details of specific vulnerability
Get-M365DefenderVulnerability -vulnerabilityId 'CVE-2022-47926'

Generate vulnerability report

# get just software vulnerabilities of CTRITICAL type and group them by machine
Get-M365DefenderVulnerabilityReport -groupBy machine -skipOSVuln -severity Critical

Invoke KQL query

Invoke-M365DefenderAdvancedQuery -query "DeviceInfo | join kind = fullouter DeviceTvmSoftwareEvidenceBeta on DeviceId"

Get software evidence

# get all (100 000 at most) applications evidences
Invoke-M365DefenderSoftwareEvidenceQuery

# get all (100 000 at most) applications evidences related to JRE software
Invoke-M365DefenderSoftwareEvidenceQuery -appName JRE

Get defender recommendations

# get all security recommendations
Get-M365DefenderRecommendation

# get security recommendations just for Putty software.
Get-M365DefenderRecommendation -productName 'putty'

# get all security recommendations for given machine.
Get-M365DefenderRecommendation -machineId '43a802402664e76a021c8dda2e2aa7db6a09a5f1'

Get all vulnerabilities per machine and software

# retrieves a list of all the vulnerabilities affecting the organization per machine and software.
Get-M365DefenderMachineVulnerability

That is all for now, but more functions will be added in the future to the M365DefenderStuff module don't worry 😉

The main features are:

• You can have multiple custom runtime environments that can be used across numerous Runbooks (a.k.a. one runtime in multiple runbooks)

• Testing of new module versions is super easy, you create a new runtime, import modules you want to test, switch to this runtime in your runbook, and see how it goes

• Testing of the new Runtime language version is super easy

• All of this can be automated via direct API calls

Today I will show you how to manage the whole Runtime Environment lifecycle including modules management through my PowerShell module AzureResourceStuff.

By the way, there is official documentation about managing Runtime Environments via API, but it lacks a lot of information, therefore I had to use web browser Developer Tools (F12) to get what I needed in most cases 😎

Before we begin

Enable Runtime Environments (Preview)

Open your testing Automation Account in the Azure web portal interface.

Manually switch to the new Runtime experience before you continue!

By the way, you can switch back using Switch to Old Experience button any time.

Now when switching to the new experience, you should see a new menu Runtime Environments (Preview) in your Automation Account left pane.

Now, we can create new runtimes, import modules, and more manually or using PowerShell commands, as shown below.

Install AzureResourceStuff module

To be able to use my PowerShell commands, you must first install AzureResourceStuff module from the PowerShell Gallery.

Install-Module AzureResourceStuff

Runtime environment functions

Now I show you a few basic actions you want to make with your Runtimes. Be sure to check functions help (via Get-Help) to get more details and examples though!

Import-Module Az.Accounts

Connect-AzAccount

Set-AzContext -Subscription "<nameOfYourSubscription>"

Get all Runtime Environments

Get-AzureAutomationRuntime

Create a new Runtime Environment

$defaultPackage = @{
    az = '8.0.0'
}
New-AzureAutomationRuntime -runtimeName 'CustomPSH_7.2' -runtimeLanguage 'PowerShell' -runtimeVersion '7.2' -defaultPackage $defaultPackage

Add a custom PSH module

Custom modules are imported from PSH Gallery or a ZIP file.

# import newest version of the 'CommonStuff' module (including all required dependencies) from the PowerShell Gallery
New-AzureAutomationRuntimeModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

# import module archived in the selected zip file
New-AzureAutomationRuntimeZIPModule -moduleZIPPath "C:\DATA\helperFunctions.zip" -runtimeName 'CustomPSH_7.2'

Update a custom PSH module

# update 'CommonStuff' module to the newest version
Update-AzureAutomationRunbookModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

# update/downgrade 'CommonStuff' module to the specified version
Update-AzureAutomationRunbookModule -moduleName 'CommonStuff' -moduleVersion '1.0.15' -runtimeName 'CustomPSH_7.2'

# update all custom modules to their newest version
Update-AzureAutomationRunbookModule -allCustomModule -runtimeName 'CustomPSH_7.2'

# replace existing module with the one saved in selected zip file
New-AzureAutomationRuntimeZIPModule -moduleZIPPath "C:\DATA\helperFunctionsv2.zip" -runtimeName 'CustomPSH_7.2'

Remove a custom PSH module

Remove-AzureAutomationRuntimeModule -moduleName 'CommonStuff' -runtimeName 'CustomPSH_7.2'

Get available default modules

Default modules are pre-built into every runtime. You select whether you want to use it (and which version) or don’t want to use it at all.

Get-AzureAutomationRuntimeAvailableDefaultModule

Set default module version

The default (built-in) modules are az, azure cli a.k.a. the ones selected from the dropdown menu in the Azure portal GUI.

$defaultPackage = @{
    'azure cli' = '2.56.0'
}

# replace existing default modules with new setting (remove 'az' completely)
Set-AzureAutomationRuntimeDefaultModule -defaultPackage $defaultPackage -runtimeName 'CustomPSH_7.2' -replace


$defaultPackage = @{
    'az'        = '8.3.0'
    'azure cli' = '2.56.0'
}

# replace existing default modules with new setting
Set-AzureAutomationRuntimeDefaultModule -defaultPackage $defaultPackage -runtimeName 'CustomPSH_7.2'


# remove all default modules
Set-AzureAutomationRuntimeDefaultModule -defaultPackage @{} -runtimeName 'CustomPSH_7.2'

Get Runtime selected default modules

Get-AzureAutomationRuntimeSelectedDefaultModule

Make Runtime Environment copy

Copy-AzureAutomationRuntime -runtimeName "CustomPSH_7.2" -newRuntimeName "CustomPSH_7.2_v2"

Remove Runtime Environment

Remove-AzureAutomationRuntime -runtimeName 'CustomPSH_7.2'

Runbook functions

Here are some of the functions related to Runbooks

Get Runbook script content

Get-AzureAutomationRunbookContent -runbookName someRunbook -ResourceGroupName Automations -AutomationAccountName someAutomationAccount

Set Runbook script content

$content = @'
   Get-process notepad
   restart-service spooler
'@

Set-AzureAutomationRunbookContent -runbookName someRunbook -ResourceGroupName Automations -AutomationAccountName someAutomationAccount -content $content

Get Runtime used in selected Runbook

Get-AzureAutomationRunbookRuntime

Set Runbook Runtime

Set-AzureAutomationRunbookRuntime

Set Runbook description

Set-AzureAutomationRuntimeDescription

Start Runbook test run using selected Runtime

Useful if you want to automate testing of the new Runtimes a.k.a. that your Runbook will successfully end with this new Runtime (modules) version, before the final assignment.

Start-AzureAutomationRunbookTestJob -runtimeName "CustomPSH_7.2_v2" -runbookName "ExchangeSetAuditSettings"

Stop Runbook test run

Stop-AzureAutomationRunbookTestJob

Get Runbook test run output

# get the output as array of string
Get-AzureAutomationRunbookTestJobOutput -runbookName "ExchangeSetAuditSettings" -justText 'Output', 'Warning', 'Error', 'Exception'

# get the output as array of objects
Get-AzureAutomationRunbookTestJobOutput -runbookName "ExchangeSetAuditSettings"

Get Runbook test run status

# get test run status 
Get-AzureAutomationRunbookTestJobStatus -runbookName "ExchangeSetAuditSettings"

I came across a thread on Reddit discussing the use of on-demand remediations in Intune to retrieve basic client data. However, I couldn’t find any existing PowerShell function for this purpose, so I decided to create one myself.

Meet my shiny, brand-new Invoke-IntuneCommand function (part of the IntuneStuff module).

Use cases

• You want to run some one-time PowerShell code against your Windows devices ASAP

• You want to get some Windows clients' data back (is a service running, is an application installed,...)

How does Invoke-IntuneCommand work?

• New Intune remediation is created in the background, utilizing the code to be invoked within the detection component

• Remediation is invoked via an on-demand request for each selected device

• The function either waits for the remediation to complete or for the specified timeout to be reached (10 minutes by default, but can be overridden) in a which-comes-first manner

• Remediation code results are retrieved (and converted to an object if the result is a compressed JSON string)

• Remediation is deleted (this step can vary based on the used parameters and remediation invocation results)

The whole process can be nicely seen when Verbose parameter is used 👇

What does the Invoke-IntuneCommand output look like

Function Invoke-IntuneCommand returns a custom object for each device where the command was run.

The returned object contains several properties

• DeviceId - managed device ID (Intune ID)

• DeviceName - name of the device

• LastSyncDateTime - when it contacted Intune the last time

• ProcessedOutput - returned output converted to an object if only a compressed JSON string was returned

• Output - string output of the invoked command (just the last line!)

• Error - thrown error if any

• Status - overall invoked remediation status

  • pending if not being run

  • fail if some error was thrown

  • success if everything was ok

If your code throws an error, you will see the error message in Error property and Status will be fail

Requirements

• Module IntuneStuff

• Graph permissions

  • DeviceManagementConfiguration.Read.All

  • DeviceManagementManagedDevices.Read.All

  • DeviceManagementManagedDevices.PrivilegedOperations.All

• License to use Intune Remediation

  • Windows 10/11 Enterprise E3 or E5 (included in Microsoft 365 F3, E3, or E5)

  • Windows 10/11 Education A3 or A5 (included in Microsoft 365 A3 or A5)

  • Windows 10/11 Virtual Desktop Access (VDA) per user

Examples

Authenticate to Graph API with correct scopes

Connect-MgGraph -Scopes DeviceManagementConfiguration.Read.All, DeviceManagementManagedDevices.Read.All, DeviceManagementManagedDevices.PrivilegedOperations.All

Run some command against all clients

$deviceNameList = Get-MgBetaDeviceManagementManagedDevice -Filter "OperatingSystem eq 'Windows' and OwnerType eq 'company'" -all -Property DeviceName | select -ExpandProperty DeviceName

Invoke-Intunecommand -deviceName $deviceNameList -command "New-Item C:\temp2 -ItemType Directory" -Verbose

Create a folder on the selected clients

Invoke-Intunecommand -deviceName "PC-01" -command "New-Item C:\temp2 -ItemType Directory" -Verbose

In a few minutes (if the device is online) you should see an output similar to this one 👇

Hence folder C:\temp2 was created.

Check if the folder exists and return a simple string

$command = @'
if (Test-Path "C:\temp2") {
    Write-Output "Folder exists"
} else {
    Write-Output "Folder doesn't exist"
}
'@

$result = Invoke-Intunecommand -deviceName "PC-01" -command $command -Verbose

In a few minutes (if the device is online) you should see an output similar to this one 👇

Return an array of objects (of all running client PowerShell processes)

$command = @'
$result = Get-Process powershell | select processname, id
$result | ConvertTo-Json -Compress
'@

$result = Invoke-Intunecommand -deviceName "PC-01" -command $command -Verbose

# output the results
$result

# output just returned JSON string converted back to the object
$result.processedOutput

In a few minutes (if the device is online) you should see an output similar to this one 👇

Because we have converted the output to compressed JSON, it was automatically converted back to an object and saved in the ProcessedOutput property.

Maximize the amount of returned data by compression

If the output you need is over the 2048-character hard limit, you can reduce its length by compressing it using ConvertTo-CompressedString function (part of the CommonStuff module). This can make it 10x times smaller (but it depends on the output content solely)!

Invoke-Intunecommand function automatically tries to decompress the received output, so you don't have to worry about this part.

$command = @'
    $result = Get-Process powershell | select processname, id
    $result | ConvertTo-Json -Compress | ConvertTo-CompressedString
'@

# invoke selected command
$result = Invoke-Intunecommand -deviceName "PC-01" -command $command -Verbose

# output the results
$result

# output just returned compressed JSON string converted back to the object
$result.processedOutput

Adding command definition to the code block

Any command you run on the remote device needs to exist there. This specifically applies to the custom functions. You can add such a function directly to the invoked command like this

$command = @'
    # Get-SomeData definition is inside the code block defined manually
    function Get-SomeData {
        do some stuff...
    }

    Get-SomeData | ConvertTo-Json -Compress
'@

Or use parameter prependCommandDefinition 😎 like this

$command = @'
    # ConvertTo-CompressedString definition is added automatically thanks to 'prependCommandDefinition' parameter 
    $result = Get-Process powershell | select processname, id
    $result | ConvertTo-Json -Compress | ConvertTo-CompressedString
'@

# text definition of the ConvertTo-CompressedString function will be added to the command, so it doesn't matter whether it is available on the remote system
Invoke-Intunecommand -deviceName "PC-01" -prependCommandDefinition ConvertFrom-CompressedString -command $command -Verbose

Limitations

• Returned output is limited to 2048 chars (Intune inner limitation)

• Only the last output line is returned

  • hence if you run the following code write-output 'aaa'; write-output 'bbb'

  • the returned output will be just 'bbb'!

• Write-Host cannot be used, instead use Write-Output

• If the "helper" remediation is removed, any clients that have not already invoked it will be unable to do so

Tips

• Definitely check the function help (Get-Help Invoke-IntuneCommand -Full) to get more details & examples

• To get as much data back as possible, convert the output using ConvertTo-CompressedString function (part of the CommonStuff module) after converting it to the compressed JSON string. This way you can get 10x more data back. And the Invoke-IntuneCommand will try to decompress it automatically 👍

• Invoke the function with the Verbose parameter to obtain more detailed information, such as the remaining time until the deadline is reached

• If you wish to transform the result back into an object, ensure that your command returns a single result, specifically the compressed JSON

  • Get-Process powershell | select processname, id | ConvertTo-Json -Compress

• If your command throws an error, the whole invocation takes more time, because a dummy remediation command (exit 0) will be run too (because we are using remediation and if the detection part fails, the remediation part takes place)

• Helper remediations are named like _invCmd_<yyyy.MM.dd_HH:mm>

The official Find-MgGraphCommand function, which retrieves the parent module for Graph Mg* commands, is undoubtedly beneficial. However, the task of extracting all these commands (including those for direct Graph API calls) from analyzed code, remains a challenging and tedious process.

Let's meet my PowerShell function Get-CodeGraphModuleDependency (part of the module MSGraphStuff) that solves all these issues.

Introduction

Function Get-CodeGraphModuleDependency gets Graph PowerShell SDK modules that are needed to run selected code.

Under the hood, it uses my other, more universal function Get-CodeDependency (part of DependencySearch module) that returns all code dependencies by analyzing its AST and doing some other magic, to search for all official Mg* commands (like Get-MgUser, ...).

When Mg* commands are extracted, an official Find-MgGraphCommand command is used to get their hosting SDK modules.

Get-CodeGraphModuleDependency is part of the module MSGraphStuff.

Main features

• Extracts all official Mg* Graph commands from the given code and returns their parent PowerShell SDK modules

  • returns Microsoft.Graph.Users module for Get-MgUser, Microsoft.Graph.Identity.DirectoryManagement for Update-MgDevice, ...

• Extracts and returns explicitly imported PowerShell SDK modules

  • returns Microsoft.Graph.Users in case of Import-Module Microsoft.Graph.Users

• Supports recursive search across all code dependencies

  • so you can get the complete modules list not just for the code itself, but for all its dependencies too

The output of the Get-CodeGraphModuleDependency

If we send the function results to Out-GridView to get a graphical representation, we can get results similar to this 👇

As you can see there are several properties returned for each found module:

• Name - name of the Graph SDK module that is needed

• Version - version (if specified) of the Graph SDK module that is needed

  • for example when Import-Module with RequiredVersion parameter is used

• RequiredBy - the original code line where the command that requires this module was found

• DependencyPath - the whole path to the found command

  • useful when using goDeep parameter to understand where the command was found

Use cases

The following examples will be made against this test code

Can be downloaded from GitHub Gist.

Return Graph PowerShell SDK modules required by selected code

The following code will return only modules directly required by code in the selected script.

If there are some indirect dependencies (like calling another function that invokes some Graph commands itself), they won't be returned!

Get-CodeGraphModuleDependency -scriptPath C:\scripts\someGraphRelatedCode2.ps1 | ogv

The result will look like this 👇

When you compare the result with the test code you can notice that:

• unrelated commands like Get-Process are ignored

• specified module version in line with Import-Module gets its way to Version property

• each module is returned only once hence Microsoft.GraphApplications is returned for Get-MgApplication, but not for Update-MgApplication

  • to change this, use the switch allOccurrences

Return ALL Graph PowerShell SDK modules required by selected code and its dependencies

The following code will return all modules required by the code in the selected script, no matter if the module was needed in the code itself, or in the called functions, etc.

Get-CodeGraphModuleDependency -scriptPath C:\scripts\someGraphRelatedCode2.ps1 -goDeep | ogv

As you can see there are some new results returned. Those two new results belong to 3rd party function Remove-O365OrphanedMailbox that is being called in the test script. And thanks to goDeep parameter it was now searched for the dependencies too.

Now that you know how to use this function don't be afraid to test it against your code. Hopefully, this will help you on your Graph API journey 👍

Graph API can be quite hard to understand, mainly the scope/permission part of it. One thing is to write the correct code and the second is knowing, what permission will you need to run it successfully 😄

Not to mention running some not-very-well-documented 3rd party code.

In this post, I will show you my solution to this problem. And that is my PowerShell function Get-CodeGraphPermissionRequirement (part of the module MSGraphStuff).

Introduction

Function Get-CodeGraphPermissionRequirement gets Graph API permissions (scopes) that are needed to run selected code.

Under the hood, it uses my other, more universal function Get-CodeDependency (part of DependencySearch module) that returns all code dependencies by analyzing its AST and doing some other magic, to search for all commands interacting with the Graph API.

Official Graph SDK commands and direct Graph API calls are both processed 😎

Get-CodeGraphPermissionRequirement is part of the module MSGraphStuff.

Main features

• Supports getting permissions for official Mg* Graph SDK commands

  • Get-MgUser, Update-MgDevice, ...

• Supports getting permissions for direct API calls invoked via Invoke-MsGraphRequest, Invoke-RestMethod, Invoke-WebRequest and their aliases

  • a.k.a. calling GET, POST, ... requests against https://graph.microsoft.com/v1.0/users and such

  • supports also usage of variables in place of IDs in the URI

    • a.k.a. v1.0/groups/$groupId/settings will be correctly recognized and processed

• Supports recursive search across all code dependencies

  • so you can get the complete permissions list not just for the code itself, but for all its dependencies too

• Recognizes v1.0 vs beta API calls

Drawbacks

• Official command Find-MgGraphCommand is used to translate command/URI calls to required permissions

  • doesn't contain permissions for all commands/URIs (but this will be hopefully solved in the future)

  • returns all permissions that can be used, not just the least one (but I am trying to solve this on my own)

• URIs passed via parameter splatting or through variables aren't detected right now

  • but you will be notified about such issue, so you can solve this manually

The output of the Get-CodeGraphPermissionRequirement

If we send the function results to Out-GridView to get a graphical representation, we can get results similar to this

As you can see there are several properties returned:

• Command - detected command that interacts with Graph API

  • official Mg* commands or direct API web requests

• Name - name of the Graph permission/scope that the command needs

• Description - Graph permission description

• FullDescription - Graph permission full description

• Type - Graph permission type (application, delegated)

• InvokedAs - the original code line where the command was found

  • helpful if some command was found multiple times to identify the calls, also in cases where URI cannot be recognized, to find such line and do the manual code analysis

• DependencyPath - the whole path to the found command

  • useful when using goDeep parameter to understand where this command was found

• ApiVersion - detected Api version (v1.0 or beta)

• Method - request method (GET, POST, DELETE, ...)

• Error - error message if there was some problem

Use cases

The following examples will be made against this test code

Can be downloaded from GitHub Gist.

Return Graph permissions required by selected code

The following code will return only application permissions for the selected script.

If there are some indirect dependencies (like calling another function that invokes some Graph API itself), they won't be returned!

Get-CodeGraphPermissionRequirement -scriptPath C:\scripts\someGraphRelatedCode.ps1 -permType "application" | Out-GridView

The result will look like this 👇

Except for two command calls the Get-CodeGraphPermissionRequirement function resolved all needed permissions for us.

• The first problematic one is Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/beta/identity/conditionalAccess/policies" -Body $body where the official Find-MgGraphCommand function doesn't return anything for this particular URI and PATCH method.

• The second one is Invoke-MgGraphRequest -OutputType PSObject -Uri $msGraphPermissionsRequestUri where instead of plaintext URI is used some variable which is currently not supported by my function.

The last thing that may grab your attention is the missing output for the custom function Remove-O365OrphanedMailbox. Trust me, this function uses Graph API, but because we haven't specified goDeep parameter when calling Get-CodeGraphPermissionRequirement, just the specified code was checked, but none of the used functions/modules. We will look into this in the next example though.

Return ALL Graph permissions required to run selected code (direct and indirect)

The following code will return delegated and application permissions for selected script and all its dependencies (used functions/modules)

# cache available modules to speed up repeated 'Get-CodeGraphPermissionRequirement' function invocations
$availableModules = @(Get-Module -ListAvailable)

Get-CodeGraphPermissionRequirement -scriptPath C:\scripts\someGraphRelatedCode.ps1 -goDeep -availableModules $availableModules -permType "application", "delegated" | Out-GridView

The result is very similar to the first example.

As you can see there are two differences though.

• Delegated permissions are returned too

• A lot of new commands were detected!

  • If we scroll to the right, we can see in the DependencyPath column that all these commands were found in the Remove-O365OrphanedMailbox function.

    

  • This function is defined outside the code we've analyzed, but thanks to goDeep parameter it was processed too!

Returned permission optimization

As I said, my function uses an official Find-MgGraphCommand under the hood to retrieve command/URI permissions and this function is chatty. It returns more permissions that are needed to be more precise.

For example Get-MgUser command, do you really think, Directory.ReadWrite.All or Directory.ReadWrite.All are needed? I don't think so.

Therefore I remove such permission from the output automatically.

But if you for some reason want to retrieve all these permissions, just use dontFilterPermissions parameter.

Now that you know how to use this function don't be afraid to test it against your code. Hopefully, this will help you on your Graph API journey 👍