Onboarder.exe to assign users by using a Command after agent install

[JuergenKlaassen]

Hi 
I want to share my most recent work over the Xmas-holidays up until today to come up with a packaged script to assign a user to a device post agent installation in a self-service manner. 

<#
.SYNOPSIS
Two weeks ago there was a significant new enhancement launched by JumpCloud: Command After Agent Install
Now you can sequence commands in alphabetical order which will be executed once the JumpCloud Agent becomes active on a new device. This gives you ample of new capabilities to take immediate action on devices and it's basically a fire-and-forget situation. Once you have figured out your 'baseline commands', every new device will automatically get them without you - as an admin - to trigger these commands. 

This capability also kept me thinking if there could be a simplified approach to make the onboarding of users to a device more convenient and more user-driven. First I went into a little rabbit hole and wanted to find a way to extract the UserID once a user is logged on to the User Console and then use the ID to assign the user by using the SystemContextAPI. I ran into early limitations there and after realising that there's no straight forward angle to it, I ditched my efforts there and started over. 

So I pivoted to the angle I took previously with other AutoPilot-ish scripts and repurposed some of that work into this one. As these previous scripts were using some vault (like Azure Key Vault or Keepass) to keep the API-key protected, but I wanted something without any third-party tool, I thought about packaging the script as an executable and encrypting the API-key at the same time. 
As a result, you still need a tool to package the script, but during the enrolment process this solution doesn't require an external vault nor any blob storage or similar. 

.DESCRIPTION

This executable, bundled with a secret-textfile and an AES-encryption key is distributed as a payload within a Command and gets executed as the current logged in user on a Windows Device. 
It prompts the user to enter the username and the EmployeeID (which gets validated). Once this is done, the user will be assigned to the system as a standard user and MFA on the device will be turned on. 

In my dev-environment, the agent will be installed automatically during the OOBE-phase of Windows on FirstLogon. A while later the Command triggers and launches the Onboarder.exe.

.COMPONENTs

The following components are in use here:

• Script: Onboarder.ps1 (functionality explained below) packaged as a binary using PowerShell Packager
• Tool: PowerShell Packager
• Script: API-Enrypter.ps1 to encrypt the JumpCloud-API-key (role: Manager) 
• File: EncryptedSecret.txt carries the AES-encrypted API-key
• File: AES.key the randomly generated encryption key
• Binary: JumpCloud Agent (installed manually or scripted during first-boot)
• Command: carrying the payloads and the script to execute itself
• EmployeeID's: populated in the directory

.FUNCTIONALITY

Setup

1. After customising the script to individual needs, package it with the PowerShell Packager.
2. Use the API-Encrypter.ps1 on a dedicated and secured administrative device.
   Upload the 2 generated files to your Command which is used after agent install.
   Attach the packaged script to the Command as well. Size is around 500KB only. 
   In my own setup, I'm using the default location C:Windows\Temp for execution.
   Note: You can also store the content of the files in the JumpCloud Password Manager. 
3. Populate the script within the Command itself. Give it a Timeout After of at least 5min. 

Command

Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

# If PSModule RunAsUser is not installed, install it
if ( -not (get-installedModule "RunAsUser" -ErrorAction SilentlyContinue)) {
    install-module RunAsUser -force
}
$Command = {
Start-Process "C:\Windows\Temp\Onboarder-RC.exe"
}
sleep 60

invoke-ascurrentuser -scriptblock $Command

Execution

1. Once triggered post installation of the agent, the Command will deliver the 3 attached files to C:\Windows\Temp 
2. The Command installs NuGet as it's required by the PS-Module RunAsUser
3. The Onboarder-binary gets launched, reads the EncryptedSecret.txt by using the AES.key and extracts the API-Key to be able to connect to the JumpCloud PowerShell Module. The secret/key-files will be instantly removed after extraction of the API-key. 
4. After a while, the user gets prompted to provide the username and EmployeeID 
5. A moment later, the user is assigned to the device and a reboot is initiated
6. The user is able to login on the newly provisioned device by using the JumpCloud Username and Password and Push-MFA as a third factor.

.EXTERNALHELP

• JumpCloud KB's
• PowerShell Pro Tools documentation
• PowerShell documentation by MSFT and related blogs on using PSCredential objects

.LINKS

• PowerShell Packager from PowerShell Pro Tools
• JumpCloud KB: Command After Agent Install
• Github repo with the scripts: Onboarder.ps1 and API-Encrypter.ps1

.NOTES

• Other validating factors besides the EmployeeID can be incorporated, i.e. by looking up the hostname or any other attribute within the directory. For example, the Description-field could carry an 'enrolment PIN'
• During the packaging process I used the following settings:
  • Unchecked: Package Referenced Scripts
  • Unchecked: Package References Modules
  • Checked: Require Elevation
  • Checked: High DPI Support
  • Checked: Windows UI Support
• Security Concerns: Certainly there is remaining risk of exposing the API-key. Despite the fact that the API-key is encrypted with a random AES-key, during runtime of the binary, the API-key gets extracted and passed over to the JumpCloud-Module. This is not without risks and can be reverse engineered. Therefore: Use this after your own careful assessment and consideration only. 

#>

Thanks for reading as usual. 
Cheers

Juergen

[JacobLawson]

Interesting approach to getting the employee ID.  Another option could be querying JumpCloud Directory Insights via the API for the system_create event of that device.  That event has the id of the user that initiated the enrollment in one of its fields, initiated_by.id.