Repository navigation
feat(entra): add Conditional Access policy plan support #2733
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
FiraSenax
wants to merge
15
commits into
maester365:main
Choose a base branch
from
FiraSenax:codex/conditional-access-policy-plans
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+1,669
−84
Open
Changes from 4 commits
Commits
Show all changes
15 commits
Select commit
Hold shift + click to select a range
2b365f8
fix(entra): include Conditional Access policy plans in checks
FiraSenax 61e0f34
build(website): regenerate policy plan taxonomy data
FiraSenax ba5b7fd
test(entra): update plan taxonomy and selection expectations
FiraSenax 2703650
fix(entra): use existing policy resource classification for plan owners
FiraSenax dc8fa7d
test(entra): suppress state-change warnings for pure fixture copies
FiraSenax 52dd4fc
fix(entra): preserve plan rule identity throughout reporting
FiraSenax b7a56af
Merge branch 'main' into codex/conditional-access-policy-plans
SamErde 436573e
fix(entra): handle escaped rule names and equivalent tenant scopes
FiraSenax 20d4bc0
fix(report): escape Conditional Access names in CIS tables
FiraSenax 92da191
Merge main into codex/conditional-access-policy-plans
FiraSenax 3b8d487
fix(tests): restore UTF-8 BOM in private pack request tests
FiraSenax bfe9a74
fix(tests): scope CIS reporting discovery cases explicitly
FiraSenax ee5990e
chore(tests): defer unrelated BOM correction to #2795
FiraSenax 7a783c0
Merge upstream main into Conditional Access policy plan support
FiraSenax df56fbc
docs(entra): record reader-role policy plan validation
FiraSenax File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
45 changes: 45 additions & 0 deletions
45
powershell/internal/services/entra/ConvertTo-MtConditionalAccessPolicy.ps1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| function ConvertTo-MtConditionalAccessPolicy { | ||
| <# | ||
| .SYNOPSIS | ||
| Projects a plan rule into the policy shape used by Maester's Conditional Access checks. | ||
|
|
||
| .DESCRIPTION | ||
| Preserves the real rule ID, state, original rule conditions and controls. Exposes inherited effective conditions, | ||
| grantControls and sessionControls at the same paths as a standalone policy, with explicit parent-plan metadata. | ||
| Never mutates the cached plan or rule and never treats a plan owner as an administrator or a rule assignment. | ||
| #> | ||
| [CmdletBinding()] | ||
| [OutputType([pscustomobject])] | ||
| param( | ||
| [Parameter(Mandatory)] [object] $Plan, | ||
| [Parameter(Mandatory)] [object] $Rule | ||
| ) | ||
|
|
||
| if ([string]::IsNullOrWhiteSpace([string]$Plan.id) -or [string]::IsNullOrWhiteSpace([string]$Rule.id)) { | ||
| throw 'Conditional Access plans and rules must have IDs before they can be evaluated.' | ||
| } | ||
| if ($Rule.state -notin @('enabled', 'disabled', 'enabledForReportingButNotEnforced')) { | ||
| throw "Conditional Access rule '$($Rule.id)' has an unsupported state '$($Rule.state)'." | ||
| } | ||
| $parent = $Plan | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable | ||
| $copy = $Rule | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable | ||
| if (-not $copy.controls -or (-not $copy.controls.grantControls -and -not $copy.controls.sessionControls)) { | ||
| throw "Conditional Access rule '$($Rule.id)' has no supported enforcement controls." | ||
| } | ||
| $copy['@odata.type'] = '#microsoft.graph.conditionalAccessPolicyRule' | ||
| $copy['ruleConditions'] = $copy.conditions | ||
| try { | ||
| $copy['conditions'] = Merge-MtConditionalAccessCondition -Shared $parent.sharedConditions -Rule $copy.conditions | ||
| } catch { | ||
| throw "Cannot evaluate rule '$($Rule.id)' in plan '$($Plan.id)': $($_.Exception.Message)" | ||
| } | ||
| $copy['grantControls'] = $copy.controls.grantControls | ||
| $copy['sessionControls'] = $copy.controls.sessionControls | ||
| $copy['displayName'] = "[Plan: $($Plan.displayName)] [Rule: $($Rule.displayName)]" | ||
| $copy['planId'] = $Plan.id | ||
| $copy['planDisplayName'] = $Plan.displayName | ||
| $copy['planOwners'] = @($Plan.owners) | ||
| $copy['sharedConditions'] = $parent.sharedConditions | ||
| $copy['sourceType'] = 'PolicyPlanRule' | ||
| return [pscustomobject]$copy | ||
| } | ||
78 changes: 78 additions & 0 deletions
78
powershell/internal/services/entra/Merge-MtConditionalAccessCondition.ps1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| function Merge-MtConditionalAccessCondition { | ||
| <# | ||
| .SYNOPSIS | ||
| Combines inherited and rule-specific Conditional Access conditions without overwriting exclusions. | ||
|
|
||
| .DESCRIPTION | ||
| Merges Graph condition dictionaries recursively and unions collection values. Null and empty optional | ||
| values do not erase inherited targeting. Incompatible scalar values, including conflicting filter expressions, | ||
| terminate the read: inventing a lossy effective policy could make an uncovered scenario pass a security check. | ||
| Inputs are JSON-compatible copies owned by the policy adapter, not objects in the Graph session cache. | ||
| #> | ||
| [CmdletBinding()] | ||
| param( | ||
| [AllowNull()] [object] $Shared, | ||
| [AllowNull()] [object] $Rule, | ||
| [string] $PropertyPath = 'conditions' | ||
| ) | ||
|
|
||
| if ($null -eq $Shared) { Write-Output -NoEnumerate -InputObject $Rule; return } | ||
| if ($null -eq $Rule) { Write-Output -NoEnumerate -InputObject $Shared; return } | ||
|
|
||
| if ($Shared -is [System.Collections.IDictionary] -and $Rule -is [System.Collections.IDictionary]) { | ||
| # Guest type and tenant membership form a pair. Unioning both independently invents cross-products | ||
| # (type A in tenant X plus type B in tenant Y must not become both types in both tenants). | ||
| if ($PropertyPath -match '\.(includeGuestsOrExternalUsers|excludeGuestsOrExternalUsers)$') { | ||
| $sharedTypes = @(([string]$Shared.guestOrExternalUserTypes -split ',') | Sort-Object -Unique) -join ',' | ||
| $ruleTypes = @(([string]$Rule.guestOrExternalUserTypes -split ',') | Sort-Object -Unique) -join ',' | ||
| $sharedTenants = $Shared.externalTenants | ConvertTo-Json -Depth 100 -Compress | ||
| $ruleTenants = $Rule.externalTenants | ConvertTo-Json -Depth 100 -Compress | ||
| if ($sharedTypes -ne $ruleTypes -and $sharedTenants -ne $ruleTenants) { | ||
|
FiraSenax marked this conversation as resolved.
Resolved
|
||
| throw "Cannot safely combine guest types and tenant sets at '$PropertyPath' without broadening the targeting." | ||
| } | ||
| } | ||
| # The all-external-tenants discriminator denotes the union's entire tenant set. | ||
| if ($PropertyPath -like '*.externalTenants' -and ($Shared.membershipKind -eq 'all' -or $Rule.membershipKind -eq 'all')) { | ||
| $all = if ($Shared.membershipKind -eq 'all') { $Shared } else { $Rule } | ||
| Write-Output -NoEnumerate -InputObject $all | ||
| return | ||
| } | ||
| $merged = [ordered]@{} | ||
| $keys = @(@($Shared.Keys) + @($Rule.Keys) | Select-Object -Unique) | ||
| foreach ($key in $keys) { | ||
| if ($key -like '*@odata.context') { continue } | ||
| $merged[$key] = Merge-MtConditionalAccessCondition -Shared $Shared[$key] -Rule $Rule[$key] -PropertyPath "$PropertyPath.$key" | ||
| } | ||
| Write-Output -NoEnumerate -InputObject $merged | ||
| return | ||
| } | ||
|
|
||
| if ($Shared -is [System.Collections.IList] -and $Rule -is [System.Collections.IList]) { | ||
| $union = [System.Collections.Generic.List[object]]::new() | ||
| $seen = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase) | ||
| foreach ($value in @($Shared) + @($Rule)) { | ||
| $key = ConvertTo-Json -InputObject $value -Depth 100 -Compress | ||
| if ($seen.Add($key)) { $union.Add($value) } | ||
| } | ||
| # These collection properties use All as a wildcard, not an additional narrowing condition. | ||
| if ($PropertyPath -match '\.(includeUsers|includeApplications|includePlatforms|includeLocations|clientAppTypes)$') { | ||
| $all = @($union | Where-Object { $_ -is [string] -and $_ -eq 'all' }) | ||
| if ($all.Count -gt 0) { Write-Output -NoEnumerate -InputObject @($all[0]); return } | ||
| } | ||
| Write-Output -NoEnumerate -InputObject $union.ToArray() | ||
| return | ||
| } | ||
|
|
||
| if ($Shared -is [string] -and [string]::IsNullOrWhiteSpace($Shared)) { Write-Output -NoEnumerate -InputObject $Rule; return } | ||
| if ($Rule -is [string] -and [string]::IsNullOrWhiteSpace($Rule)) { Write-Output -NoEnumerate -InputObject $Shared; return } | ||
| if (($Shared | ConvertTo-Json -Depth 100 -Compress) -ceq ($Rule | ConvertTo-Json -Depth 100 -Compress)) { | ||
| Write-Output -NoEnumerate -InputObject $Shared | ||
| return | ||
| } | ||
| if ($Shared -is [string] -and $Rule -is [string] -and | ||
| $PropertyPath -match '\.(guestOrExternalUserTypes|insiderRiskLevels|agentIdRiskLevels|transferMethods)$') { | ||
| $flags = @(@($Shared -split ',') + @($Rule -split ',') | ForEach-Object { $_.Trim() } | Where-Object { $_ } | Select-Object -Unique) | ||
| return $flags -join ',' | ||
| } | ||
| throw "Cannot safely combine Conditional Access plan and rule values at '$PropertyPath'. The inventory is incomplete; use a scenario evaluation for this condition instead of assuming coverage." | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
57 changes: 42 additions & 15 deletions
57
powershell/public/services/entra/Get-MtConditionalAccessPolicy.ps1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,26 +1,53 @@ | ||
| function Get-MtConditionalAccessPolicy { | ||
| <# | ||
| .Synopsis | ||
| Returns all the Conditional Access policies in the tenant. | ||
| .SYNOPSIS | ||
| Returns standalone Conditional Access policies and effective policy plan rules. | ||
|
|
||
| .Description | ||
| Returns all the Conditional Access policies in the tenant. | ||
| .DESCRIPTION | ||
| Reads standalone policies and beta policy plans through the Graph session cache. Each plan rule is projected | ||
| into the policy shape used by existing checks: inherited conditions are combined without dropping exclusions, | ||
| and nested grant/session controls are exposed at the policy level. The rule retains its own ID and state, | ||
| with planId, planDisplayName, planOwners, sourceType, sharedConditions and ruleConditions identifying its source. | ||
| Owners are metadata only. Disabled and report-only rules retain their states and are not promoted to enabled. | ||
| An empty plan inventory is valid. A failed read or an unsafe condition combination terminates the inventory | ||
| instead of presenting partial data as complete. Reading requires CA read access, not write permissions. | ||
|
|
||
| .Example | ||
| Get-MtConditionalAccessPolicy | ||
| .PARAMETER StandaloneOnly | ||
| Returns only standalone policies, without reading the preview plans endpoint. This is an explicit inventory | ||
| selection for callers that need original Graph policy objects, not a fallback used by security checks. | ||
|
|
||
| .PARAMETER DisableCache | ||
| Forwards an explicit diagnostic caller's cache choice. Security checks leave this switch unset. | ||
|
|
||
| .EXAMPLE | ||
| Get-MtConditionalAccessPolicy | Where-Object state -EQ enabled | ||
|
|
||
| Returns enabled standalone policies and enabled plan rules with effective conditions. | ||
|
|
||
| .EXAMPLE | ||
| Get-MtConditionalAccessPolicy -StandaloneOnly | ||
|
|
||
| Returns the standalone policy inventory without making a plans request. | ||
|
|
||
| .LINK | ||
| https://maester.dev/docs/commands/Get-MtConditionalAccessPolicy | ||
| #> | ||
| [CmdletBinding()] | ||
| param( | ||
| # Specify if this request should skip cache and go directly to Graph. | ||
| [Parameter(Mandatory = $false)] | ||
| [Switch]$DisableCache | ||
| ) | ||
|
|
||
| Write-Verbose -Message "Getting Conditional Access policies." | ||
| [CmdletBinding()] | ||
| [OutputType([object[]])] | ||
| param( | ||
| [switch] $StandaloneOnly, | ||
| [switch] $DisableCache | ||
| ) | ||
|
|
||
| return Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/policies' -ApiVersion beta -DisableCache:$DisableCache | ||
| Write-Verbose -Message 'Reading standalone Conditional Access policies and effective plan rules.' | ||
| $policies = @(Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/policies' -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop) | ||
| if ($StandaloneOnly) { return $policies } | ||
|
|
||
| $effectiveRules = [System.Collections.Generic.List[object]]::new() | ||
| foreach ($plan in @(Get-MtConditionalAccessPolicyPlan -DisableCache:$DisableCache -ErrorAction Stop)) { | ||
| foreach ($rule in @($plan.rules)) { | ||
| $effectiveRules.Add((ConvertTo-MtConditionalAccessPolicy -Plan $plan -Rule $rule)) | ||
| } | ||
| } | ||
| return @($policies) + @($effectiveRules.ToArray()) | ||
| } |
47 changes: 47 additions & 0 deletions
47
powershell/public/services/entra/Get-MtConditionalAccessPolicyPlan.ps1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| function Get-MtConditionalAccessPolicyPlan { | ||
| <# | ||
| .SYNOPSIS | ||
| Returns Conditional Access policy plans with their complete rule inventories. | ||
|
|
||
| .DESCRIPTION | ||
| Reads the beta plans and rules endpoints through Maester's Graph session cache. Rules are kept in their | ||
| original Graph shape, including controls and rule-specific conditions. Shared conditions and owners stay | ||
| on the parent plan. Empty plans inventories return no objects; failed reads terminate instead of hiding plans. | ||
| This preview API requires CA read access. Policy.Read.All is sufficient; write permissions are not required. | ||
|
|
||
| .PARAMETER MetadataOnly | ||
| Reads only plan metadata and does not request child rules. Useful for accountability checks. | ||
|
|
||
| .PARAMETER DisableCache | ||
| Forwards an explicit diagnostic caller's cache choice to every inventory request. Security checks leave the | ||
| switch unset so that they use the same tenant snapshot as the rest of the Maester run. | ||
|
|
||
| .EXAMPLE | ||
| Get-MtConditionalAccessPolicyPlan | ||
|
|
||
| Returns each plan and its rules without modifying the cached Graph objects. | ||
|
|
||
| .LINK | ||
| https://maester.dev/docs/commands/Get-MtConditionalAccessPolicyPlan | ||
| #> | ||
| [CmdletBinding()] | ||
| [OutputType([pscustomobject])] | ||
| param( | ||
| [switch] $MetadataOnly, | ||
| [switch] $DisableCache | ||
| ) | ||
|
|
||
| Write-Verbose -Message 'Reading Conditional Access policy plan metadata and rule inventories.' | ||
| $plans = @(Invoke-MtGraphRequest -RelativeUri 'identity/conditionalAccess/plans' -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop) | ||
| $inventory = [System.Collections.Generic.List[object]]::new() | ||
| foreach ($plan in $plans) { | ||
| if ([string]::IsNullOrWhiteSpace([string]$plan.id)) { throw 'Conditional Access plan inventory contains a plan without an ID.' } | ||
| $planId = [uri]::EscapeDataString([string]$plan.id) | ||
| $copy = $plan | ConvertTo-Json -Depth 100 | ConvertFrom-Json -AsHashtable | ||
| if (-not $MetadataOnly) { | ||
| $copy['rules'] = @(Invoke-MtGraphRequest -RelativeUri "identity/conditionalAccess/plans/$planId/rules" -ApiVersion beta -DisableCache:$DisableCache -ErrorAction Stop) | ||
| } | ||
| $inventory.Add([pscustomobject]$copy) | ||
| } | ||
| return $inventory.ToArray() | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.