Moving users or computers in AD with the Move-ADObject cmdlet

According to the official documentation, Move-ADObject “Moves an Active Directory object or a container of objects to a different container or domain”. The straightforward noun-verb structure of PS also suggest what you can do with it. Let’s review the syntax:

Move-ADObject
    [-WhatIf]
    [-Confirm]
    [-AuthType <ADAuthType>]
    [-Credential <PSCredential>]
    [-Identity] <ADObject>
    [-Partition <String>]
    [-PassThru]
    [-Server <String>]
    [-TargetPath] <String>
    [-TargetServer <String>]
    [<CommonParameters>]

Both -Identity and -TargetPath are obligatory parameters. Regarding -Identity, we can use a distinguished name or a GUID as values. -TargetPath, on the other hand, “must be the path to a container or organizational unit”. So, in order to use Move-ADObject we must:

• Be able to identify the AD object we need to move. For users or computers, we can search for the DistinguishedName property of a user:

#For users:
PS> C:WindowsSystem32> (Get-ADUser -Identity “john.lennon” -Properties *).DistinguishedName
CN=John Lennon, OU=Rock,DC=andreypicado,DC=com
#For computers:
PS> C:WindowsSystem32>  (Get-ADComputer -Identity “Desktop001”).DistinguishedName
CN= Desktop001, OU=RockComputers,DC=andreypicado,DC=com

• Know the path where we want to move the user to. As an example we can use  “OU=Artists,DC=andreypicado,DC=com”

So, if we want to move the user John Lennon from his current OU to Artists, we can run:

Move-ADObject -Identity “CN=John Lennon, OU=Rock,DC=andreypicado,DC=com” -TargetPath “OU=Artists,DC=andreypicado,DC=com”

To successfully run this command we need to have permission to do it in the domain.

A practical use: check if one or more computers are part of an OU and if not, add them

For this example, our computer names will be placed inside an array. Of course, a CSV or XML could also be used. We will check if the computer belongs to Toronto_Computers. If that’s not the case, we will use Move-ADObject to move the computers to Toronto_Computers.

First we have to declare our variables.

$computerName = @("Desktop001","Laptop002","Workstation010")
$targetOU = "OU=Toronto_Computers,DC=andreypicado,DC=com"

Then, a for can help us to iterate through the $computerNames array. Inside of this for we will place the logic to determine whether the computer is part of the target OU. To add a computer if its not part of the target OU, we’re going to use Move-ADObject and an simple try and catch to handle errors:

for($i=0; $i -le ($computerNames.Count-1); $i++)
{
    $currentComputerName = $computerName[$i]
    if((Get-ADComputer -Identity $computerName[$i]).DistinguishedName -notlike "CN=$currentComputerName,$targetOU" )
    {  
        $currentComputerOU = (Get-ADComputer -Identity $computerNames[$i]).DistinguishedName
        Write-Host "The computer $currentComputerName is part of $currentComputerOU"
        try
        {
            Write-Host "Adding $currentComputerName to $targetOU ...."
            Move-ADObject -Identity $currentComputerOU -TargetPath $targetOU
            Write-Host "$currentComputerName ADDED TO $targetOU ...."
        }
        catch
        {
            Write-Host "Unexpected error"
        }
    }
    else
    {
        Write-Host "Bingo, this computer is part of the target OU"
    }
}

With this simple script you can check and move objects in AD very easily. Keep in mind that our source can also be a .csv or .xml file (check for Import-Csv and Import-Clixml cmdlets). In this example we searched for computers but is almost the same thing for users as it was showed at the start of this post. Also, the try and catch can be modified to catch commons errors to make the script easier to troubleshoot