functions/Get-PpacRbacRoleAssignment.ps1
|
<#
.SYNOPSIS Search tenant RBAC role assignments through the Power Platform API. .DESCRIPTION Searches tenant role assignments through the Power Platform API. Only supplied filters are sent and matching assignments are returned. .PARAMETER Scope The scope to search, such as a tenant or environment scope path. .PARAMETER ServicePrincipalId The object id of the principal to filter the search by. .PARAMETER PrincipalType The principal type to filter by, such as user or application. .PARAMETER Permission The permission name to filter the search results by. .PARAMETER IncludeParentScopes Includes assignments from parent scopes in the search results. .PARAMETER IncludeNestedScopes Includes assignments from nested scopes in the search results. .PARAMETER ExpandEnvironmentGroups Expands environment group memberships in the search results. .PARAMETER ExpandEnvironmentClusters Expands environment cluster memberships in the search results. .PARAMETER ExpandSecurityGroups Expands security group memberships in the search results. .PARAMETER IncludeVirtualEntraRoleAssignments Includes virtual Entra role assignments in the search results. .PARAMETER ContinuationToken The continuation token for the next page of search results. .PARAMETER AsExcelOutput Instructs the cmdlet to output the results as an Excel file. .EXAMPLE PS C:\> Get-PpacRbacRoleAssignment -Scope "/tenants/00000000-0000-0000-0000-000000000000" Searches assignments within the tenant scope. It uses -Scope to select the search scope. .EXAMPLE PS C:\> Get-PpacRbacRoleAssignment -Scope "/tenants/00000000-0000-0000-0000-000000000000" -ServicePrincipalId "11111111-1111-1111-1111-111111111111" -PrincipalType "ApplicationUser" -Permission "Read" Searches assignments for a principal with a permission filter. It uses -Scope to select the search scope. It uses -ServicePrincipalId to select the principal. It uses -PrincipalType to select the principal type. It uses -Permission to select the permission filter. .EXAMPLE PS C:\> Get-PpacRbacRoleAssignment -Scope "/tenants/00000000-0000-0000-0000-000000000000" -IncludeParentScopes -IncludeNestedScopes -AsExcelOutput Exports assignments including parent and nested scopes. It uses -Scope to select the search scope. It uses -IncludeParentScopes to include parent scopes. It uses -IncludeNestedScopes to include nested scopes. It uses -AsExcelOutput to write an Excel file. .EXAMPLE PS C:\> Get-PpacRbacRoleAssignment -Scope "/tenants/00000000-0000-0000-0000-000000000000" -ExpandEnvironmentGroups -ExpandEnvironmentClusters -ExpandSecurityGroups -IncludeVirtualEntraRoleAssignments -ContinuationToken "abc" Searches assignments with expanded memberships and paging. It uses -Scope to select the search scope. It uses -ExpandEnvironmentGroups to expand group memberships. It uses -ExpandEnvironmentClusters to expand cluster memberships. It uses -ExpandSecurityGroups to expand security memberships. It uses -IncludeVirtualEntraRoleAssignments to include virtual assignments. It uses -ContinuationToken to continue a paged search. .NOTES Author: d365bap.tools contributors .LINK https://learn.microsoft.com/en-us/power-platform/admin/programmability-tutorial-rbac-role-assignment .LINK https://learn.microsoft.com/en-us/power-platform/admin/programmability-authentication-v2 #> function Get-PpacRbacRoleAssignment { [CmdletBinding()] [OutputType('D365Bap.Tools.PpacRbacRoleAssignment[]', [object[]])] param ( [Parameter(Mandatory = $true)] [ValidateNotNullOrEmpty()] [string] $Scope, [ValidateNotNullOrEmpty()] [string] $ServicePrincipalId, [ValidateNotNullOrEmpty()] [string] $PrincipalType, [ValidateNotNullOrEmpty()] [string] $Permission, [switch] $IncludeParentScopes, [switch] $IncludeNestedScopes, [switch] $ExpandEnvironmentGroups, [switch] $ExpandEnvironmentClusters, [switch] $ExpandSecurityGroups, [switch] $IncludeVirtualEntraRoleAssignments, [ValidateNotNullOrEmpty()] [string] $ContinuationToken, [switch] $AsExcelOutput ) process { $objSecureToken = Get-BapAccessToken -PowerPlatform $tokenValue = ConvertFrom-SecureString -AsPlainText ` -SecureString $objSecureToken $hashHeaders = @{ Authorization = "Bearer $tokenValue" 'Content-Type' = 'application/json' } $apiVersion = $script:BapApiVersions.PowerPlatform $uri = 'https://api.powerplatform.com/authorization/roleAssignments/search?api-version={0}' ` -f $apiVersion $hashBody = [ordered]@{ scope = $Scope } if ($PSBoundParameters.ContainsKey('ServicePrincipalId')) { $hashBody['principalObjectId'] = $ServicePrincipalId } if ($PSBoundParameters.ContainsKey('PrincipalType')) { $hashBody['principalType'] = $PrincipalType } if ($PSBoundParameters.ContainsKey('Permission')) { $hashBody['permission'] = $Permission } if ($IncludeParentScopes) { $hashBody['includeParentScopes'] = $true } if ($IncludeNestedScopes) { $hashBody['includeNestedScopes'] = $true } if ($ExpandEnvironmentGroups) { $hashBody['expandEnvironmentGroups'] = $true } if ($ExpandEnvironmentClusters) { $hashBody['expandEnvironmentClusters'] = $true } if ($ExpandSecurityGroups) { $hashBody['expandSecurityGroups'] = $true } if ($IncludeVirtualEntraRoleAssignments) { $hashBody['includeVirtualEntraRoleAssignments'] = $true } if ($PSBoundParameters.ContainsKey('ContinuationToken')) { $hashBody['continuationToken'] = $ContinuationToken } $jsonBody = $hashBody | ConvertTo-Json -Depth 20 try { $result = Invoke-RestMethod -Method Post ` -Uri $uri ` -Headers $hashHeaders ` -Body $jsonBody ` -ContentType 'application/json' ` -ErrorAction Stop } catch { $messageString = "Failed to search tenant role assignments in scope <c='em'>$Scope</c>. $($_.Exception.Message)" Write-PSFMessage -Level Important ` -Message $messageString ` -Exception $_.Exception Stop-PSFFunction -Message "Stopping because the role assignment search request failed." ` -Exception $_.Exception return } $colRes = @( $result.value | Select-PSFObject -TypeName 'D365Bap.Tools.PpacRbacRoleAssignment' ` -Property ` 'principalObjectId as ServicePrincipalId', 'roleDefinitionId as RoleId', 'principalType as PrincipalType', 'scope as Scope', 'id as RoleAssignmentId' ) if ($AsExcelOutput) { $colRes | Export-Excel -WorksheetName 'Get-PpacRbacRoleAssignment' ` -WarningAction SilentlyContinue return } $colRes } } |