Managing Active Directory OUs with PowerShell

powershell-hero-img
In a previous article, I demonstrated how to use the Active Directory PowerShell module to create new organizational units in Active Directory. Even with careful planning, there might be a time when you need to modify an OU. As such, there might be situations where you want a scripted solution, so let’s see what we can do. As before, we’ll be using the Active Directory module in a domain with an account that has domain admin privileges.

Setting OU Properties

If you read the previous article, it probably isn’t too difficult to figure out what cmdlet you can use to set OU properties.

Set-ADOrganizationalUnit Help (Image Credit: Jeff Hicks)
Set-ADOrganizationalUnit Help (Image Credit: Jeff Hicks)

Sometimes, the trickiest part of this command is getting the OU that you want to modify. For example, in my domain I have an engineering OU, and I want to change the description. I might try this:

Set-ADOrganizationalUnit Engineering -description "Engineering division user accounts"

But this will fail.

Set OU failure (Image Credit: Jeff Hicks)
Set OU failure (Image Credit: Jeff Hicks)

I need to provide a complete identity, which means I need to know the OU’s distinguished name.

Set-ADOrganizationalUnit "OU=Engineering,OU=Departments,OU=Employees,DC=Globomantics,DC=Local" -Description "Engineering division user accounts"

This assumes that I know the full path, which I may not. Usually, I find it easier to use Get-ADOrganizationalUnit, which will let me find the OU on a partial name and pipe that to Set-ADOrganizationalUnit.

Get-ADOrganizationalUnit -filter "Name -eq 'Engineering'" | Set-ADOrganizationalUnit -description "Engineering division user accounts" -PassThru –whatif

I almost always use –Whatif first, just in case there is more than one OU that matches the filter. If I am satisfied, I can re-run the command without –WhatIf. I should also point out that –Passthru only writes the basic OU object to the pipeline. I may not see the changes I just made, such as modifying the description. One way to handle that is to get it, set it and get it again.

Get-ADOrganizationalUnit -Filter "Name -eq 'servers'" |
Set-ADOrganizationalUnit -Description "Company servers" -DisplayName "Globomantics Servers" -PassThru |
Get-ADOrganizationalUnit -Properties Description,DisplayName
An OU modification one-liner (Image Credit: Jeff Hicks)
An OU modification one-liner (Image Credit: Jeff Hicks)

This type of approach can also be used to modify multiple OUs. For example, in my domain I have a number of OUs based on departments all located under the Employees OU. I can quickly configure all of them with the same location information.

Get-ADOrganizationalUnit -filter * -SearchBase "OU=Departments,OU=Employees,DC=Globomantics,DC=Local" |
Set-ADOrganizationalUnit -City Chicago -State IL -Country US

Renaming OUs

Another task you might face is renaming an OU. Normally I never feel that Active Directory OU names need to align with any business unit names. How the business is managed and organized can be distinct from Active Directory, but sometimes work is dictated to us. I have an OU called Customer Service, which is should be self-explanatory. But let’s imagine a scenario where the company is re-organizing once again and now this groups is called Client Relations. There’s no technical needed to change the OU name, but we’ll keep the boss happy.
In this situation, we can’t simply assign new name properties. We’ll need to use a different cmdlet Rename-ADObject. As before, I find it easier to get the object and then pipe it to the command to do something.

Get-ADOrganizationalUnit -filter "Name -eq 'Customer Service'" -SearchBase "OU=Departments,OU=Employees,DC=Globomantics,DC=Local" |
Rename-ADObject -NewName "Client Relations" –whatif
WhatIf Renaming an OU (Image Credit: Jeff Hicks)
WhatIf Renaming an OU (Image Credit: Jeff Hicks)

There is a Get-ADObject cmdlet, but this works just as well. I’ll now go ahead and re-run without –Whatif.

Renaming an OU (Image Credit: Jeff Hicks)
Renaming an OU (Image Credit: Jeff Hicks)

Hopefully this is sufficient to keep the boss happy, but it may not take other properties into account.

Get-ADOrganizationalUnit -filter "Name -like 'client*'" -Properties Description,Displayname
Viewing the renamed OU (Image Credit: Jeff Hicks)
Viewing the renamed OU (Image Credit: Jeff Hicks)

Looks I should change the description to keep everyone happy.

Get-ADOrganizationalUnit -filter "Name -like 'client*'" |
Set-ADOrganizationalUnit -Description "Client Relations account reps" -DisplayName "Client Relations" -PassThru |
Get-ADOrganizationalUnit -Properties Description,DisplayName

This appears to get the job done.

Making final adjustments (Image Credit: Jeff Hicks)
Making final adjustments (Image Credit: Jeff Hicks)

ManagedBy

The last setting I want to quickly show you is how to configure the ManagedBy setting. Right now, my Domain Controllers OU doesn’t have this configured.

Nothing configured for ManagedBy (Image Credit: Jeff Hicks)
Nothing configured for ManagedBy (Image Credit: Jeff Hicks)

To change that, all I need to do is specify the SamAccountName of an Active Directory User or Group.

Set-ADOrganizationalUnit "OU=Domain Controllers,DC=Globomantics,DC=Local" -ManagedBy "Domain Admins" –PassThru

PowerShell figures out the rest.

The new ManagedBy setting (Image Credit: Jeff Hicks)
The new ManagedBy setting (Image Credit: Jeff Hicks)

If you want to remove the value use a parameter value of $Null.

Set-ADOrganizationalUnit "OU=Domain Controllers,DC=Globomantics,DC=Local" -ManagedBy $null –PassThru

It is just as easy to modify this setting for multiple OUs. In my domain, I want to make myself the manager of all of the HQ organizational units.

Get-ADOrganizationalUnit -filter "Name -like '*HQ'" |
Set-ADOrganizationalUnit -ManagedBy "jeff" -PassThru |
Select Name,ManagedBy
Modifying multiple OUs (Image Credit: Jeff Hicks)
Modifying multiple OUs (Image Credit: Jeff Hicks)

To avoid mistakes you might want to use Get-ADUser or Get-ADGroup first to make sure you have the correct account.

$j = get-aduser jfrost

Then you can use this object to make the change.

Get-ADOrganizationalUnit -filter "name -eq 'Testing'" | Set-ADOrganizationalUnit -ManagedBy $j -PassThru
Using an AD User object (Image Credit: Jeff Hicks)
Using an AD User object (Image Credit: Jeff Hicks)


And I think that’s about all I want to inundate you with for now. Next time we’ll look at moving and deleting organizational units.

Related Article: