A CSV-driven toolkit for migrating every Azure Key Vault in a tenant from the legacy access policy permission model to Azure RBAC, without losing anyone's access along the way. Two PowerShell scripts, an Azure Monitor workbook, pipeline definitions for Azure DevOps and GitHub Actions, and a runbook. Used to migrate a multi-subscription production tenant in waves with zero access incidents.
1 Export --> 2 Consolidate --> 3 Plan + Groups --> 4 Assign --> 5 Verify --> 6 Flip
- Export every access policy on every vault in the tenant to CSV. Identities are resolved through Microsoft Graph, legacy
allpermissions are expanded, the least-privileged built-in role that covers each entry is suggested from the live role definitions, and 90 days of real usage from Key VaultAuditEventlogs is joined on. - Consolidate in a spreadsheet: decide per identity whether it joins an admin group (
Group), gets a direct role (Direct), is dropped (Drop) or is out of scope (Skip), and assign a wave. - Plan prints exactly what will change. Groups creates the Entra security groups and members.
- Assign creates the role assignments at vault or resource group scope. On an access policy vault these are inert, so this step has no user impact.
- Verify re-reads live state, expands transitive group membership, and proves every access policy identity keeps its data actions after the flip. Exit code 1 on any gap.
- Flip sets
EnableRbacAuthorization = true, one wave at a time. Access policies stay on the vault, so Rollback is a single property write.
Everything is idempotent and every state change honours -WhatIf. Full detail in docs/runbook.md.
Connect-AzAccount -Tenant <tenantId>
# 1. Inventory (Reader + directory read; workspace ID optional)
.\scripts\Export-KvAccessPolicyInventory.ps1 -OutputFolder .\KvInventory -LogAnalyticsWorkspaceId <workspace customer ID>
# 2. Fill TargetGroupName / TargetRole / Action / Wave in Excel, save as KvPlan-<tenant>.csv
# (see data/KvPlan-sample.csv and docs/plan-csv-reference.md)
# 3 to 6. Execute wave 1 with resource group scoped admin groups
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Plan -GroupScope ResourceGroup -Wave 1
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Groups -Wave 1
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Assign -GroupScope ResourceGroup -Wave 1
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Verify -Wave 1
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Flip -Wave 1 -WhatIf
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Flip -Wave 1
# If the soak period shows ForbiddenByRbac denials
.\scripts\Invoke-KvRbacMigration.ps1 -PlanCsv .\KvPlan-<tenant>.csv -Action Rollback -VaultName <vault>| Path | Contents |
|---|---|
scripts/Export-KvAccessPolicyInventory.ps1 |
Step 1. Inventory of access policies, vault-scope role assignments and usage. |
scripts/Invoke-KvRbacMigration.ps1 |
Steps 3 to 6 plus Rollback, driven by the plan CSV. |
data/KvPlan-sample.csv |
Fictional plan showing every Action, multi-role rows, TargetScope overrides and platform groups. |
data/AccessPolicyRBACMapping.csv |
Access policy permission to RBAC data action mapping (from Microsoft's compare tool). Also embedded in both scripts. |
workbooks/ |
KeyVault-Audit.workbook.json (six tabs, including RBAC Migration), a deploy script and ARM template. Details. |
pipelines/ |
Azure DevOps pipeline with approval-gated state changes. |
.github/workflows/ |
GitHub Actions equivalent, plus CI (PSScriptAnalyzer + Pester). |
docs/ |
Runbook, plan CSV reference, group naming convention, permissions, pipelines, change record template, rollback. |
tests/ |
Pester structure tests (no Azure connection needed). |
| Column | You set it to |
|---|---|
Action |
Group (add identity to an Entra group that holds the role), Direct (role straight on the identity), Drop (do not carry over), Skip (out of scope; a vault whose rows are all Skip is never touched). |
TargetGroupName |
For Group rows. Suggested standard: RBAC_RG_<ResourceGroup>_KVAdmin for one RG, RBAC_KV_<Platform>_Admin for a platform spanning several RGs, with the scope rule in TargetGroupDescription. |
TargetRole |
One or more role names, ; separated. Start from the exported SuggestedRole. |
TargetScope |
Optional resource group or subscription ID that overrides the scope for that row. |
Wave |
Any label; -Wave filters on it. |
Scope choice: -GroupScope ResourceGroup assigns group roles once per resource group, covering current and future vaults in it. The script warns when an RG assignment also reaches vaults outside the run and whether those are already live (RBAC) or inert (access policy). TargetScope does the same per row.
- Nothing changes until
Groups.Export,PlanandVerifyare read only. - Role assignments are created before the flip and are ignored by access policy vaults, so
Assigncannot break anything on an unflipped vault. Verifycompares the mapped data actions of every live access policy against the effective RBAC coverage (direct, inherited and via transitive group membership) and refuses to pass with aGAPorNO-ROLE.Flipnever removes access policies.Rollbackrestores the previous model instantly.- Orphaned and foreign-tenant identities are never added to groups or given assignments, whatever the plan says.
- Every run writes a CSV log (verify report, flip and rollback change logs) for the change record.
- Windows PowerShell 5.1 or PowerShell 7 with
Az.Accounts,Az.Resources,Az.KeyVault,Az.Monitor(andAz.OperationalInsightsfor usage). Az 16.3.0 or later recommended. - Rights per step in docs/permissions.md. Export needs Reader plus directory read; Flip needs Owner-level rights on the vaults because the Key Vault resource provider demands unrestricted
roleAssignments/writeto change the permission model. - For usage enrichment and the workbook: diagnostic settings on the vaults sending
AuditEventto a Log Analytics workspace in Azure Diagnostics mode.
The access policy to RBAC data action mapping comes from Microsoft's Azure/KeyVault-AccessPolicyToRBAC-CompareTool (MIT, now archived). That tool compares one vault interactively; this toolkit takes the same mapping and applies it tenant-wide with a plan, a gate and a rollback.
MIT.