functions/Get-PpacEnvironmentRbacRoleMember.ps1
|
<#
.SYNOPSIS List environment RBAC assignments. .DESCRIPTION Retrieves scoped assignments through the Power Platform API with name resolution. .PARAMETER EnvironmentId Target environment identifier. .PARAMETER ServicePrincipalId Member object id filter. Wildcards are accepted. Default: * .PARAMETER Role Assignment definition name, id, or wildcard filter. Default: * .PARAMETER AsExcelOutput Exports the results to an Excel workbook. .EXAMPLE PS C:\> Get-PpacEnvironmentRbacRoleMember -EnvironmentId "00000000-0000-0000-0000-000000000000" Lists assignments in the environment. It uses -EnvironmentId to select the environment. .EXAMPLE PS C:\> Get-PpacEnvironmentRbacRoleMember -EnvironmentId "00000000-0000-0000-0000-000000000000" -Role "*admin*" Lists assignments that match the filter. It uses -EnvironmentId to select the environment. It uses -Role "*admin*" to filter by definition name or id. .EXAMPLE PS C:\> Get-PpacEnvironmentRbacRoleMember -EnvironmentId "00000000-0000-0000-0000-000000000000" -AsExcelOutput Exports assignments to an Excel workbook. It uses -EnvironmentId to select the environment. It uses -AsExcelOutput to write an Excel file. .NOTES Author: d365bap.tools contributors .LINK https://learn.microsoft.com/en-us/power-platform/admin/programmability-tutorial-rbac-role-assignment?tabs=PowerShell .LINK https://learn.microsoft.com/en-us/power-platform/admin/programmability-authentication-v2?tabs=powershell%2Cpowershell-interactive%2Cpowershell-confidential #> function Get-PpacEnvironmentRbacRoleMember { [CmdletBinding()] [OutputType('D365Bap.Tools.PpacRbacRoleAssignment[]')] param ( [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true)] [Alias('PpacEnvId')] [ValidateNotNullOrEmpty()] [string] $EnvironmentId, [SupportsWildcards()] [string] $ServicePrincipalId = '*', [SupportsWildcards()] [string] $Role = '*', [switch] $AsExcelOutput ) process { $objSecureToken = Get-BapAccessToken -PowerPlatform $tokenValue = ConvertFrom-SecureString -AsPlainText ` -SecureString $objSecureToken $hashHeaders = @{ 'Content-Type' = 'application/json' } $hashHeaders.Add('Authorization', "Bearer $tokenValue") $colDefinitions = @(Get-BapRbacRoleCatalog) if ($colDefinitions.Count -eq 0) { $apiVersionDefinitions = $script:BapApiVersions.AuthorizationPreview $uriDefinitions = 'https://api.powerplatform.com/authorization/roleDefinitions?api-version={0}' ` -f $apiVersionDefinitions try { $colDefinitions = @(Invoke-RestMethod -Method Get ` -Uri $uriDefinitions ` -Headers $hashHeaders ` -ErrorAction Stop | Select-Object -ExpandProperty value) } catch { $messageString = "Failed to retrieve role definitions for environment <c='em'>$EnvironmentId</c>. $($_.Exception.Message)" Write-PSFMessage -Level Important ` -Message $messageString ` -Exception $_.Exception Stop-PSFFunction -Message 'Stopping because the role definition request failed.' ` -Exception $_.Exception return } } $colMatched = @( $colDefinitions | Where-Object { ($_.roleDefinitionName -like $Role) ` -or ($_.roleDefinitionId -like $Role) } ) if ($colMatched.Count -eq 0) { $messageString = "The specified role: <c='em'>$Role</c> was not found. Please provide a valid role name. Try running the command <c='em'>Get-PpacRbacRole</c> to see the list of valid role names." Write-PSFMessage -Level Important ` -Message $messageString Stop-PSFFunction -Message 'Stopping because of invalid role name.' ` -Exception $([System.Exception]::new($($messageString -replace '<[^>]+>', ''))) return } $colRoleIds = @($colMatched | Select-Object -ExpandProperty roleDefinitionId) $hashRoleNames = @{} foreach ($itemDefinition in $colMatched) { $hashRoleNames[$itemDefinition.roleDefinitionId] = $itemDefinition.roleDefinitionName } $apiVersion = $script:BapApiVersions.PowerPlatform $uri = 'https://api.powerplatform.com/authorization/environments/{0}/roleAssignments?api-version={1}' ` -f $EnvironmentId, $apiVersion try { $colRaw = @(Invoke-RestMethod -Method Get ` -Uri $uri ` -Headers $hashHeaders ` -ErrorAction Stop | Select-Object -ExpandProperty value) } catch { $messageString = "Failed to retrieve role assignments for environment <c='em'>$EnvironmentId</c>. $($_.Exception.Message)" Write-PSFMessage -Level Important ` -Message $messageString ` -Exception $_.Exception Stop-PSFFunction -Message 'Stopping because the role assignment request failed.' ` -Exception $_.Exception return } $colFiltered = @( $colRaw | Where-Object { ($_.principalObjectId -like $ServicePrincipalId) ` -and ($_.roleDefinitionId -in $colRoleIds) } ) $colRes = @( $colFiltered | Select-PSFObject -TypeName 'D365Bap.Tools.PpacRbacRoleAssignment' ` -Property ` 'principalObjectId as ServicePrincipalId', 'roleDefinitionId as RoleId', @{ Name = 'Role'; Expression = { $hashRoleNames[$_.roleDefinitionId] } }, 'principalType as PrincipalType', 'roleAssignmentId as RoleAssignmentId', 'scope as Scope' ) if ($AsExcelOutput) { $colRes | Export-Excel -WorksheetName 'Get-PpacEnvironmentRbacRoleMember' ` -WarningAction SilentlyContinue return } $colRes } } |