Test Active Directory User Accounts with PowerShell

It is probably no surprise that Active Directory is something that IT pros love to automate with PowerShell. Certainly, creating 100 new user accounts from a CSV file with PowerShell is pretty simple. Part of that process may be testing for an existing user account, which I’ll show you how to do in this article.

The easy approach is to run Get-ADUser and if there is an error because the user isn’t found, it is okay to proceed.

Another test you might want to run is to test a specific property. You might want to know whether or not it’s defined, or perhaps you need to test if it is a certain value. It isn’t too difficult to get the user account and property.

Given these needs, I decided to write a Test-ADUser function, which I am happy to share with you.

The function requires the ActiveDirectory module. If it isn’t running when you load the function, PowerShell will automatically load it. I’ve written the function using many of the same parameters as Get-ADUser because when it comes time to getting the user account, I can splat the $PSBoundParameters value to Get-ADUser, after first removing the parameters that don’t belong.

If you look at the param section, you’ll see that I am using parameter sets. The default parameter set tests if the user account exists or not. You can also specify a single user property, and perform one out of three tasks:

  • Test if it exists, meaning something is defined.
  • Test if it doesn’t exist, meaning it is empty or null
  • Test if the value is equal to something you specify.

Each of these scenarios is a separate parameter set. Notice that the property parameter belongs to multiple sets. I actually didn’t specify any parameter set for identity because that is part of all the sets. I suppose I could have explicitly stated that fact, however.

I’m using a try-catch statement when attempting to get the user account. You can have multiple catch statements to handle different types of errors. If Get-ADUser can’t find the user account that is an exception, that’s a good thing in this case. If that exception happens, then I know I can write $False to the pipeline. That’s why I have a catch block designated to handle not found exceptions. Any other types of errors, such invalid credentials, bad server name, or bad property name, will be handled by the other catch block. If something like that happens, then the function can’t test anything so the function displays a warning and bails out.

Assuming the user is found, the function finally uses a switch statement and does a different comparison depending on the parameter set name. Because switch by default attempts to process all possibilities, I could have included a break statement within each condition.

But my switch statement is so simple that any performance gains would be insignificant.

Once the function is loaded into my PowerShell session, I can easily test if users exist or if key properties meet certain criteria.

I also wrote the function to accept pipelined input although this probably only works with a small set so you can correlate the results.

If the user can’t be found, then the function doesn’t try to test properties.

As I was developing the function, I thought about how someone might use it, which is a key step to consider when building a PowerShell script or tool. Since the function only writes Boolean values to the pipeline, I thought maybe there might be other use cases. So I experimented with adding a –Passthru parameter to write the user account to the pipeline. But how do you handle something that isn’t found is exactly what this function is all about. I didn’t like the results so I pulled it.

I hope you’ll let me know what you think.

Related Topics:

  • PowerShell

    Don't have a login but want to join the conversation? Sign up for a Petri Account