Add a domain user or group to local administrators with PowerShell

• Author
• Recent Posts

Sitaram Pamarthi

Sitaram Pamarthi is working as a Windows Engineer and his special fields of interest are PowerShell, Active Directory, Exchange, and virtualization.

Latest posts by Sitaram Pamarthi (see all)

• Add a domain user or group to local administrators with PowerShell - Wed, Mar 19 2014
• Create a list of local administrators with PowerShell - Wed, Mar 5 2014
• Remotely query user profile information with PowerShell - Tue, Nov 26 2013

In my previous article, I showed you how to generate local admin group membership details and save the data in a CSV file for use in Excel. In this article, I will explain how to add a domain user or group to the local administrators group using PowerShell.

Input

I tried to make this script as simple as possible for day-to-day use. This script takes three parameters:

• ObjectType: Type of object that you want to add to the local administrators group. ObjectType should be either User or Group.
• ObjectName: Name of the domain object that you want to add. ObjectName should be in the format DOMAINNAME\UserName or DOMAINNAME\GroupName.
• ComputerName: List of computer names on which you want to perform the operation. When no computer account is specified, the script tries to execute the action against the local computer from which you are running the script.

Execution

The script relies on the [ADSI] WinNT provider to query the computer’s local administrators object. Once the object is queried, the script uses a method called Add() to add the given domain user or group to the local administrators group. The argument for this method is the ADSPath of the object we are trying to add. The script uses the domain name extracted from ObjectName to form this ADSPath. For a list of allowed ADSPath formats, refer to this MSDN link. Below is the code snippet that performs the addition operation:

$GroupObj = [ADSI]"WinNT://$Computer/Administrators"
$GroupObj.Add("WinNT://$ObjDomain/$ObjName")

Output

The script shows its progress as it executes, as well as how many computers it completed, so it is easy for you to know its current stage of execution. The script also provides a good verbose output when the -Verbose parameter is used. The status of additions made to the local administrators group is saved in a CSV file named ResultsofLocalGroupAddition.CSV in the c:\temp folder. You can modify the value of the $ResultsFile variable if you want to choose a different location or file name for the output file.

The output contains three columns: ComputerName, Status, and Comments. Status indicates the result of the addition (“failed” or “successful”). If the computer is offline, the status will be set to “offline.” The Comments column shows the reason for failures. These are .NET exceptions, but they are clear enough to understand the reason for the failure.

Sample output

PowerShell script

<#
    .Synopsis 
        Adds a user or group to local administrator group

    .Description
        This scripts adds the given user or group to local administrators group on given list of servers.

    .Parameter ComputerName
        Computer Name(s) on which you want to add user/group to local administrators

	.Parameter ObjectType
		This parameter takes either of two values, User or Group. This parameter indicates the type of object
		you want to add to local administrators

	.Parameter ObjectName
		Name of the object (user or group) which you want to add to local administrators group. This should be in 
		Domain\UserName or Domain\GroupName format

    .Example
        Set-LocalAdminGroupMembers.ps1 -ObjectType User -ObjectName "AD\TestUser1" -ComputerName srvmem1, srvmem2 

        Adds AD\TestUser1 user account to local administrators group on srvmem1 and srvmeme2

    .Example
        Set-LocalAdminGroupMembers.ps1 -ObjectType Group -ObjectName "ADDomain\AllUsers" -ComputerName (Get-Content c:\servers.txt) 

		Adds AD\TestUser1 Group to local administrators group on servers listed in c:\servers.txt
    .Notes
		Author : Sitaram Pamarthi
		WebSite: http://techibee.com

#>
[CmdletBinding()]
Param(
	[Parameter(Mandatory=$true,Position=1)]
	[ValidateSet("User","Group")]
	[String]
	$ObjectType,

	[Parameter(Mandatory=$true,Position=2)]
	[ValidateScript({($_.split("\").count -eq 2)})]
	[string]$ObjectName,

	[Parameter(Position=3)]
	[String[]]$ComputerName=$env:COMPUTERNAME
)

#Name and location of the output file. Change this line if you want to alter the location
$ResultsFile = "c:\temp\ResultsofLocalGroupAddition.csv"
$ObjDomain = $ObjectName.Split("\")[0]
$ObjName = $ObjectName.Split("\")[1]
$ComputerCount = $ComputerName.Count
$count = 0
Add-Content -Path $ResultsFile -Value "ComputerName,Status,Comments"
foreach($Computer in $ComputerName) {
	$count++
	$Status=$null
	$Comment = $null
	Write-Host ("{0}. Working on {1}" -f $Count, $Computer)
	if(Test-Connection -ComputerName $Computer -Count 1 -Quiet) {
		Write-Verbose "$Computer : Online"
		try {
			$GroupObj = [ADSI]"WinNT://$Computer/Administrators"
			$GroupObj.Add("WinNT://$ObjDomain/$ObjName")
			$Status = "Success"
			$Comment = "Added $ObjectName $ObjectType to Local administrators group"
			Write-Verbose "Successfully added $ObjectName $ObjectType to $Computer"
		} catch {
			$Status = "Failed"
			$Comment = $_.toString().replace("`n","").replace("`r","")
			Write-Verbose "Failed to add $ObjectName $ObjectType to $Computer"
		}

		Add-Content -Path $ResultsFile -Value ("{0},{1},{2}" -f $Computer,$Status,$Comment )	

	} else {
		Write-Warning "$Computer : Offline"
		Add-Content -Path $ResultsFile -Value ("{0},{1}" -f $Computer,"Offline")
	}

}

Usage instructions

This script is simple to use. You can get examples by running the following command:

PS C:\> get-help C:\Scripts\Set-LocalAdminGroupMembers.ps1 -Examples

Example 1

PS C:\> Set-LocalAdminGroupMembers.ps1 -ObjectType User -ObjectName "AD\TestUser1" -ComputerName srvmem1, srvmem2

Adds the AD\TestUser1 user account to the local administrators group on srvmem1 and srvmeme2.

Example 2

PS C:\> Set-LocalAdminGroupMembers.ps1 -ObjectType Group -ObjectName "ADDomain\AllUsers" -ComputerName (Get-Content c:\servers.txt)

Adds the AD\TestUser1 group to the local administrators group on servers listed in c:\servers.txt.

I hope this helps. Comments and suggestions are welcome.