{"id":2653,"date":"2013-10-27T00:01:00","date_gmt":"2013-10-27T00:01:00","guid":{"rendered":"https:\/\/blogs.technet.microsoft.com\/heyscriptingguy\/2013\/10\/27\/the-admins-first-steps-local-group-membership\/"},"modified":"2013-10-27T00:01:00","modified_gmt":"2013-10-27T00:01:00","slug":"the-admins-first-steps-local-group-membership","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/the-admins-first-steps-local-group-membership\/","title":{"rendered":"The Admin’s First Steps: Local Group Membership"},"content":{"rendered":"

Summary<\/strong>: Richard Siddaway talks about using Windows PowerShell to discover the membership of local groups.\n\"Hey, Hey, Scripting Guy! I’ve just starting using Windows PowerShell to administer my systems, and I’ve been told I need to check the membership of local groups on all my servers. How can I do that?\n— AK\n\"Hey, Hello AK,\nHonorary Scripting Guy, Richard Siddaway here today—filling in for my good friend, The Scripting Guy. Windows PowerShell is great because you have a number of ways to perform most tasks. You’ll see an example of that in this post, where there are three ways to solve this issue. This is a strength but also a weakness because it can confuse people who are starting to use Windows PowerShell. My advice has always been to find something that works and stick with it. You get more issues solved that way.\nWhen we look at local groups, the most important is the Administrators group. This bestows full control of the system and allows you to do anything to that machine. We’ll use that group as an example throughout this post, but the ideas can be applied to any local group.\nOf the three ways to find local group membership, the oldest method uses the WinNT ADSI provider. ADSI is a scripting interface to directory services. It’s normally used for scripting against Active Directory, but you can also use it against local machines.<\/p>\n

$group = [ADSI]”WinNT:\/\/.\/Administrators”<\/p>\n

 @($group.Invoke(“Members”)) |<\/p>\n

foreach {$_.GetType().InvokeMember(“Name”, ‘GetProperty’, $null, $_, $null)}\nThe ADSI scripting interface isn’t directly available in Windows PowerShell in the same way it is in VBScript. Instead, you have to use the System.DirectoryServices.DirectoryEntry .NET Framework class, which provides a wrapper for ADSI. A shortcut, known as a type accelerator has been provided so you don’t have to type the whole class name. To add confusion, the type accelerator is known as [adsi]<\/strong> or [ADSI]<\/strong>—case doesn’t matter.\nThe WinNT provider is used to access the local machine by using “.” to represent the system together with the name of the group—in this case, Administrators. You then have to use the Invoke()<\/strong> method of the $group<\/strong> object to get the members that you can pipe to Foreach-Object<\/strong>, which uses the InvokeMember()<\/strong> method to get the member name. The output will look something like this:<\/p>\n

Administrator<\/p>\n

Richard\nPersonally, I don’t like using “.” to represent the local machine. It’s easy to overlook, and I have seen problems when using it with WMI. I prefer to use $env:COMPUTERNAME<\/strong>, and pick the machine’s name from the environmental variables:<\/p>\n

$group =[ADSI]”WinNT:\/\/$($env:COMPUTERNAME)\/Administrators”<\/p>\n

 @($group.Invoke(“Members”)) |<\/p>\n

foreach {$_.GetType().InvokeMember(“Name”, ‘GetProperty’, $null, $_, $null)}\nThis is OK if your machine is in a workgroup; but in a domain, you might get answers like this:<\/p>\n

Administrator<\/p>\n

Domain Admins<\/p>\n

Richard\nIt’s not easy to separate local users from domain accounts by using this approach. Luckily, you have some alternatives. One of the alternatives involves using WMI. When I’m working with WMI, I find that the CIM cmdlets introduced in Windows PowerShell 3.0 are the easiest to work with:<\/p>\n

$group = Get-CimInstance -ClassName Win32_Group  -Filter “Name = ‘Administrators'”<\/p>\n

Get-CimAssociatedInstance -InputObject $group -ResultClassName Win32_UserAccount |<\/p>\n

select -ExpandProperty Caption\nUse the Win32_Group<\/strong> class to get the WMI object that represents the group. Use that object in Get-CimAssociatedInstance<\/strong> to find the Win32_UserAccount<\/strong> instances that are associated with that group. On a workgroup machine, you get this:<\/p>\n

RSLAPTOP01Administrator<\/p>\n

RSLAPTOP01Richard\nAnd on a domain machine, you get this:<\/p>\n

WIN12R2Administrator<\/p>\n

MANTICORERichard\nNow you can see which of the results are local accounts and which are domain accounts. But (and isn’t there always a but?) you don’t get the nested domain groups. You need to find the associated groups, which simply involves another call to Get-CimAssociatedInstance<\/strong>:<\/p>\n

$group = Get-CimInstance -ClassName Win32_Group  -Filter “Name = ‘Administrators'”<\/p>\n

Get-CimAssociatedInstance -InputObject $group -ResultClassName Win32_UserAccount |<\/p>\n

select -ExpandProperty Caption<\/p>\n

Get-CimAssociatedInstance -InputObject $group -ResultClassName Win32_Group |<\/p>\n

select -ExpandProperty Caption\nBecause you are displaying the same data, you can output from multiple calls (generally its viewed as a bad thing), and you get something like this:<\/p>\n

WIN12R2Administrator<\/p>\n

MANTICORERichard<\/p>\n

MANTICOREDomain Admins\nNow you can see the domain and machine name, so you know which entries are local, and you get the nested groups. If you can’t use the CIM cmdlets, you can fall back on the WMI cmdlets.<\/p>\n

$query = “ASSOCIATORS OF {Win32_Group.Domain=’$($env:COMPUTERNAME)’,Name=’Administrators’} WHERE ResultClass = Win32_UserAccount”<\/p>\n

Get-WmiObject -Query $query | Select -ExpandProperty Caption<\/p>\n

$query = “ASSOCIATORS OF {Win32_Group.Domain=’$($env:COMPUTERNAME)’,Name=’Administrators’} WHERE ResultClass = Win32_Group”<\/p>\n

Get-WmiObject -Query $query | Select -ExpandProperty Caption\nThis is a bit more complicated than the CIM cmdlet version because you have to create a WMI Query Language (WQL) query to discover the associated Win32_UserAccount<\/strong> and Win32_Group<\/strong> instances. The difficult part is getting the contents of the {}<\/strong> correct. The easiest way is to look at the __RELPATH<\/strong> property of the returned object when you use the following command:<\/p>\n

Get-WmiObject -Class Win32_Group -Filter “Name = ‘Administrators'” | fl *\nRemember to change the double quotes to single quotes to make the query work.\nYou get the same results as with the CIM cmdlets:<\/p>\n

WIN12R2Administrator<\/p>\n

MANTICORERichard<\/p>\n

MANTICOREDomain Admins\nThe third and final way to get this data is to drop back to the .NET Framework class and use the System.DirectoryServices.AccountManagement<\/strong> classes that were introduced in .NET Framework 3.5.<\/p>\n

Add-Type -AssemblyName System.DirectoryServices.AccountManagement<\/p>\n

$ctype = [System.DirectoryServices.AccountManagement.ContextType]::Machine<\/p>\n

$context = New-Object -TypeName System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList $ctype, $env:COMPUTERNAME<\/p>\n

$idtype = [System.DirectoryServices.AccountManagement.IdentityType]::SamAccountName<\/p>\n

$group = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($context, $idtype, ‘Administrators’)<\/p>\n

$group.Members |<\/p>\n

select @{N=’Domain’; E={$_.Context.Name}}, samaccountName\nThis may look a bit more complicated, but most of it is concerned with defining the objects that you want to work with. The script starts by using Add-Type<\/strong> to load the System.DirectoryServices.AccountManagement<\/strong> .NET Framework classes into Windows PowerShell. Not all.NET Framework classes are loaded by default—only those that are thought to be of the most use to the most people.\nAfter that, you use the ContextType<\/strong> class to say that you are looking at the local machine rather than the domain. The System.DirectoryServices.AccountManagement<\/strong> classes aren’t used much, which is a shame because they are powerful and they span local and domain level activities.\nYou can then use the context type and the local machine name to create a context. The IdentityType<\/strong> defines what you are using to identify objects—in this case, the SamAccountName<\/strong>.\nNow you can use all of that data in the FindByIdentity()<\/strong> method of the GroupPrincipal<\/strong> class to find the group. The Members<\/strong> property holds the members as you might expect; but the final piece is that you have to dig into the Context of the member to discover whether the object comes from the domain or from the local machine.\nLuckily the code runs much faster than I can write about it and you get results like this:<\/p>\n

Domain             SamAccountName<\/p>\n

——                  ————–<\/p>\n

WIN12R2         Administrator<\/p>\n

Manticore.org   Domain Admins<\/p>\n

Manticore.org   Richard \nWorking through these three methods illustrates an important point: If there are multiple methods available, you should investigate them to discover how they work, any issues that occur for you, and which one works best with your skills and way of working.\nThe last part of this journey is to turn your code into a function that you can use across multiple remote machines. I’m going to use the System.DirectoryServices.AccountManagement<\/strong> approach so I can illustrate how these classes can be used against remote machines without the need to rely on Windows PowerShell remoting.<\/p>\n

function get-localgroupmember {<\/p>\n

[CmdletBinding()]<\/p>\n

param(<\/p>\n

[parameter(ValueFromPipeline=$true,<\/p>\n

   ValueFromPipelineByPropertyName=$true)]<\/p>\n

   [string[]]$computername = $env:COMPUTERNAME<\/p>\n

)<\/p>\n

BEGIN {<\/p>\n

Add-Type -AssemblyName System.DirectoryServices.AccountManagement<\/p>\n

$ctype = [System.DirectoryServices.AccountManagement.ContextType]::Machine<\/p>\n

}<\/p>\n

 <\/p>\n

PROCESS{<\/p>\n

foreach ($computer in $computername) {<\/p>\n

  $context = New-Object -TypeName System.DirectoryServices.AccountManagement.PrincipalContext -ArgumentList $ctype, $computer<\/p>\n

  $idtype = [System.DirectoryServices.AccountManagement.IdentityType]::SamAccountName<\/p>\n

  $group = [System.DirectoryServices.AccountManagement.GroupPrincipal]::FindByIdentity($context, $idtype, ‘Administrators’)<\/p>\n

  $group.Members |<\/p>\n

  select @{N=’Server’; E={$computer}}, @{N=’Domain’; E={$_.Context.Name}}, samaccountName<\/p>\n

} # end foreach<\/p>\n

} # end PROCESS<\/p>\n

}<\/p>\n

 <\/p>\n

“Win12R2”, “W12SUS” | get-localgroupmember\nStart by defining the function and parameter. In this case, you’re only interested in the remote computer name. When you use an array as the type, you can also do this:<\/p>\n

get-localgroupmember -computername Win12R2, w12sus\n…but only if you have the Foreach<\/strong> loop in the PROCESS block. (You don’t have to capitalize these blocks of code—I do it to make my code more readable.)\nYou only need to load the .NET Framework classes, define the context, and identity types once. So those steps go into the BEGIN block, which executes once when the first object in the pipeline hits the function.\nThe PROCESS block loops through the computers and creates a context for each machine. The Administrators group is found and the membership list is extracted. You are working against remote machines so the computer is added to the output to identify to which machine the results apply.\nYou can use this function on the pipeline as shown or interactively by passing one or more computer names to the function.\nIf you want to extend the use of this script you could:<\/p>\n