public/Get-MsecEntraAppAssignment.ps1
|
function Get-MsecEntraAppAssignment { <# .SYNOPSIS Who is assigned to an enterprise application - the portal's "Users and groups" blade - one row per assignment. .DESCRIPTION This is the access-review question: which people and which groups can use this app, and in which role. It is NOT the consent question. Get-MsecEntraAppConsent reads the same Graph collection and deliberately keeps only ServicePrincipal principals, because those are application permissions granted TO software. This command keeps the other side - User and Group - which is who may USE the app. A GROUP IS REPORTED AS A GROUP, NOT EXPANDED. The portal shows the group; so does this. A row saying a group is assigned does not tell you how many people that is, and treating the row count as a headcount will undercount badly - four of these apps carry four group assignments each. Expand with Get-MsecEntraGroupMember when the review needs names. A PRINCIPAL CAN HOLD SEVERAL ROLES, AND EACH IS ITS OWN ROW. Counting rows counts assignments, not people. Measured on four live apps: 37 rows, of which 21 were user assignments - held between just 6 distinct people. Reporting that as 21 users overstates the review by more than three times. Group by PrincipalId for a headcount. THE UPN IS NOT IN THE ASSIGNMENT AND COSTS A CALL PER USER. appRoleAssignedTo carries principalDisplayName and principalId only, so UserPrincipalName and UserEnabled come from a second Graph read per DISTINCT user, cached within the call. Display names are not unique and say nothing about whether the account still works, which is most of what an access review is for - measured on four live apps, 21 users across 37 assignments. UserEnabled IS THE COLUMN THAT FINDS THE STALE ONES. An assignment survives the user being disabled; nothing cleans it up. A PATTERN THAT MATCHES NOTHING WARNS. An app that was renamed, or a wildcard that misses, would otherwise return an empty result identical to an app with no assignments - and on a monthly review that reads as "nobody has access" rather than "we did not look". Named apps are easy to miss: a prefix search for four similarly named apps in a live tenant turned up a FIFTH carrying an extra suffix, which an obvious wildcard would exclude. .PARAMETER DisplayName Enterprise application display names. Wildcards are supported and matching is case-insensitive, which matters - display names in a live tenant were inconsistently cased ('CONTOSO-PROD-API' beside 'contoso-prod-web'). A wildcard pattern is matched client-side, so the service principals are enumerated first. Graph cannot filter on an arbitrary pattern. .PARAMETER AppId Application (client) ids, as an alternative to -DisplayName. Exact match, no wildcards. .EXAMPLE Connect-Msec -KeyVaultName kv-msec Get-MsecEntraAppAssignment -DisplayName 'contoso-prod-*' | Format-Table Application, PrincipalType, PrincipalDisplayName, Role, UserEnabled The monthly access review, as the portal would show it. .EXAMPLE # Assignments left behind by people whose accounts are disabled. Get-MsecEntraAppAssignment -DisplayName 'contoso-prod-*' | Where-Object { $_.UserEnabled -eq $false } .EXAMPLE # People, not assignments - a principal holding three roles is one person. Get-MsecEntraAppAssignment -DisplayName 'contoso-prod-*' | Group-Object PrincipalId | Measure-Object | Select-Object -ExpandProperty Count .OUTPUTS One PSCustomObject per assignment, PSTypeName 'MsecEntraAppAssignment'. .NOTES Needs Connect-Msec and the 'Application.Read.All' application permission to read the service principals and their assignments, plus a directory read ('User.Read.All' or 'Directory.Read.All') for UserPrincipalName and UserEnabled. Verified against a live tenant on the permissions the msec app already holds. 'Unreadable' in UserPrincipalName means the user lookup FAILED, not that the user has no UPN. A warning names how many, and UserEnabled is $null for those rows - a failed read must never render as a clean one. #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [Parameter()] [string[]] $DisplayName, [Parameter()] [string[]] $AppId ) Assert-MsecSession # A runtime check rather than [Parameter(Mandatory)]: a mandatory parameter PROMPTS a # non-interactive caller and hangs it, and reporting pipelines consume this module. An # unfiltered call would also enumerate every assignment in the tenant, which is not a # default anyone wants by accident. if (-not $DisplayName -and -not $AppId) { throw 'Specify -DisplayName (wildcards allowed) or -AppId. Without one, this would enumerate every enterprise application in the tenant.' } $zeroGuid = '00000000-0000-0000-0000-000000000000' # Two phases on purpose. Listing every service principal WITH its appRoles pulls the role # definitions of the whole tenant to match a handful of names; the roles are fetched per # matched app instead. Write-Verbose 'Enumerating service principals' $all = @(Invoke-MsecGraphRequest -All -Path ('/v1.0/servicePrincipals?' + [uri]::EscapeDataString('$select') + '=id,displayName,appId&' + [uri]::EscapeDataString('$top') + '=999')) $matched = [System.Collections.Generic.List[object]]::new() foreach ($pattern in @($DisplayName)) { if (-not $pattern) { continue } $hits = @($all | Where-Object { [string] $_.displayName -like $pattern }) if ($hits.Count -eq 0) { # See the help: an empty result here is indistinguishable from an app with nobody # assigned, and on a review that is the dangerous direction to be wrong in. Write-Warning "No enterprise application matched -DisplayName '$pattern'. No assignments are reported for it - that is NOT the same as the app having none." continue } foreach ($h in $hits) { $matched.Add($h) } } foreach ($id in @($AppId)) { if (-not $id) { continue } $hits = @($all | Where-Object { [string] $_.appId -eq $id }) if ($hits.Count -eq 0) { Write-Warning "No enterprise application matched -AppId '$id'. No assignments are reported for it - that is NOT the same as the app having none." continue } foreach ($h in $hits) { $matched.Add($h) } } # The same app can arrive from both parameters, or from two overlapping patterns. $apps = @($matched | Sort-Object { [string] $_.id } -Unique) Write-Verbose "Matched $($apps.Count) enterprise application(s)" # Cache per call: the same person is usually assigned to several of the apps being reviewed. $userCache = @{} $unreadableUsers = 0 foreach ($app in $apps) { $appName = [string] $app.displayName # appRoles live on the service principal, and the assignment carries only the id. $roleName = @{} try { $detail = Invoke-MsecGraphRequest -Path ("/v1.0/servicePrincipals/$($app.id)?" + [uri]::EscapeDataString('$select') + '=appRoles') foreach ($r in @($detail.appRoles)) { $roleName[[string] $r.id] = [string] $r.displayName } } catch { Write-Warning "Could not read the app roles of '$appName', so Role is reported as null on its assignments. Graph said: $($_.Exception.Message)" } $assignments = $null try { $assignments = @(Invoke-MsecGraphRequest -All -Path "/v1.0/servicePrincipals/$($app.id)/appRoleAssignedTo?`$top=999") } catch { Write-Warning "Could not read assignments on '$appName'. Its access is MISSING from this output, which is not the same as the app having no assignments. Graph said: $($_.Exception.Message)" [PSCustomObject]@{ PSTypeName = 'MsecEntraAppAssignment' Application = $appName AppId = [string] $app.appId ServicePrincipalId = [string] $app.id PrincipalDisplayName = 'Unreadable' PrincipalType = $null PrincipalId = $null UserPrincipalName = $null UserEnabled = $null Role = $null AppRoleId = $null CreatedDateTime = $null AssignmentId = $null } continue } foreach ($a in $assignments) { $type = [string] $a.principalType # ServicePrincipal assignments are application permissions granted to software, a # different question entirely - Get-MsecEntraAppConsent answers that one. if ($type -ne 'User' -and $type -ne 'Group') { continue } $upn = $null $enabled = $null if ($type -eq 'User') { $pid = [string] $a.principalId if (-not $userCache.ContainsKey($pid)) { try { $u = Invoke-MsecGraphRequest -Path ("/v1.0/users/$pid`?" + [uri]::EscapeDataString('$select') + '=userPrincipalName,accountEnabled') $userCache[$pid] = [PSCustomObject]@{ Upn = [string] $u.userPrincipalName Enabled = [bool] $u.accountEnabled } } catch { # 'Unreadable' rather than $null: $null is what a Group legitimately has # here, and a failed read must not borrow that meaning. $userCache[$pid] = [PSCustomObject]@{ Upn = 'Unreadable'; Enabled = $null } $unreadableUsers++ } } $upn = $userCache[$pid].Upn $enabled = $userCache[$pid].Enabled } $roleId = [string] $a.appRoleId $role = if ($roleId -eq $zeroGuid) { 'Default Access' } elseif ($roleName.ContainsKey($roleId)) { $roleName[$roleId] } else { $null } # the app no longer publishes the role this assignment names [PSCustomObject]@{ PSTypeName = 'MsecEntraAppAssignment' Application = $appName AppId = [string] $app.appId ServicePrincipalId = [string] $app.id PrincipalDisplayName = [string] $a.principalDisplayName PrincipalType = $type PrincipalId = [string] $a.principalId UserPrincipalName = $upn UserEnabled = $enabled Role = $role AppRoleId = $roleId CreatedDateTime = $a.createdDateTime AssignmentId = [string] $a.id } } } if ($unreadableUsers -gt 0) { Write-Warning "$unreadableUsers user(s) could not be read; their UserPrincipalName is 'Unreadable' and UserEnabled is null. Needs 'User.Read.All' or 'Directory.Read.All'." } } |