An Identity Governance and Administration (IGA) PowerShell module for exporting, monitoring, detecting drift, and reconciling Azure Role-Based Access Control (RBAC) role assignments across Subscriptions and Management Groups.
- Key Features
- Prerequisites & Requirements
- Installation
- Exported Functions
- Export-AzRoleAccessGuard
- Invoke-AzRoleAccessGuardDrifft
- Publish JUnit results in Azure DevOps
- Compare-AzRoleAccessGuardExport
- Update-AzRoleAccessGuard
- Clear-AzRoleOrphaned
- Governance Workflow Example
- Snapshot Export: Export live Azure RBAC role assignments across Management Groups and Subscriptions into JSON, HTML, CSV, or deployable AVM-based Bicep.
- Drift Detection: Compare current Azure access against a reference baseline snapshot and produce detailed drift reports in Terminal, JSON, HTML, CSV, or JUnit XML (ideal for CI/CD pipelines).
- Automated Remediation: Reconcile detected access drift by granting missing role assignments or revoking unauthorized access.
- Orphaned Access Cleanup: Identify and clean up orphaned role assignments where security principals no longer exist in Microsoft Entra ID.
- PowerShell: 5.1 (Desktop) or PowerShell 7+ (Core)
- Required Modules:
Az.Accounts(>= 15.2)Az.Resources(>= 15.2)
Install PowerShell.IGA.AccessGuard from the PowerShell Gallery for the current user, including its required modules:
Install-Module -Name PowerShell.IGA.AccessGuard -Repository PSGallery -Scope CurrentUser -IncludeDependencies
Import-Module -Name PowerShell.IGA.AccessGuardExports a snapshot of active Azure RBAC role assignments across Subscriptions and Management Groups. Bicep output uses the AVM role-assignment modules and omits orphaned principals and assignments with missing or unknown role names.
Export-AzRoleAccessGuard
[-OutputFormat <String>]
[-OutputPath <String>]
[-SubscriptionOnly]
[-ManagementGroupOnly]
[-IncludeInherited]-OutputFormat: Format of the output snapshot (Json,Html,Csv,Bicep). Default isJson.-OutputPath: Destination file path without file extension. Default is./output.-SubscriptionOnly: Export role assignments for Subscriptions only.-ManagementGroupOnly: Export role assignments for Management Groups only.-IncludeInherited: Include role assignments inherited from parent scopes.
# Export all Subscriptions and Management Groups baseline to JSON
Export-AzRoleAccessGuard -OutputFormat Json -OutputPath "C:\baselines\azure-rbac-baseline"
# Export Subscriptions only into an HTML report
Export-AzRoleAccessGuard -OutputFormat Html -SubscriptionOnly -OutputPath "C:\reports\sub-rbac"
# Export Management Group and Subscription assignments as an AVM-based Bicep deployment
Export-AzRoleAccessGuard -OutputFormat Bicep -OutputPath "C:\baselines\azure-rbac"The generated Bicep template targets the tenant scope and can be deployed with
az deployment tenant create --location <location> --template-file C:\baselines\azure-rbac.bicep.
It references the AVM management-group scope module
and subscription scope module,
using versions 0.1.2 and 0.1.1, respectively. Inherited assignments are emitted once at their
source scope. The template includes Bicep metadata for the generating tool and UTC export time,
separate // MARK: sections for management-group and subscription assignments, and one AVM module
per deployable assignment. Orphaned principals and assignments with missing or unknown role names
are omitted; AVM telemetry is disabled in generated modules.
Example output (IDs and timestamp are illustrative):
targetScope = 'tenant'
metadata generatedBy = 'PowerShell.IGA.AccessGuard'
metadata exportedAtUtc = '2026-10-02T20:10:14Z'
// MARK: Management Group Role Assignments
module mod_role_assignment_mg_reader_aaaaaaaa_aaaa_aaaa_aaaa_aaaaaaaaaaaa 'br/public:avm/res/authorization/role-assignment/mg-scope:0.1.2' = {
scope: managementGroup('Platform')
params: {
principalId: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
roleDefinitionIdOrName: 'Reader'
managementGroupId: 'Platform'
principalType: 'Group'
enableTelemetry: false
}
}
// MARK: Subscription Role Assignments
module mod_role_assignment_sub_contributor_bbbbbbbb_bbbb_bbbb_bbbb_bbbbbbbbbbbb 'br/public:avm/res/authorization/role-assignment/sub-scope:0.1.1' = {
scope: subscription('cccccccc-cccc-cccc-cccc-cccccccccccc')
params: {
principalId: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'
roleDefinitionIdOrName: 'Contributor'
principalType: 'ServicePrincipal'
enableTelemetry: false
}
}Compares current live Azure RBAC role assignments against a reference baseline file to identify permission drift (added, removed, or modified assignments).
Invoke-AzRoleAccessGuardDrifft
[-ReferenceFile] <String>
[[-OutputPath] <String>]
[[-OutputFormat] <String>]-ReferenceFile: Path to the baseline snapshot file (JSON) generated byExport-AzRoleAccessGuard.-OutputPath: Destination file path for saving the drift report without extension. Default is./output_diff.-OutputFormat: Drift report output format (Terminal,Json,Html,Csv,JUnit,Bicep). Default isJson.
# Display drift report directly in the terminal table view
Invoke-AzRoleAccessGuardDrifft -ReferenceFile "C:\baselines\azure-rbac-baseline.json" -OutputFormat Terminal
# Output JUnit XML report for Azure DevOps or GitHub Actions CI/CD pipelines
Invoke-AzRoleAccessGuardDrifft -ReferenceFile "C:\baselines\azure-rbac-baseline.json" -OutputFormat JUnit -OutputPath "./drift-results"
# Export AVM Bicep modules for baseline assignments missing from Azure
Invoke-AzRoleAccessGuardDrifft -ReferenceFile "C:\baselines\azure-rbac-baseline.json" -OutputFormat Bicep -OutputPath "./drift-to-add"Bicep drift output uses the same AVM management-group (0.1.2) and subscription (0.1.1)
modules as the full export. It includes missing baseline assignments to add. Assignments present in
Azure but absent from the baseline require removal; because these AVM modules only create role
assignments, those changes are excluded and reported as a warning.
On an Azure-authenticated agent with the module installed, generate the JUnit report and publish it
with PublishTestResults@2:
trigger:
- main
pool:
vmImage: ubuntu-latest
steps:
- pwsh: |
$driftParams = @{
ReferenceFile = "$(Build.SourcesDirectory)/baseline.json"
OutputFormat = 'JUnit'
OutputPath = "$(Build.SourcesDirectory)/output_diff"
}
Invoke-AzRoleAccessGuardDrifft @driftParams
displayName: Generate JUnit drift results
- task: PublishTestResults@2
condition: succeededOrFailed()
inputs:
testResultsFormat: JUnit
testResultsFiles: output_diff.xml
searchFolder: '$(Build.SourcesDirectory)'
failTaskOnFailedTests: falseThe published drift findings appear in the Azure DevOps Tests view:
Compares two previously exported role assignment JSON files, for example a full export (-IncludeInherited) against a baseline export, without querying Azure.
Compare-AzRoleAccessGuardExport
[-FullExportFile] <String>
[-ExportFile] <String>
[[-OutputPath] <String>]
[[-OutputFormat] <String>]-FullExportFile: Path to the full export file (JSON) treated as the current/actual state.-ExportFile: Path to the baseline export file (JSON) treated as the reference/desired state.-OutputPath: Destination file path for saving the comparison report without extension. Default is./output_export_diff.-OutputFormat: Comparison report output format (Terminal,Json,Html,Csv,JUnit). Default isJson.
# Compare a full export against the baseline export and print results to the terminal
Compare-AzRoleAccessGuardExport -FullExportFile "C:\exports\full-export.json" -ExportFile "C:\baselines\azure-rbac-baseline.json" -OutputFormat Terminal
# Write an HTML comparison report
Compare-AzRoleAccessGuardExport -FullExportFile "C:\exports\full-export.json" -ExportFile "C:\baselines\azure-rbac-baseline.json" -OutputFormat Html -OutputPath "./export-comparison"Reconciles Azure RBAC assignments by applying corrections specified in a drift report file (output_diff.json). Adds missing role assignments and revokes unauthorized ones.
Update-AzRoleAccessGuard
[[-DriftFile] <String>]
[-Force]
[-WhatIf]
[-Confirm]-DriftFile: Path to the drift report JSON file produced byInvoke-AzRoleAccessGuardDrifft. Default is./output_diff.json.-Force: Suppresses interactive confirmation prompts for unattended pipelines.-WhatIf: Previews changes that would be executed without modifying Azure resources.-Confirm: Prompts for explicit confirmation before performing actions.
# Preview reconciliation actions without making actual changes
Update-AzRoleAccessGuard -DriftFile "./output_diff.json" -WhatIf
# Enforce desired state non-interactively
Update-AzRoleAccessGuard -DriftFile "./output_diff.json" -ForceIdentifies and optionally removes orphaned role assignments in Azure (assignments pointing to deleted or missing Entra ID principals).
Clear-AzRoleOrphaned
[-Remove]
[-GenerateReport]
[-OutputFormat <String>]
[-OutputPath <String>]
[-WhatIf]
[-Confirm]-Remove: Enables removal of identified orphaned role assignments. When omitted, runs in report-only dry-run mode.-GenerateReport: Exports the orphaned role assignments report file.-OutputFormat: Format for the report (Json,Html,Csv,JUnit). Default isJson.-OutputPath: Base output file path without extension. Default is.\output_unknow.
# Generate an HTML report of orphaned role assignments without removing them
Clear-AzRoleOrphaned -GenerateReport -OutputFormat Html -OutputPath "./orphaned_report"
# Remove all orphaned role assignments interactively
Clear-AzRoleOrphaned -Removeflowchart TD
subgraph Step1["1. Export Baseline"]
A[Live Azure Environment] -->|Export-AzRoleAccessGuard| B[(baseline.json)]
end
subgraph Step2["2. Detect Drift"]
B -->|Reference Baseline| C[Invoke-AzRoleAccessGuardDrifft]
A -->|Current Live State| C
C -->|Detect Differences| D[(output_diff.json)]
end
subgraph Step3["3. Reconcile to Baseline"]
D -->|Dry Run Preview| E[Update-AzRoleAccessGuard -WhatIf]
D -->|Enforce Compliance| F[Update-AzRoleAccessGuard -Force]
F -->|Remediate Access Drift| A
end
- Export Baseline:
Export-AzRoleAccessGuard -OutputFormat Json -OutputPath "./baseline"
- Detect Drift:
Invoke-AzRoleAccessGuardDrifft -ReferenceFile "./baseline.json" -OutputFormat Json -OutputPath "./output_diff"
- Reconcile to Baseline:
Update-AzRoleAccessGuard -DriftFile "./output_diff.json" -WhatIf Update-AzRoleAccessGuard -DriftFile "./output_diff.json" -Force
- Clean Up Orphaned Assignments:
Clear-AzRoleOrphaned -Remove -GenerateReport -OutputFormat Html
