feat(auth): add cached access scope rules for custom roles

Introduces a per-worker cache for access scope rules derived from custom roles and tenant group membership, keyed on a shared version stamp stored in Azure Table.

- Add Get-CippAccessScopeRule to cache the rule (allow/block lists) rather than resolved tenant ids, keeping correctness as tenants change
- Add Get-CippAccessScopeVersion to memo the shared stamp with a short TTL
- Add Clear-CippAccessScopeCache to bump the stamp and drop local memos; called from ExecCustomRole, ExecTenantGroup, Set-CIPPAccessRole, and Update-CIPPDynamicTenantGroups
- Add Expand-CippScopeTenantItem to resolve tenant group references in allowed/blocked lists
- Refactor Test-CIPPAccess to use the cache for TenantList and GroupList requests, avoiding a full tenant load on every warm request
- Extract Resolve-CippRoleTenantEntry and fix silent drop of unresolvable tenant ids in ListCustomRole, which previously caused a blocked tenant to render as unrestricted

Synced from CyberDrain/CIPP@aa01643

Author: github-actions[bot]

Modules/CIPPCore/Public/Authentication/Clear-CippAccessScopeCache.ps1

@@ -0,0 +1,49 @@
+function Clear-CippAccessScopeCache {
+    <#
+    .SYNOPSIS
+        Invalidate cached access scope rules across every worker.
+
+    .DESCRIPTION
+        Bumps the shared version stamp that Get-CippAccessScopeRule keys on, so every worker misses
+        and recomputes from source, and drops this worker's caches immediately.
+
+        Propagation is not instant on the other workers. They each memo the stamp for a short
+        window (see Get-CippAccessScopeVersion), so a change lands there within that window rather
+        than on the very next request. Verified behaviour, not an assumption.
+
+        Call this from anything that changes what a role is allowed to see: custom role
+        definitions, access role group mappings, and tenant group membership. Missing a call site
+        does not cause indefinite staleness - the rule cache TTL still expires entries - but it
+        does mean an operator can save a role change and not see it take effect straight away.
+
+        A failure is logged rather than thrown. Failing the role save the operator just made
+        because a cache table hiccuped would be the worse outcome, and the TTL bounds the damage.
+
+    .EXAMPLE
+        Clear-CippAccessScopeCache
+
+    .FUNCTIONALITY
+        Internal
+    #>
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param()
+
+    if (-not $PSCmdlet.ShouldProcess('access scope cache', 'Invalidate')) {
+        return
+    }
+
+    $script:CippAccessScopeRuleCache = @{}
+    $script:CippAccessScopeVersionMemo = $null
+
+    try {
+        $Table = Get-CIPPTable -tablename 'CacheVersions'
+        $Entity = @{
+            PartitionKey = 'CacheVersion'
+            RowKey       = 'AccessScope'
+            Version      = [string][guid]::NewGuid()
+        }
+        Add-CIPPAzDataTableEntity @Table -Entity $Entity -Force | Out-Null
+    } catch {
+        Write-LogMessage -API 'AccessScopeCache' -message "Failed to invalidate the access scope cache. Other workers will keep their current rules until the cache expires. $($_.Exception.Message)" -Sev 'Error'
+    }
+}

Modules/CIPPCore/Public/Authentication/Expand-CippScopeTenantItem.ps1

@@ -0,0 +1,46 @@
+function Expand-CippScopeTenantItem {
+    <#
+    .SYNOPSIS
+        Expand a role's tenant entries, resolving tenant groups to their member tenant ids.
+
+    .DESCRIPTION
+        Entries stored against a role are either literal tenant ids, the 'AllTenants' sentinel, or
+        a tenant group reference that has to be resolved to the ids currently in that group.
+
+        A group that cannot be expanded warns and contributes nothing, which is deliberate: the
+        alternative - treating an unresolvable group as 'everything' - would widen access on the
+        back of a lookup failure.
+
+        Used by Get-CippAccessScopeRule for both the allowed and blocked lists.
+
+    .PARAMETER Items
+        The stored AllowedTenants or BlockedTenants entries.
+
+    .PARAMETER Kind
+        'allowed' or 'blocked', used only to make the warning readable.
+
+    .EXAMPLE
+        Expand-CippScopeTenantItem -Items $Permission.BlockedTenants -Kind 'blocked'
+
+    .FUNCTIONALITY
+        Internal
+    #>
+    [CmdletBinding()]
+    param(
+        $Items,
+        [string]$Kind
+    )
+
+    foreach ($Item in $Items) {
+        if ($Item -is [PSCustomObject] -and $Item.type -eq 'Group') {
+            try {
+                $GroupMembers = Expand-CIPPTenantGroups -TenantFilter @($Item)
+                $GroupMembers | ForEach-Object { $_.addedFields.customerId }
+            } catch {
+                Write-Warning "Failed to expand $Kind tenant group '$($Item.label)': $($_.Exception.Message)"
+            }
+        } else {
+            $Item
+        }
+    }
+}

Modules/CIPPCore/Public/Authentication/Get-CippAccessScopeRule.ps1

@@ -0,0 +1,99 @@
+function Get-CippAccessScopeRule {
+    <#
+    .SYNOPSIS
+        The tenant and group scope rule a custom role expresses.
+
+    .DESCRIPTION
+        Returns the rule itself - allow everything, or an explicit allow list minus a block list -
+        rather than the set of tenant ids it currently resolves to.
+
+        That distinction is the whole point of the cache. Caching the resolved id list would bake
+        in a snapshot of the tenant table, so a tenant onboarded afterwards would silently stay
+        invisible to the role until the entry expired: the same silent-omission failure that made
+        the request scope leak so hard to spot. A rule depends only on the role definition and
+        tenant group membership, both covered by the version stamp, so it stays correct however
+        many tenants come and go. Callers expand it against the live tenant list at the point of
+        use, which is an in-memory set operation over data they already hold.
+
+        Cached per worker, keyed by the shared version stamp so a role change invalidates every
+        worker at once, with a TTL as a backstop in case an invalidation call site is missed.
+
+    .PARAMETER Role
+        Name of the custom role.
+
+    .EXAMPLE
+        $Rule = Get-CippAccessScopeRule -Role 'helpdesk'
+        if (-not $Rule.Unrestricted) { $Rule.BlockedTenants }
+
+    .FUNCTIONALITY
+        Internal
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Role
+    )
+
+    $TtlMinutes = 5
+    $Now = (Get-Date).ToUniversalTime()
+    $Version = Get-CippAccessScopeVersion
+    $CacheKey = '{0}|{1}' -f $Version, $Role
+
+    if (-not $script:CippAccessScopeRuleCache) {
+        $script:CippAccessScopeRuleCache = @{}
+    }
+
+    $Cached = $script:CippAccessScopeRuleCache[$CacheKey]
+    if ($Cached -and $Cached.Expires -gt $Now) {
+        return $Cached.Rule
+    }
+
+    # Throws when the role no longer exists, which callers already handle as 'this role
+    # contributes no scope'
+    $Permission = Get-CIPPRolePermissions -Role $Role
+
+    $Unrestricted = ((($Permission.AllowedTenants | Measure-Object).Count -eq 0 -or
+            $Permission.AllowedTenants -contains 'AllTenants') -and
+        ($Permission.BlockedTenants | Measure-Object).Count -eq 0)
+
+    $AllowAllTenants = $false
+    $AllowedTenants = @()
+    $BlockedTenants = @()
+    $AllowedGroups = @()
+
+    if (-not $Unrestricted) {
+        $Expanded = @(Expand-CippScopeTenantItem -Items $Permission.AllowedTenants -Kind 'allowed')
+
+        # 'AllTenants' alongside a block list means 'everything except', and the caller substitutes
+        # the live tenant list. Held as a flag rather than a resolved list precisely so that
+        # substitution happens at read time.
+        $AllowAllTenants = $Expanded -contains 'AllTenants'
+        $AllowedTenants = @($Expanded | Where-Object { $_ -ne 'AllTenants' })
+        $BlockedTenants = @(Expand-CippScopeTenantItem -Items $Permission.BlockedTenants -Kind 'blocked')
+        $AllowedGroups = @(
+            foreach ($Item in $Permission.AllowedTenants) {
+                if ($Item -is [PSCustomObject] -and $Item.type -eq 'Group') { $Item.value }
+            }
+        )
+    }
+
+    $Rule = [PSCustomObject]@{
+        Role            = $Role
+        Unrestricted    = $Unrestricted
+        AllowAllTenants = $AllowAllTenants
+        AllowedTenants  = $AllowedTenants
+        BlockedTenants  = $BlockedTenants
+        AllowedGroups   = $AllowedGroups
+    }
+
+    # Entries keyed on a superseded version are dead weight; drop the lot rather than track ages
+    if ($script:CippAccessScopeRuleCache.Count -gt 200) {
+        $script:CippAccessScopeRuleCache = @{}
+    }
+    $script:CippAccessScopeRuleCache[$CacheKey] = @{
+        Rule    = $Rule
+        Expires = $Now.AddMinutes($TtlMinutes)
+    }
+
+    return $Rule
+}

Modules/CIPPCore/Public/Authentication/Get-CippAccessScopeVersion.ps1

@@ -0,0 +1,57 @@
+function Get-CippAccessScopeVersion {
+    <#
+    .SYNOPSIS
+        Current version stamp for cached access scope rules.
+
+    .DESCRIPTION
+        Access scope rules are derived from CustomRoles, AccessRoleGroups and tenant group
+        membership, and are cached per worker. Those inputs are shared, and one worker has no way
+        to reach into another's memory, so invalidation goes through this stamp instead: every
+        worker keys its cache on the current value, and Clear-CippAccessScopeCache bumps it
+        whenever the underlying definitions change.
+
+        The stamp is itself memoised for a short window so a warm request costs no storage read at
+        all. That window is the upper bound on how long a role change takes to reach a worker that
+        is already warm.
+
+        A read failure returns a fresh value rather than the last known one. That forces a miss and
+        a recompute from source, so a storage blip costs latency instead of serving a scope that
+        may no longer be correct.
+
+    .EXAMPLE
+        Get-CippAccessScopeVersion
+
+    .FUNCTIONALITY
+        Internal
+    #>
+    [CmdletBinding()]
+    param()
+
+    # How long a worker trusts its copy of the stamp, and therefore the worst case delay before a
+    # role change reaches a worker that is already warm. The worker that made the change clears
+    # its own memo, so this only applies to the others. Kept short deliberately: the cost is one
+    # small table read per worker per window, which is nothing next to an operator changing a role
+    # and being unable to tell whether it took effect.
+    $MemoSeconds = 10
+    $Now = (Get-Date).ToUniversalTime()
+
+    if ($script:CippAccessScopeVersionMemo -and $script:CippAccessScopeVersionMemo.Expires -gt $Now) {
+        return $script:CippAccessScopeVersionMemo.Version
+    }
+
+    try {
+        $Table = Get-CIPPTable -tablename 'CacheVersions'
+        $Entity = Get-CIPPAzDataTableEntity @Table -Filter "PartitionKey eq 'CacheVersion' and RowKey eq 'AccessScope'"
+        $Version = if ($Entity.Version) { [string]$Entity.Version } else { 'initial' }
+    } catch {
+        Write-Warning "Could not read the access scope cache version, forcing a recompute. $($_.Exception.Message)"
+        return [string][guid]::NewGuid()
+    }
+
+    $script:CippAccessScopeVersionMemo = @{
+        Version = $Version
+        Expires = $Now.AddSeconds($MemoSeconds)
+    }
+
+    return $Version
+}

Modules/CIPPCore/Public/Authentication/Set-CIPPAccessRole.ps1

@@ -47,5 +47,9 @@ function Set-CIPPAccessRole {
 
     if ($PSCmdlet.ShouldProcess("Setting access role $Role for group $($Group.displayName)")) {
         Add-CIPPAzDataTableEntity -Table $Table -Entity $AccessGroup -Force
+
+        # Group to role mapping decides which roles a user resolves to, so the cached scope rules
+        # have to be invalidated with it
+        Clear-CippAccessScopeCache
     }
 }

Modules/CIPPCore/Public/Authentication/Test-CIPPAccess.ps1

@@ -331,6 +331,55 @@ function Test-CIPPAccess {
         if (@('admin', 'superadmin') -contains $BaseRole.Name) {
             return $true
         } else {
+            # Scope-only requests resolve from the cached rules. On a warm cache this needs no
+            # storage read at all, and it only needs the tenant table when a rule actually says
+            # 'all tenants except', because that is the one case where the answer depends on
+            # which tenants currently exist.
+            if ($TenantList.IsPresent -or $GroupList.IsPresent) {
+                $swScopeRules = [System.Diagnostics.Stopwatch]::StartNew()
+                $ScopeRules = foreach ($CustomRole in $CustomRoles) {
+                    try {
+                        Get-CippAccessScopeRule -Role $CustomRole
+                    } catch {
+                        Write-Information $_.Exception.Message
+                    }
+                }
+                $swScopeRules.Stop()
+                $AccessTimings['GetScopeRules'] = $swScopeRules.Elapsed.TotalMilliseconds
+
+                if (($ScopeRules | Measure-Object).Count -eq 0) {
+                    # No role produced a scope, so the caller is entitled to nothing
+                    return @()
+                }
+
+                if ($TenantList.IsPresent) {
+                    $swTenantList = [System.Diagnostics.Stopwatch]::StartNew()
+                    $NeedsTenantList = @($ScopeRules | Where-Object { -not $_.Unrestricted -and $_.AllowAllTenants }).Count -gt 0
+                    $Tenants = if ($NeedsTenantList) { Get-Tenants -IncludeErrors } else { @() }
+
+                    $LimitedTenantList = foreach ($Rule in $ScopeRules) {
+                        if ($Rule.Unrestricted) {
+                            @('AllTenants')
+                        } else {
+                            $AllowedForRule = if ($Rule.AllowAllTenants) { $Tenants.customerId } else { $Rule.AllowedTenants }
+                            $AllowedForRule | Where-Object { $Rule.BlockedTenants -notcontains $_ }
+                        }
+                    }
+                    $swTenantList.Stop()
+                    $AccessTimings['BuildTenantList'] = $swTenantList.Elapsed.TotalMilliseconds
+                    return @($LimitedTenantList | Sort-Object -Unique)
+                }
+
+                Write-Information "Getting allowed groups for roles: $($CustomRoles -join ', ')"
+                $swGroupList = [System.Diagnostics.Stopwatch]::StartNew()
+                $LimitedGroupList = foreach ($Rule in $ScopeRules) {
+                    if ($Rule.Unrestricted) { @('AllGroups') } else { $Rule.AllowedGroups }
+                }
+                $swGroupList.Stop()
+                $AccessTimings['BuildGroupList'] = $swGroupList.Elapsed.TotalMilliseconds
+                return @($LimitedGroupList | Sort-Object -Unique)
+            }
+
             $swTenantsLoad = [System.Diagnostics.Stopwatch]::StartNew()
             $Tenants = Get-Tenants -IncludeErrors
             $swTenantsLoad.Stop()
@@ -349,69 +398,8 @@ function Test-CIPPAccess {
             $AccessTimings['GetRolePermissions'] = $swRolePerms.Elapsed.TotalMilliseconds
 
             if ($PermissionsFound) {
-                if ($TenantList.IsPresent) {
-                    $swTenantList = [System.Diagnostics.Stopwatch]::StartNew()
-                    $LimitedTenantList = foreach ($Permission in $PermissionSet) {
-                        if ((($Permission.AllowedTenants | Measure-Object).Count -eq 0 -or $Permission.AllowedTenants -contains 'AllTenants') -and (($Permission.BlockedTenants | Measure-Object).Count -eq 0)) {
-                            @('AllTenants')
-                        } else {
-                            # Expand tenant groups to individual tenant IDs
-                            $ExpandedAllowedTenants = foreach ($AllowedItem in $Permission.AllowedTenants) {
-                                if ($AllowedItem -is [PSCustomObject] -and $AllowedItem.type -eq 'Group') {
-                                    try {
-                                        $GroupMembers = Expand-CIPPTenantGroups -TenantFilter @($AllowedItem)
-                                        $GroupMembers | ForEach-Object { $_.addedFields.customerId }
-                                    } catch {
-                                        Write-Warning "Failed to expand tenant group '$($AllowedItem.label)': $($_.Exception.Message)"
-                                        @()
-                                    }
-                                } else {
-                                    $AllowedItem
-                                }
-                            }
-
-                            $ExpandedBlockedTenants = foreach ($BlockedItem in $Permission.BlockedTenants) {
-                                if ($BlockedItem -is [PSCustomObject] -and $BlockedItem.type -eq 'Group') {
-                                    try {
-                                        $GroupMembers = Expand-CIPPTenantGroups -TenantFilter @($BlockedItem)
-                                        $GroupMembers | ForEach-Object { $_.addedFields.customerId }
-                                    } catch {
-                                        Write-Warning "Failed to expand blocked tenant group '$($BlockedItem.label)': $($_.Exception.Message)"
-                                        @()
-                                    }
-                                } else {
-                                    $BlockedItem
-                                }
-                            }
-
-                            if ($ExpandedAllowedTenants -contains 'AllTenants') {
-                                $ExpandedAllowedTenants = $Tenants.customerId
-                            }
-                            $ExpandedAllowedTenants | Where-Object { $ExpandedBlockedTenants -notcontains $_ }
-                        }
-                    }
-                    $swTenantList.Stop()
-                    $AccessTimings['BuildTenantList'] = $swTenantList.Elapsed.TotalMilliseconds
-                    return @($LimitedTenantList | Sort-Object -Unique)
-                } elseif ($GroupList.IsPresent) {
-                    $swGroupList = [System.Diagnostics.Stopwatch]::StartNew()
-                    Write-Information "Getting allowed groups for roles: $($CustomRoles -join ', ')"
-                    $LimitedGroupList = foreach ($Permission in $PermissionSet) {
-                        if ((($Permission.AllowedTenants | Measure-Object).Count -eq 0 -or $Permission.AllowedTenants -contains 'AllTenants') -and (($Permission.BlockedTenants | Measure-Object).Count -eq 0)) {
-                            @('AllGroups')
-                        } else {
-                            foreach ($AllowedItem in $Permission.AllowedTenants) {
-                                if ($AllowedItem -is [PSCustomObject] -and $AllowedItem.type -eq 'Group') {
-                                    $AllowedItem.value
-                                }
-                            }
-                        }
-                    }
-                    $swGroupList.Stop()
-                    $AccessTimings['BuildGroupList'] = $swGroupList.Elapsed.TotalMilliseconds
-                    return @($LimitedGroupList | Sort-Object -Unique)
-                }
-
+                # Tenant list and group list requests have already returned above, from the
+                # cached scope rules. Everything from here is the per-endpoint access decision.
                 $TenantAllowed = $false
                 $APIAllowed = $false
                 $swPermissionEval = [System.Diagnostics.Stopwatch]::StartNew()