Public/AdminRole/Get-GraphAdminRole.ps1
# Module: Orbit # Function: UserAdmin # Author: David Eberhardt # Updated: 28-May 2023 # Status: Beta function Get-GraphAdminRole { <# .SYNOPSIS Queries Admin Roles assigned to an Object .DESCRIPTION Queries Azure Active Directory Admin Roles assigned to an Object Requires a Connection to Graph .PARAMETER Identity Required. One or more UserPrincipalNames of the Office365 Administrator .PARAMETER Type Optional. Switches query to All (Default), Eligible or Active Admin Roles .PARAMETER QueryGroupsOnly Optional. Switches query to Active (Default) or Eligible Admin Roles Limits the query to Active Directory Groups only. .EXAMPLE Get-GraphAdminRole [-Identity] user@domain.com [-Type Active] Returns all active Admin Roles for the provided Identity .EXAMPLE Get-GraphAdminRole [-Identity] user@domain.com -Type Eligible Returns all eligible Admin Roles for the provided Identity .INPUTS System.String .OUTPUTS System.Object .NOTES Returns an Object containing all Admin Roles assigned to a User. This is intended as an informational for the User currently connected to a specific PS session (whoami and whatcanido) The Output can be used as baseline for other functions (-contains "Teams Service Admin") .COMPONENT UserManagement .FUNCTIONALITY Queries active or eligible Privileged Identity roles for Administration of Teams .LINK https://github.com/DEberhardt/Orbit/tree/main/docs/Orbit.Authentication/Get-GraphAdminRole.md .LINK https://github.com/DEberhardt/Orbit/tree/main/docs/about/about_UserManagement.md .LINK https://github.com/DEberhardt/Orbit/tree/main/docs/ #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName, HelpMessage = 'Enter the identity of the User to Query')] [Alias('UserPrincipalName', 'Id', 'ObjectId')] [string]$Identity, [Parameter(HelpMessage = 'Filters the output by Type: All, Eligibe or Active only')] [ValidateSet('All', 'Active', 'Eligible')] #[ValidateSet('All', 'Active', 'Eligible','Group')] [string]$Type = 'All', [Parameter(HelpMessage = 'Queries Active Group memberships only. Fast, but limited to direct assignments')] [switch]$QueryGroupsOnly ) #param begin { Show-OrbitFunctionStatus -Level Beta Write-Verbose -Message "[BEGIN ] $($MyInvocation.MyCommand)" # Asserting Graph Connection if ( -not $script:TFPSSA) { $script:TFPSSA = Assert-GraphConnection; if ( -not $script:TFPSSA ) { break } } # Setting Preference Variables according to Upstream settings if (-not $PSBoundParameters.ContainsKey('Verbose')) { $VerbosePreference = $PSCmdlet.SessionState.PSVariable.GetValue('VerbosePreference') } if (-not $PSBoundParameters.ContainsKey('Confirm')) { $ConfirmPreference = $PSCmdlet.SessionState.PSVariable.GetValue('ConfirmPreference') } if (-not $PSBoundParameters.ContainsKey('WhatIf')) { $WhatIfPreference = $PSCmdlet.SessionState.PSVariable.GetValue('WhatIfPreference') } if (-not $PSBoundParameters.ContainsKey('Debug')) { $DebugPreference = $PSCmdlet.SessionState.PSVariable.GetValue('DebugPreference') } else { $DebugPreference = 'Continue' } if ( $PSBoundParameters.ContainsKey('InformationAction')) { $InformationPreference = $PSCmdlet.SessionState.PSVariable.GetValue('InformationAction') } else { $InformationPreference = 'Continue' } #Loading Modules $CurrentOperationID0 = 'Loading modules' Write-BetterProgress -Id 0 -Activity $ActivityID0 -Status $StatusID0 -CurrentOperation $CurrentOperationID0 -Step ($private:CountID0++) -Of $private:StepsID0 $GraphGovernanceModule = Get-InstalledModule Microsoft.Graph.Identity.Governance if ( -not $GraphGovernanceModule ) { Import-Module Microsoft.Graph.Identity.Governance -Force -Global -Verbose:$false } } #begin process { Write-Verbose -Message "[PROCESS] $($MyInvocation.MyCommand)" foreach ($Id in $Identity) { try { $GraphUser = Get-GraphUser -ObjectId "$Id" -WarningAction SilentlyContinue -ErrorAction Stop } catch { [string]$Message = $_ | Get-ErrorMessageFromErrorString Write-Warning -Message "User '$Id': GetUser$($Message.Split(':')[1])" } if ( $GraphPreviewModule -and -not $QueryGroupsOnly ) { #Querying privileged Admin Roles Assignments $SubjectId = $GraphUser.Id $MyAdminRoles = Get-GraphMSPrivilegedRoleAssignment -ProviderId $ProviderId -ResourceId $ResourceId -Filter "subjectId eq '$SubjectId'" $Scope = 'Privileged' } if ($QueryGroupsOnly) { # Querying active roles only with Group Membership $MyMemberships = Get-GraphUserMembership -ObjectId $GraphUser.ObjectId #-All $true #IMPROVE Test Performance and reliability without "all!" $MyAdminRoles = $MyMemberships | Where-Object ObjectType -EQ Role $Scope = 'Group' } if ($PSBoundParameters.ContainsKey('Debug') -or $DebugPreference -eq 'Continue') { "Function: $($MyInvocation.MyCommand.Name) - MyAdminRoles ($Scope)", ( $MyAdminRoles | Format-List | Out-String).Trim() | Write-Debug } [System.Collections.Generic.List[object]]$MyRoles = @() foreach ($R in $MyAdminRoles) { $Role = @() switch ($Scope) { 'Privileged' { # Querying Display Name $RoleObject = $AllRoles | Where-Object { $_.Id -eq $R.RoleDefinitionId } $Role = [PsCustomObject][ordered]@{ PSTypeName = 'PowerShell.TeamsFunctsions.GraphAdminRole.RoleActivationAssignment' 'User' = $GraphUser.UserPrincipalName 'Rolename' = $RoleObject.DisplayName 'Type' = $R.MemberType 'ActiveSince' = $R.StartDateTime 'ActiveUntil' = $R.EndDateTime 'AssignmentState' = $R.AssignmentState 'RoleDefinitionId' = $R.RoleDefinitionId } } 'Group' { $Role = [PsCustomObject][ordered]@{ PSTypeName = 'PowerShell.TeamsFunctsions.GraphAdminRole.RoleActivationAssignment' 'User' = $GraphUser.UserPrincipalName 'Rolename' = $R.DisplayName 'Type' = 'Direct' # This may be different once we incorporate Groups too! 'ActiveSince' = '' 'ActiveUntil' = '' 'AssignmentState' = 'Active' 'RoleDefinitionId' = $R.RoleTemplateId } # Overriding Type as Group only has active entries $Type = 'All' } } [void]$MyRoles.Add($Role) } # Output switch ($Type) { 'Active' { Write-Output $MyRoles | Where-Object AssignmentState -EQ 'Active' } 'Eligible' { Write-Output $MyRoles | Where-Object AssignmentState -EQ 'Eligible' } 'All' { Write-Output $MyRoles } } } } #process end { Write-Verbose -Message "[END ] $($MyInvocation.MyCommand)" } #end } #Get-GraphAdminRole |