Private/Test/Test-IsLocalAdmin.ps1
|
function Test-IsLocalAdmin { <# .SYNOPSIS Tests if the current user is running as a local administrator. .DESCRIPTION Checks if the current PowerShell session is running with local administrator privileges by examining the Windows Identity and checking for membership in the built-in Administrators group. This function is useful for scripts that require elevated permissions to perform administrative tasks such as modifying system settings, installing software, or accessing restricted resources. .INPUTS None. This function does not accept pipeline input. .OUTPUTS System.Boolean Returns $true if the current user is running as a local administrator. Returns $false if the user does not have administrator privileges. .EXAMPLE Test-IsLocalAdmin Returns $true if running as administrator, $false otherwise. .EXAMPLE if (-not (Test-IsLocalAdmin)) { throw "This script requires administrator privileges. Please run as administrator." } Throws an error if the script is not running with administrator privileges. .EXAMPLE if (Test-IsLocalAdmin) { Write-Host "Running with administrator privileges" # Perform administrative tasks } else { Write-Warning "Some features require administrator privileges" # Run limited functionality } Conditionally executes code based on administrator status. .EXAMPLE Test-IsLocalAdmin -Verbose Tests administrator status and displays verbose output showing the detection method. .NOTES This function checks for local administrator privileges on Windows systems. It uses the Windows Identity class to determine the current user's security context and checks membership in the built-in Administrators role. On non-Windows systems or if the check fails, the function returns $false with a warning. .LINK https://learn.microsoft.com/en-us/dotnet/api/system.security.principal.windowsidentity .LINK https://learn.microsoft.com/en-us/dotnet/api/system.security.principal.windowsprincipal #> [CmdletBinding()] [OutputType([bool])] param ( ) #requires -Version 5.1 try { # Get the current Windows Identity $identity = [Security.Principal.WindowsIdentity]::GetCurrent() $principal = [Security.Principal.WindowsPrincipal]$identity # Check if the user is in the Administrator role $isAdmin = $principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator) Write-Verbose "Administrator status: $isAdmin" return $isAdmin } catch { Write-Warning "Unable to determine administrator status. Assuming non-elevated. Error: $_" return $false } } |