Managing Domain Memberships with PowerShell

Deployment Examples, PDQ Deploy

Let’s go through some steps that may prove helpful in speeding up your processes in joining machines to a domain, or helping you to migrate machines to a new domain at scale. We will utilize some pretty simple PowerShell to accomplish this task. So without further ado, grab a drink, sit back, and let’s do this!

Checking Domain Membership

We need some logic to see if the machine is currently a member of a domain. That’s pretty simple with PowerShell. The code looks like this (and will return a true/false value):

(Get-WMIObject win32_computersystem).partofdomain

Removing a Machine from a Domain

This also is going to return to us a true/false value. Given that we want to put the machine on a new domain, let’s use some logic to automate removing the machine from its current domain membership.

If ( (Get-WMIObject win32_computersystem).partofdomain "eq $true ){
    Remove-Computer
}

Pretty simple right? The machine is now off the domain! However, you may need to restart the computer for the changes to apply. You can add a -restart parameter to your script if desired. Keep in mind that this will only tell the local computer to switch to using a workgroup. It doesn’t clean anything up in Active Directory. It will only disable the associated computer object in Active Directory.

Some additional parameters to consider:

-UnjoinDomainCredential

This is for specifying a user account that has permission to remove computers from their current domain. This is a required parameter if you’re trying to use Remove-Computer with a remote computer.

-LocalCredential

This parameter is for specifying a user account with permission to connect to the computer

Putting a Machine on a New Domain

The question then becomes “Well, how do I put it on the new domain?” I’m so glad you asked! Let’s look at that:
A couple of prerequisites are needed. To add a computer to the domain, we must supply credentials to the command that have been delegated rights to add machines to the domain. There are a few ways to do this, and I will provide the simplest method in this post, though I would recommend reading Kris’ excellent post on using more secure credentials here. Let’s go ahead and get our account setup in PowerShell.

$User = "DOMAIN\DelegatedUser"
$Password = ConvertTo-SecureString "somepassword" "AsPlainText "Force
$Credentials = New-Object System.Management.Automation.PSCredential $user,$password

Now we can pass that set of credentials to the next cmdlet we need to utilize:

Add-Computer "Domainname "YourDomainName" -Credential $Credentials

Restart Options

The computer will need a reboot after the task is complete. You have some options here. You can use a Restart-Computer cmdlet in your script right after Add-Computer, or if deploying your script with PDQ Deploy you can add a Reboot Step to your deployment package. The Reboot step is my preferred method, as that will let PDQ Deploy control deployment state, and return a successful result when the computer checks back in after the reboot is complete. Otherwise, if you choose to add Restart-Computer cmdlet directly into your script, you have no way of receiving any feedback from the script being run. It will simply timeout (though the target machine will be rebooted).

A simple way to put this together would be to make a PowerShell function that joins the machine to the domain. This makes it easy.

Let’s put that all together so you have a clear picture of what the complete script would look like:

$User = "DOMAIN\DelegatedUser"
$Password = ConvertTo-SecureString "somepassword" "AsPlainText "Force
$Credentials = New-Object System.Management.Automation.PSCredential $User,$Password

Function Join-Domain {
    Add-Computer "Domainname "" -Credential $Credentials
}

If ( (Get-WMIObject win32_computersystem).partofdomain "eq $true ) {
    Remove-Computer
    Join-Domain
} Else {
    Join-Domain
}

Deploying Your PowerShell Script

One option for deploying your script is to use PDQ Deploy. Save this script as a ps1 file somewhere on your network, such as your PDQ Repository.

  1. Create a new package, give it a name, and add a PowerShell step to the package.Powershell Step Window.
  2. Give the step a title, and then select Insert PowerShell Script at the bottom of the command window on the details tab.Powershell Step Insert Script managing domain memberships
  3. Browse to and select your PowerShell script you created from the code above. Set your conditions and options as you see fit for your environment.
  4. Deploy to your target machines with a Local Administrator account. (We don’t want any hiccups once the machine is off the domain.)Change Deploy Credentials


2 Comments

  • Minor typo, Get-WMIObject in the beginning of the article is correct but in the other 2 instances, the dash is in the wrong spot. Also the script failed on me until I moved the function before the if/else statement. Other than that I’m still new to powershell and I enjoy reading these posts.

Leave a Reply

Your email address will not be published. Required fields are marked *