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
    }
}