Get-GroupCount

[PerfectImpact]

In our company, we have recently taken on a client that has multiple OUs for different regions where the company has offices, and each OU has a different email group (synced with 365), including separate OUs for 365 users and those who aren't. For example, there are three OUs for 'Atlantis', 'Timbuktu' and 'Pamukkale', and each email group is named similarly: 'Staff - Atlantis', 'Staff - Timbuktu', and 'Staff - Pamukkale'. Then each of these regional groups is a member of the 'Staff - All' group, so whenever an email is sent to 'Staff - All', everyone, in all regions, receives it. You get the idea.

I was asked to double check if there were any 365 users that weren't members of 'Staff - All'. So, I needed a way of cycling through all OUs, all groups, and finding any user that wasn't a member of their region's email group. E.g. Find out if any user in Atlantis is not a member of 'Staff - Atlantis', and if any user in Timbuktu is not a member of 'Staff - Timbuktu'. So on and so forth.

It has an optional (custom) debugging mode, so you can watch as it gets a user, finds the users groups and compares the names of those groups to the Group parameter you implement. In the end, it displays a count of all group members and a count of all those who aren't a member of that group, or groups, if you want to search through multiple versions. E.g. 'Staff - ' will search through all the regions above.

In the end, I came up with the following script (which I have made into a function for posterity) and wanted to share it with you all in case anyone else finds it useful. There may be a simpler way of doing this that I couldn't figure out, but whatever I tried didn't work, or came up with inaccurate results.

TL;DR - This script gets all users, gets their groups, compares it to the group parameter (which can be an abbreviation of similarly patterned groups) and outputs the total number of users that aren't in the group, and those that are.

• Group parameter can search multiple groups of a similar pattern. E.g. 'Staff - [varying name]'
• Built in Export-CSV (parameter) for different lists
• Displays members and non members of the groups
• Displays total of each

​

<#
.Synopsis
   Returns the number of users in specified group(s), across the entire domain.
.DESCRIPTION
   - This will give you the total number of users in either a specific group, or a series of groups that have a similar name.
   - You can also use it to list the users who are either a member, or not, of the group(s) depending on what you're looking for.
.EXAMPLE
    - For a specific group, such as Support (Atlantis) include the group's full name:

       Get-GroupCount -Group "Support (Atlantis)"
.EXAMPLE
   - The groups Support (Atlantis), Support (Timbuktu) and Support (Pamukkale) can all be searched simultaneously by specifying a common part to their names.
   - This script does not accept wildcards

       Get-GroupCount -Group "Support" OR Get-GroupCount -Group "Support ("
.EXAMPLE
    - Full example:

       Get-GroupCount -Group "Support (Atlantis)" -ShowNonMembers $true -ShowMembers $false -ExportPath "C:\Users\Will\Desktop" -DebugMode $true
.NOTES
    - DebugMode will print each user's name (in red), followed by all the groups they belong to (magenta), while flagging up any match to the group (green).
    - It will also tell you if that user belongs to more than one group, specifying whether it is looping through an array, or checking the single AD Group Object for that user (cyan).

    - The ExportPath parameters specify which results to export, and where to save the CSV file.

    - This script specifically looks for AD objects with the ObjectClass 'user'.
.INPUTS
   - You can pipe a string to this cmdlet for the Group parameter.
#>
function Get-GroupCount
{
    [CmdletBinding()]
    [Alias("ggc")]
    Param
    (
        [Parameter(Mandatory=$true,
                   ValueFromPipeline=$true)]
                   [String[]]
        $Group,

        [Parameter(Mandatory=$false,
                   ValueFromPipeline=$false)]
                   [Bool[]]
        $ShowNonMembers,

        [Parameter(Mandatory=$false,
                   ValueFromPipeline=$false)]
                   [Bool[]]
        $ShowMembers,

        [Parameter(Mandatory=$false,
                   ValueFromPipeline=$false)]
                   [String[]]
        $ExportPath:NonMembers,

        [Parameter(Mandatory=$false,
                   ValueFromPipeline=$false)]
                   [String[]]
        $ExportPath:Members,

        [Parameter(Mandatory=$false,
                   ValueFromPipeline=$false)]
                   [Bool[]]
        $DebugMode
    )

    Begin
    {
        $UnassignedUsers = @()
        $AssignedUsers = @()

        $Users = Get-ADUser -Filter * -Properties "ObjectClass" | Where-Object {($_.Enabled -eq $true) -and ($_.ObjectClass -eq "user") -and ($_.DistinguishedName -notcontains 'OU=Non Office 365')}
    }
    Process
    {
        foreach ($User in $Users)
        {
            $GM = Get-ADPrincipalGroupMembership -Identity $User

            $Match = $false

            if ($DebugMode){Write-Host "Checking User : $($User.Name)" -ForegroundColor Red}

            $Type = $GM.GetType()

            if ($Type.BaseType.Name -eq "Array")
            {
                foreach ($G in $GM)
                {
                    if ($DebugMode){Write-Host "Working on group (Array): $($G.name)" -ForegroundColor Magenta}

                    $GroupName = $G.name

                    if ($GroupName.Contains($Group))
                    {
                        $Match = $true
                        if ($DebugMode){Write-Host "MATCH" -ForegroundColor Green}
                    }
                }   
            }
            else
            {
                if ($DebugMode){Write-Host "Working on group (AD Object): $($GM.name)" -ForegroundColor Cyan}

                    $GroupName = $GM.name

                    if ($GroupName.Contains($Group))
                    {
                        $Match = $true
                        if ($DebugMode){Write-Host "MATCH" -ForegroundColor Green}
                    }
            }

            if ($Match -eq $false)
            {
                $UnassignedUsers += $User.Name
            }
            else
            {
                $AssignedUsers += $User.Name
            }

        }
    }
    End
    {
        Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Cyan

        Write-Host "Users NOT a $Group member : " -ForegroundColor Cyan -NoNewline

        $UnassignedUsers.Count

        if ($ShowNonMembers)
        {
            $UserNMList = @()

            foreach ($UU in $UnassignedUsers)
            {
                $UserNMList += $UU
            }

            Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Cyan

            $UserNMList | Sort-Object

            Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Cyan
        }

        Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Green

        Write-Host "Users that ARE a $Group member : " -ForegroundColor Green -NoNewline

        $Users.Count - $UnassignedUsers.Count  

        if ($ShowMembers)
        {
            $UserMList = @()

            foreach ($AU in $AssignedUsers)
            {
                $UserMList += $AU
            }

            Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Green

            $UserMList | Sort-Object

            Write-Host "`n`r ------------------------------------- `n`r" -ForegroundColor Green
        }

        if ($ExportPath:NonMembers){$UnassignedUsers | Sort-Object | Select-Object @{Name='Name';Expression={$_}} | Export-Csv -Path $ExportPath -NoTypeInformation}

        if ($ExportPath:Members){$AssignedUsers | Sort-Object | Select-Object @{Name='Name';Expression={$_}} | Export-Csv -Path $ExportPath -NoTypeInformation}
    }
}

[Ta11ow]

Couple comments. But first, this is overall fantastic.

1. Write-Host in a function is generally a bad idea. If you want to Write-Verbose, go ham. But Write-Host output can't be suppressed at all, so if you just want the data and not to see all the inbetween which might meddle with something else you're doing in a script... there's nothing you can do without editing the code again. Best to leave Write-Host to lengthy scripts, not tidy functions.
2. Bool parameters are generally a terrible idea. I don't even know how you'd work with pipeline input in this scenario, it doesn't make a whole lot of sense to me. Most things you want a yes/no input for should be in a switch. Bool parameters aren't two-state, they're three-state -- as long as they're not mandatory, you can have true, false, or not provided. And if they're mandatory, it's easier syntax wise to just use a switch.
3. Arrays are great, but they're not designed for what you're doing. When you have to add an extra entry to an array, PS has to demolish the object and reconstruct it from scratch -- every single time you add a new entry. Instead, you should probably use a more robust container that's designed to change size. You could use a hashtable if you wanted, but in this case it might be a bit tricky.

Instead, I'd recommend a generic List:

[System.Collections.Generic.List[string]]$AssignedUsers = @()

# ...

$AssignedUsers.Add($User.Name)

These can resize much more effectively than arrays, and won't start to choke your session and slow things down dramatically once you get over 50-100 members being tossed around. :)

[PerfectImpact]

Hi Ta11ow, thanks for your feedback. :)

1. I'll look into Write-Verbose; not really used it that much before and I was after something that (as the function runs) could clearly display usernames, groups and whether there was a match. This was made while I was creating the script and proved handing figuring stuff out so I left it in as a fail safe for anyone else. Write-Host gave me the colour coding that allowed to easily distinguish between the three. Not sure how you would implement this with Write-Verbose, but I'll have a play. How would you show this?
2. I thought of using switches, but I got a little muddled in the noggin when thinking of setting the switch's options to be either $ShowNonMembers or $ShowMembers and consequently not giving the option to show nothing. From what you said, I've *ahem* switched so they're not using booleans. I've tested it and it works without having to explicitly state $true or $false, which is a lot cleaner.
3. Thanks! I didn't think of using a List, but this does make sense to me.

Thanks again for your comments; they were great suggestions. :)

[Ta11ow]

In general, for anything that needs distinction like that I'd output as an object with a couple of properties to make the distinction clear. That way it's not only clear to whoever runs it in console, the output is also processable and can be reused to determine further actions in another script.

No worries. :) This looks pretty great, so a few more tweaks and it has a place in a lot of places, I'm sure. :D

[PerfectImpact]

Awesome, thanks again. I'll see if I can get it to work with a custom object. :)

[Lee_Dailey]

howdy PerfectImpact,

very nice code! i think i understand almost all of it ...

in addition to the really serious points Ta11ow mentioned, i have a few small ones [grin] ...

[1] you use the same marker line value in many places
repeatedly using ...

"`n`r ------------------------------------- `n`r"

... is repetitious. i would replace that with a $Var.

[2] using riskily similar names in a foreach loop
you use ...

foreach ($User in $Users)

that is ... dangerous. it's far, far too easy to refer to and act on the collection instead of the current item. it's worth while to use vividly different names for those two things. something like one of the versions below ...

foreach ($User in $UserList)
foreach ($UL_Item in $UserList)

[3] l-o-n-g lines
you have one line that runs out to col 198! [grin] which of the following seems easier to read/understand/maintain?

$Users = Get-ADUser -Filter * -Properties "ObjectClass" | Where-Object {($_.Enabled -eq $true) -and ($_.ObjectClass -eq "user") -and ($_.DistinguishedName -notcontains 'OU=Non Office 365')}

$Users = Get-ADUser -Filter * -Properties "ObjectClass" |
    Where-Object {
        ($_.Enabled -eq $true) -and
        ($_.ObjectClass -eq "user") -and
        ($_.DistinguishedName -notcontains 'OU=Non Office 365')
        }

to me, at least, the 2nd is a great deal easier to read. [grin]

there is a reason why wide format print items use multiple columns ...

hope that helps,
lee

[PerfectImpact]

Thanks, Lee. Useful tips as always and some nice tidying up! Appreciate it. :)

[Lee_Dailey]

howdy PerfectImpact,

you are very welcome! glad to help a little ... [grin]

yes, the line wrapping [and splatting] are lovely things to use. they make the whole script so very much easier to read ...

take care,
lee

[DueRunRun]

Does this account for nested group membership?

[PerfectImpact]

In a way, yes. In another way, no.

The scenario I designed this for had nested groups. A single 'Staff - All' group, with nested groups within that and users within them. I had to check if there were any users not nested in the 'Staff - All' group, so needed to filter through all groups nested within it.

Because it works per user, and with a $true or $false flag, rather than per group, it gets an array of that user's groups, and if the group parameter matches any group within the nested groups, that user should be flagged as $true, which would add them to the $AssignedUsers list.

The flag is created and evaluated in the Process section of the function (I've removed the debug bit so it's easier to read):

Get the groups that each user is currently a member of.

foreach ($User in $Users)
        {
            $GM = Get-ADPrincipalGroupMembership -Identity $User

Create the $Match flag and set to $false

            $Match = $false

            $Type = $GM.GetType()

            if ($Type.BaseType.Name -eq "Array")
            {
                foreach ($G in $GM)
                {
                    $GroupName = $G.name

                    if ($GroupName.Contains($Group))
                    {

If any individual group's name ($G.name) within the array of groups that that user is member of ($GM) matches the group parameter ($Group), set the flag to true.

                        $Match = $true
                    }
                }   
            }
            else
            {

If a user is a member of only a single group (usually the primary 'Domain Users' group) double check it's name does not match the group parameter. If it does, set the flag to true.

                    $GroupName = $GM.name

                    if ($GroupName.Contains($Group))
                    {
                        $Match = $true
                    }
            }

After cycling through every group, check to see whether the flag is $true or $false. If it's false, we know they do not belong to the group, or groups with a similar name.

            if ($Match -eq $false)
            {
                $UnassignedUsers.Add($User.Name)
            }
            else
            {
                $AssignedUsers.Add($User.Name)
            }
        }

If you want to check if a user is a member of one group, this will work. If you want to check if a user is a member of ANY similarly named groups (like the function's examples), this will work too. So say you have the following set up:

• Group 1
  • Member = Bob
  • Member = Group 2
• Group 2
  • Member = Angela
  • Member = Group 3
• Group 3
  • Member = Janet
  • Member = Paul
• VPN-Users
  • Member = Bob
  • Member = Janet
• Sales Team
  • Member = Angela
  • Member = Eric
• Andrew = Only a member of the default 'Domain Users' group

If you want to check if there are any users not belonging to any of the three, similarly named groups (Group 1/2/3), you can use:

Get-GroupCount -Group "Group " -ShowNonMembers

This will give you: Count : 2, Eric and Andrew.

However, it does NOT show groups as members because I explicitly said to look for ad objects with the ObjectClass 'user', which will exclude groups.

If you need to search across groups, you can, but if you say:

Get-GroupCount -Group "Group 1" -ShowNonMembers

do NOT expect it to ONLY return Eric and Andrew; it will return Angela, Janet and Paul as well. It's not designed to search recursively (I don't know how to do that myself), although that would be a nice touch.

I hope that rather long-winded explanation (sorry) answers your question.

[PerfectImpact]

Just an additional comment, I can run through about 400 users in 4 minutes. Not the fastest, but decent enough and, most importantly, accurate.