Onboarding Script | Report for each system the users it has and if they are managed

[Idan]

Today I had a conversation with a new JumpCloud customer, and they raised an issue they have to optimize their JumpCloud onboarding project (i.e., deploying JumpCloud across their entire company, which is significant in size).

The ask was to know the users on each system (aka device) and whether JumpCloud manages them. Going to the current JumpCloud reports would be less helpful in this case, as these reports show each User the systems bound to it. In this scenario, we want the exact opposite.

This use case was very interesting, so I decided to script and share it with the JumpCloud community. My approach was to get all users from "System Insights" and cross reference that with all "Systems". In SQL terms, this is a Left-Outer Join between "Systems" (on the left) and "System Insights Users" (on the right), where the join is on the SystemId. I'm using a Left-Outer Join because we are looking at this from the device perspective, and some devices may have no users on them. From there, I decided to change the names of the fields to be more consistent and friendly to new JumpCloud customers unfamiliar with our API.

The script returns a summary to your console about interactive (real/human) users and the systems in your environment, two output files: one in CSV, which you can use in Google Sheets/Excel/etc., and a JSON file you can process however else you want. The output files also have a field named " systemJumpCloudDetails" that contains an HTTPS link to the device in your JumpCloud console (this is useful for processing systematically).

You can copy paste the script in this post to a file named "all_users_on_devices.ps1" and use it to create your reports.

The generated report is also helpful for compliance purposes, as non-managed users are visible even if they are admins. For example, in a scenario where there are users with Admin privileges but not IT staff (such as R&D employees), it is essential to know if other local users appear on a device and what their privileges are. Pushing the report to a versioning system allows monitoring of such changes for compliance and auditing.

Happy New Year to all !

DISCLAIMER:

a. JUMPCLOUD DOES NOT PROVIDE SUPPORT FOR THIS SCRIPT

b. THIS SCRIPT IS PROVIDED AS-IS WITH NO WARRANTY OR GUARANTEE

c. USE THIS SCRIPT ON YOUR DISCRETION

d. YOU MAY USE THIS SCRIPT FOR TESTING, LEARNING, AND INSPIRATION

<# 
# THIS SCRIPT WAS CREATED BY IDAN MASHAAL
# NAME OF SCRIPT: 'all_users_on_devices.ps1'
#
# 1. DISCLAIMER:
#    a. JUMPCLOUD DOES NOT PROVIDE SUPPORT FOR THIS SCRIPT
#    b. THIS SCRIPT IS PROVIDED AS-IS WITH NO WARRANTY OR GUARANTEE
#    c. USE THIS SCRIPT ON YOUR DISCRETION
#    d. YOU MAY USE THIS SCRIPT FOR TESTING, LEARNING, AND INSPIRATION
#
# 2. Purpose: Reports for all systems and all the users that exist on them, 
# regardless if they are managed or unmanaged by JumpCloud. Using such
# a report may be helpful when starting a new JumpCloud project deployment.
#
# 3. How is this achieved? By retrieving all JumpCloud Systems and all users from System Insights
# and doing a Left Join from Systems to Users because some systems may not have users.
# 
# 4. What is the Output?
#    a. Summary printed to default output (usually the console)
#    b. Report in CSV file format
#    c. Report JSON file format 
#    d. Both reports contian the field 'systemJumpCloudDetails' which is a HTTPS link to the system in the JumpCloud console
#    e. Script performance (duration) depends on the number of systems and users in your environment
#
# 5. Requirements:
#    a. The 'JumpCloud' Powershell Module. (you can use this script to install the module, modify $psmodule_install_if_missing)
#    b. The 'JoinObject' Powershell Module. (you can use this script to install the module, modify $psmodule_install_if_missing)
#    c. JumpCloud API Key (read-only preferred)
# 
#>
###################### Global Configuration - Start ######################
$jc_api_key = 'YOUR_JUMPCLOUD_API_KEY_HERE'
$report_file_name_prefix = 'report_all_users_on_devices'
$psmodule_install_if_missing = $false
$psmodule_install_scope = 'CurrentUser'
####################### Global Configuration - End #######################

################ DO NOT CHANGE ANY LINES BELOW THIS LINE! ################

##### START OF SCRIPT #####

## Install modules if not installed
if ( $psmodule_install_if_missing )
{
    ## Install JumpCloud Module in configured scope if not installed
    if ( -not (Get-InstalledModule JumpCloud -ErrorAction SilentlyContinue) )
    {
        Install-Module JumpCloud -Scope $psmodule_install_scope -Force
    }

    ## Install JoinModule Module in configured scope if not installed
    if ( -not (Get-InstalledModule JoinModule -ErrorAction SilentlyContinue) )
    {
        Install-Module JoinModule -Scope $psmodule_install_scope -Force
    }
}

## Import Modules
Import-Module JumpCloud
Import-Module JumpCloud.SDK.V1
Import-Module JumpCloud.SDK.V2
Import-Module JumpCloud.SDK.DirectoryInsights
Import-Module JoinModule -DisableNameChecking

## Connect to JumpCloud
Connect-JCOnline -JumpCloudApiKey $jc_api_key -Force
$timestamp_utc = $(((get-date).ToUniversalTime()).ToString("yyyyMMdd_HHmmss"))
$report_file_name = ($report_file_name_prefix + '-' + $timestamp_utc)

## Get All System Insights (si) Users
$jc_si_users = Get-JcSdkSystemInsightUser

## Get All JumpCloud Systems
$jc_systems = Get-JCSystem

## Left-Join between Systems and Devices because we can have devices that have no users
$jc_system_users = $jc_systems | LeftJoin $jc_si_users -On _id -Equals SystemId 

## Make output human readable even without prior JumpCloud knowledge
$result_field_names = @(
    @{Name='systemJumpCloudId'; Expression='SystemId'},
    @{Name='systemHostName'; Expression='hostname'},
    @{Name='systemJumpCloudDisplayName'; Expression='displayName'},
    @{Name='systemOs'; Expression='os'},
    @{Name='osFamily'; Expression='osFamily'},
    @{Name='osVersion'; Expression='version'},
    @{Name='osArch'; Expression='arch'},
    @{Name='systemAgentVersion'; Expression='agentVersion'},
    @{Name='systemRemoteIp'; Expression='remoteIp'},
    @{Name='isSystemOnline'; Expression='active'},
    @{Name='localUserName'; Expression='Username'},
    @{Name='isUserAdmin'; Expression='Admin'},
    @{Name='isUserReal'; Expression='RealUser'},
    @{Name='isUserManagedByJumpCloud'; Expression='Managed'},
    @{Name='isUserManagedByActiveDirectory'; Expression='AdManaged'},
    @{Name='systemInsightsCollectionTime'; Expression='CollectionTime'}
    @{Name='systemJumpCloudDetails'; Expression={"https://console.jumpcloud.com/#/devices/$($_.SystemId)/details"}}
)
$result = $jc_system_users | Select-Object -Property $result_field_names

## Output Report Results
$jc_unmanaged_real_users = $result | Where-Object -Property isUserReal -EQ $true | Where-Object -Property isUserManagedByJumpCloud -EQ $false | Measure-Object | Select-Object -ExpandProperty Count
$jc_managed_real_users = $result | Where-Object -Property isUserManagedByJumpCloud -EQ $true | Measure-Object | Select-Object -ExpandProperty Count

#$result | Format-Table *

Write-Output ("`n----------------------------------------------------------------------------------")
Write-Output ("All Users on All Devices Report for UTC timestamp: " + $timestamp_utc)
Write-Output ("* Number of Systems: " + $jc_systems.Count)
Write-Output ("* Number of joined records between all systems and all users: " + $result.Count)
Write-Output ("* Number of JumpCloud managed real (interactive) users on all systems: " + $jc_managed_real_users)
Write-Output ("* Number of unmanaged real (interactive) users on all systems: " + $jc_unmanaged_real_users)

## Store Results to the same folder as the script in csv
$result | Export-Csv -Path ($report_file_name + '.csv')
Write-Output ("* CSV Report File Name: " + "'" + $report_file_name + ".csv" + "'")

## Store Results to the same folder as the script in csv
$result | ConvertTo-Json | Out-File -FilePath ($report_file_name + '.json')
Write-Output ("* JSON Report File Name: " + "'" + $report_file_name  + ".json" + "'")
Write-Output ("----------------------------------------------------------------------------------`n")
##### END OF SCRIPT #####