Retrieving Active Directory and Microsoft Lync Server 2010 User Accounts

[NextHop_Team]

First published on TECHNET on Jun 06, 2010

After you get Microsoft Communications Server up and running, you probably won’t find yourself having to manage several hundred sets of Address Book server configurations or thousands of conferencing policies. Consequently, the fact that the cmdlets used to manage these objects don’t offer a lot of ways to filter the returned information (beyond simple wildcards) probably isn’t that big of a deal.

Note . And if it is a problem you can always pipe the returned data to Where-Object and thus apply some very complex and sophisticated filters to the information.

This is definitely not the case when it comes to users, however. Depending on the size of your organization you might have hundreds of users enabled for Microsoft Communications Server; heck, you might have tens of thousands of users enabled for Microsoft Communications Server. Furthermore, you will undoubtedly want to “slice and dice” these user accounts in a myriad of ways: you might want to retrieve a collection of users who have offices in a certain location, users who work for a specified department, users who have a designated job title, etc. Needless to say, simple wildcards won’t do the trick here.

But that’s OK. As it turns out, the two cmdlets used to return user account information – Get-CsAdUser and Get-CsUser –include several ways to slice and dice user information. For example, the two cmdlets each have a parameter ( -OU ) that limits retrieved data to user accounts found in a specific Active Directory organizational unit, including any child OUs in that organizational unit. These two cmdlets also feature a pair of filter parameters:

• -Filter , which enables you to filter user accounts based on Microsoft Communications Server-specific attributes, such as voice policy or dial plan.

• -LdapFilter , which enables you to filter user accounts based on “generic” Active Directory attributes, attributes such as department and job title.

In this article we’ll explain these parameters. We’ll also take a moment to talk about the –Identity parameter for user account cmdlets.

Incidentally, why two cmdlets for retrieving user account information? Well, Get-CsUser returns information only for users who have been enabled for Microsoft Communications Server; if you don’t have any users who have been enabled for Microsoft Communications Server then Get-CsUser won’t return any data whatsoever. By contrast, Get-CsAdUser returns account information for all your users, whether they have been enabled for Microsoft Communications Server or not.

User Identities

To begin with, you don’t have to retrieve user accounts in bulk; instead, you can always use the –Identity parameter to zero in on a specific user. As you might expect, the Identity for a user differs from the Identity used for a policy or configuration. As such, you can retrieve a specific user account by using any of the following:

• The user’s Active Directory display name (for example, Pilar Ackerman ).

• The user’s Universal Principal Name (UPN). The UPN will look something like this: pilar@fabrikam.com .

• The user’s SIP address; for example, sip:pilar@fabrikam.com .

• The user’s domain name and logon name. For example: fabrikampilar .

Or, to put it into PowerShell terms, any of these commands will return Pilar Ackerman’s user account:

Get-CsUser –Identity "Pilar Ackerman"

Get-CsUser –Identity "pilar@fabrikam.com"

Get-CsUser –Identity "sip:pilar@fabrikam.com"

Get-CsUser –Identity "fabrikampilar"

Unlike other cmdlets, Get-CsUser and Get-CsAdUser let you use wildcards when specifying the Identity. This command returns Pilar Ackerman’s account, as well as the account for any other user named Pilar:

Get-CsUser –Identity "Pilar *"

Note . We know what you’re thinking: why can’t you just use the person’s SamAccountName (logon name) as an Identity? There’s actually a good reason for that: SamAccountNames do not have to be unique in a forest. That means you could have more than one user with the same SamAccountName. And that makes the SamAccountName unsuitable for use as an Identity.

So then why can you use a user’s display name? Display names don’t have to be unique. Well, … just because.

OU Parameter

Let’s turn our attention to the –OU parameter. If you use the –OU parameter along with the Get-CsAdUser cmdlet, Get-CsAdUser will return a collection of all the user accounts found in the specified Active Directory OU. For example, this command returns all the user accounts found in the North America OU:

Get-CsAdUser -OU "ou=North America,dc=fabrikam,dc=com"

The –OU parameter works pretty much the same way when used with Get-CsUser; the only difference, of course, is that Get-CsUser returns only the users in the North America OU who have been enabled for Microsoft Communications Server:

Get-CsUser -OU "ou=North America,dc=fabrikam,dc=com"

Wow: that did seem easy, didn’t it?

And it was, as long as you remember to set the value of the –OU parameter to the distinguished name of the OU. For example, this is how we get to the Redmond OU, a child OU of North America :

Get-CsAdUser -OU "ou=Redmond,ou=North America,dc=fabrikam,dc=com"

That’s how you do it.

Before you ask, yes, you can retrieve a collection of users in an OU and all its child OUs; in fact, that’s exactly how the -OU parameter works. However, you can’t supply multiple OU names to the –OU parameter. If you try that, your command will fail. Period.

But don’t despair: you can always write a custom script to do this for you. You know, a custom script that returns all your users, grouped by the OU where their user account resides.

Like, you know, this somewhat-rudimentary custom script:

$strFilter = "(objectCategory=organizationalUnit)"

$objDomain = New-Object System.DirectoryServices.DirectoryEntry

$objSearcher = New-Object System.DirectoryServices.DirectorySearcher

$objSearcher.SearchRoot = $objDomain

$objSearcher.PageSize = 1000

$objSearcher.Filter = $strFilter

$objSearcher.SearchScope = "Subtree"

$colPropList = "DisplayName"

foreach($i in $colPropList)

{[void] $objSearcher.PropertiesToLoad.Add($i)}

$colResults = $objSearcher.FindAll()

foreach($objResult in $colResults)

{$x = $objResult.Properties.distinguishedName

$objResult.Path

Get-CsAdUser -OU "$x" | Select-Object DisplayName, CsEnabled}

And no, we won’t bother explaining how this works, at least not today. We’ll save that explanation for a different article .

The –Filter Parameter

The –Filter parameter enables you to “filter” the user accounts returned by Get-CsAdUser or Get-CsUser; that means that you can specify criteria of some kind and only the user accounts that meet that criteria will be returned. And what kind of criteria can you specify? In the case of –Filter, you can create filters based on the Active Directory user account attributes that are directly related to Microsoft Communications Server.

Before we go much further we should note that, at the present time, there are a few Microsoft Communications Server attributes that you can’t filter on; if you put those attributes in a filter all you’ll get back is an error message. However, here are some of the attributes that we were able to successfully use as filters:

• Enabled

• LineServerUri

• LineUri

• SipAddress

• PrivateLine

We were also able to use commands like the following to determine which users had been assigned a per-user policy, using any of the attributes that include Policy in the attribute name. For example, here we’ve used the VoicePolicy attribute:

Get-CsUser -Filter {VoicePolicy -eq "*"}

Even better is the fact that we can retrieve the list of users who had been assigned a particular per-user policy by using a command similar to this one, which returns all the users who have been assigned the voice policy RedmondPolicy :

Get-CsUser -Filter {VoicePolicy -eq "RedmondPolicy"}

Makes sense, right? Let’s run some more commands and explain how they work. Suppose you’d like a list of all the Active Directory users who have not yet been enabled for Microsoft Communications Server. How are you going to do that? Here’s one way to do that:

Get-CsAdUser -Filter {Enabled -eq $False}

As you can see, all we’re doing here is calling Get-CsAdUser along with the –Filter parameter. And what exactly is our filter? This is our filter:

{Enabled -eq $False}

Doesn’t make much sense? Gee; it made sense to us . OK, maybe we should take a moment to walk you through the different parts of the filter.

To begin with, filters must be enclosed in curly braces. (In PowerShell terminology, that makes the filter a “script block.”) Inside the curly braces the filter must adhere to the following format:

Attribute	Operator	Filter Value
Enabled	-eq	$False

So why does PowerShell uses –eq rather than the equals sign? That was a decision made by the PowerShell team many years ago, and, to their credit, they’ve stuck to their guns even though this probably wasn’t the most popular decision they ever made. Here are some of the more commonly-used comparison operators found in Windows PowerShell:

Operator	Definition