Public/Get-GraphPermission.ps1
|
function Get-GraphPermission { <# .SYNOPSIS Looks up the official definition of a Microsoft Graph permission: what it is, its GUID, whether it is delegated or application, and whether admin consent is required. .DESCRIPTION Get-GraphMapping -Permission answers "which operations use this permission". Get-GraphPermission answers a different question: "what is this permission" -- its official display name, description, GUID, delegated/application type and admin-consent requirement, as published on the Microsoft Graph service principal itself (MSGraphServicePrincipalPermissions.json). A permission name such as "User.Read.All" is defined twice in the official source: once as a delegated permission (oauth2PermissionScope) and once as an application permission (appRole), each with its own GUID and description. Get-GraphPermission returns one record per definition instead of merging them. The related-operation count reuses the exact same reverse index Get-GraphMapping -Permission already loads (data/graph-command-permissions-lite.json); it is not recomputed or duplicated here. Pass -IncludeOperations to also list the matching cmdlets and endpoints instead of only their count. .PARAMETER Name A Microsoft Graph permission name, for example "User.Read.All". Accepts the MatchedPermission property from Get-GraphMapping -Permission over the pipeline. .PARAMETER Type Restrict the result to 'Delegated' or 'Application' when the permission is defined as both. .PARAMETER IncludeOperations Also return the distinct Cmdlets and Endpoints that use this permission, not just the Operations count. .EXAMPLE Get-GraphPermission -Name "User.Read.All" Returns two records: the Application definition and the Delegated definition, each with its own GUID, description and admin-consent requirement. .EXAMPLE Get-GraphPermission -Name "User.Read.All" -Type Application Returns only the application (app role) definition. .EXAMPLE Get-GraphMapping -Permission "User.Read.All" | Select-Object -First 1 -ExpandProperty MatchedPermission | Get-GraphPermission .OUTPUTS GraphShell.Permission #> [CmdletBinding()] [OutputType('GraphShell.Permission')] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)] [Alias('Permission', 'MatchedPermission')] [ValidateNotNullOrEmpty()] [string]$Name, [Parameter(ValueFromPipelineByPropertyName)] [ValidateSet('Delegated', 'Application')] [string]$Type, [switch]$IncludeOperations ) process { $catalogIndex = Get-GraphPermissionCatalogIndex if (-not $catalogIndex) { Write-Warning "GraphShell permission catalog data is not available in this installation. Run scripts/sync-graph-permission-catalog.ps1, or update GraphShell to a version that includes it." return } $definitions = $null if (-not $catalogIndex.ByName.TryGetValue($Name, [ref]$definitions)) { Write-Warning "GraphShell found no official definition for permission '$Name'. Check the name, or try Get-GraphMapping -Permission to see if any operation references it." return } $filtered = if ($Type) { @($definitions | Where-Object Type -eq $Type) } else { @($definitions) } if ($filtered.Count -eq 0) { Write-Warning "GraphShell has a '$Name' definition, but none of type '$Type'." return } $operationRecords = $null $permissionLiteIndex = Get-GraphPermissionLiteIndex $permissionLiteIndex.ByName.TryGetValue($Name, [ref]$operationRecords) | Out-Null $operationCount = if ($operationRecords) { $operationRecords.Count } else { 0 } $cmdlets = $null $endpoints = $null if ($IncludeOperations -and $operationRecords) { $cmdlets = @($operationRecords | Select-Object -ExpandProperty command -Unique) $endpoints = @($operationRecords | Select-Object -ExpandProperty uri -Unique) } foreach ($definition in $filtered) { [pscustomobject]@{ PSTypeName = 'GraphShell.Permission' Name = $Name Type = $definition.Type Id = $definition.Id DisplayName = $definition.DisplayName Description = $definition.Description AdminConsentRequired = $definition.AdminConsentRequired IsEnabled = $definition.IsEnabled Operations = $operationCount Cmdlets = $cmdlets Endpoints = $endpoints } } } } |