BlackCat

1.0.0

Public/Discovery/Get-EntraIDPermissions.ps1

function Get-EntraIDPermissions {
    param (
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'ObjectId')]
        [string]$ObjectId,

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $false, ParameterSetName = 'Name')]
        [string]$Name,

        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $false, ParameterSetName = 'UserPrincipalName')]
        [ValidatePattern('^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$', ErrorMessage = "The value '{1}' is not a valid UPN format")]
        [string]$UserPrincipalName,

        [Parameter(Mandatory = $false)]
        [switch]$ShowActions,

        [Parameter(ParameterSetName = 'ObjectId')]
        [Parameter(ParameterSetName = 'Name')]
        [Parameter(ParameterSetName = 'UserPrincipalName')]
        [switch]$Group
    )

    begin {
        Write-Verbose "Starting function $($MyInvocation.MyCommand.Name)"
        $MyInvocation.MyCommand.Name | Invoke-BlackCat -ResourceTypeName 'MSGraph'

        $permissionsOverview = [System.Collections.Concurrent.ConcurrentBag[object]]::new()
    }

    process {
        try {
            # Construct query based on parameter set
            switch ($PSCmdlet.ParameterSetName) {
                'ObjectId' {
                    if ($Group) {
                        $response = Get-EntraInformation -ObjectId $ObjectId -Group
                    }
                    else {
                        $response = Get-EntraInformation -ObjectId $ObjectId
                    }
                }
                'Name' {
                    if ($Group) {
                        $response = Get-EntraInformation -Name $Name -Group
                    }
                    else {
                        $response = Get-EntraInformation -Name $Name
                    }
                }
                'UserPrincipalName' {
                    if ($Group) {
                        Write-Message -FunctionName $($MyInvocation.MyCommand.Name) -Message "The -Group parameter cannot be used with -UserPrincipalName. parameter." -Severity 'Error'
                    }
                    $response = Get-EntraInformation -UserPrincipalName $UserPrincipalName
                }
            }

            if (-not $response) {
                Write-Error "$($PSCmdlet.ParameterSetName) not found."
                return
            }

            $roleDetails = Invoke-MsGraph -relativeUrl 'roleManagement/directory/roleDefinitions' -ErrorVariable Err

            $response.Roles | ForEach-Object -parallel {
                $roleName = $_
                $roleDetails = $using:roleDetails

                $roleDetail = $roleDetails | Where-Object { $_.displayName -eq $roleName }

                if ($roleDetail) {
                    $currentItem = [PSCustomObject]@{
                        RoleName     = $roleDetail.displayName
                        Description  = $roleDetail.description
                        Actions      = $roleDetail.rolePermissions.allowedResourceActions
                        IsPrivileged = $roleDetail.isPrivileged
                    }
                    ($using:permissionsOverview).Add($currentItem)
                }
            }

            if ($permissionsOverview.Count -eq 0) {
                Write-Error "No permissions found for the user."
                return
            }

            if ($ShowActions) {
                Write-Message -FunctionName $($MyInvocation.MyCommand.Name) -Message "Actions this user can perform:"
                return $permissionsOverview.Actions | Sort-Object -Unique
            } else {
                return $permissionsOverview
            }
        }
        catch {
            Write-Message -FunctionName $($MyInvocation.MyCommand.Name) -Message $($_.Exception.Message) -Severity 'Error'
        }
    }
<#
.SYNOPSIS
    Retrieves permissions for a user or group in Microsoft Entra ID.
 
.DESCRIPTION
Retrieves and lists all permissions a user or group has in Microsoft Entra ID. This function queries the Microsoft Graph API for Entra ID roles, group memberships, and their associated permissions. Provides a comprehensive view of a principal's effective permissions and role assignments in Entra ID.
.PARAMETER ObjectId
    The unique Object ID of the user or group in Entra ID.
 
.PARAMETER Name
    The display name of the user or group in Entra ID.
 
.PARAMETER UserPrincipalName
    The User Principal Name (UPN) of the user in the format username@domain.com.
 
.PARAMETER ShowActions
    When specified, returns only the list of actions the user can perform instead of full role details.
 
.PARAMETER Group
    Indicates that the query should target a group rather than a user. Cannot be used with UserPrincipalName.
 
.EXAMPLE
    Get-EntraIDPermissions -UserPrincipalName "john.doe@contoso.com"
 
    Retrieves all role permissions for the specified user.
 
.EXAMPLE
    Get-EntraIDPermissions -ObjectId "12345678-1234-1234-1234-123456789012" -Group
 
    Retrieves all role permissions for the specified group.
 
.EXAMPLE
    Get-EntraIDPermissions -Name "IT Administrators" -Group -ShowActions
 
    Returns only the actions that members of the "IT Administrators" group can perform.
 
.OUTPUTS
    System.Management.Automation.PSCustomObject[]
    Returns collection of custom objects with role details including RoleName, Description, Actions, and IsPrivileged.
    When -ShowActions is specified, returns a string array of unique actions.
 
.NOTES
    Requires appropriate Microsoft Graph API permissions to query user/group roles and permissions.
    The function filters out read permissions by default when showing actions.
 
.LINK
    MITRE ATT&CK Tactic: TA0007 - Discovery
    https://attack.mitre.org/tactics/TA0007/
 
.LINK
    MITRE ATT&CK Technique: T1069.003 - Permission Groups Discovery: Cloud Groups
    https://attack.mitre.org/techniques/T1069/003/
#>
}