Scripting new user onboarding with First Day Password

One common question we have received regarding Specops First Day Password is how to bulk enroll users. Many of the organizations or industries we work with, for example education, onboard several new users or employees at specific intervals.

The good news is that First Day Password enrollment is done via PowerShell and therefore we can easily build a script to enroll each batch of new users as they come through your new hire process.

Single user enrollment

First, a quick refresher on how to enroll a single user:

Set-SpecopsFirstDayPassword -Username sierra.test1 -PersonalEmail specops.test1@gmail.com 
-UserMobile +12155550123 -FromDate "12/04/2024 06:00" -ValidNumberOfDays 3

Note of the mobile number and personal email address, only one or the other is required – if you provide both, the user can choose which one to use to authenticate with at the time they set their First Day Password. Either one on its own is sufficient.

Specifying the From Date and Valid Number of Days fields are also optional – you may want to set these so that the user can only set their First Day password on or around their expected start date. If left blank the cmdlet will use the default values (from the current date/time, and for 21 days).

Verify the results with Get-SpecopsFirstDayPassword

Get-SpecopsFirstDayPassword -Username sierra.test1

Username     FromDateInUtc        ToDateInUtc          InviteSent
--------     -------------        -----------          ----------
sierra.test1 12/4/2024 6:00:00 AM  12/7/2024 6:00:00 AM False

Bulk user enrollment

In this example we’ll get our new user data via a CSV file that contains fields corresponding to the parameters accepted by Set-SAOnboarding:

• Username
• PersonalEmail
• UserMobile
• FromDate
• ValidNumberOfDays

Keep in mind that not all fields are required (as discussed above). In the case of the CSV you can simply leave those fields blank.

Of course, use of a CSV is not strictly required. If your new users are already being automatically created elsewhere, it may make more sense to build additional automation to pull the necessary information from those systems (e.g. a REST API interface to your HRIS or other provisioning tools) then feed that data to the Set-SpecopsFirstDayPassword cmdlet, you can modify the script accordingly. While we are not experts in every HRIS API out there, we have plenty of experience working with customers to fine tune their implementations to get the best use out of our products.

$newUsers = Import-Csv 'c:\temp\newusers.csv'
ForEach ($newUser in $newUsers) {
    $newUserHash = @{}
    $newUser.PSObject.Properties | % { if ($_.Value) { $newUserHash[$_.Name] = $_.Value } }
    write-verbose -Verbose "Creating First Day Password for $($newUserHash.userName)"
    Set-SpecopsFirstDayPassword @newUserHash -force
}

A note on PowerShell Splatting:  We convert each line from the CSV Import (which PowerShell gives us as a PSCustomObject) into the @newUserHash table, which is then passed to the Onboarding cmdlet in a technique called Splatting. This is a way to convert each CSV column directly into a cmdlet parameter, and any parameters that are blank are cleanly omitted as well. You can read more on splatting direct from Microsoft.

Confirm the results of your script with a final Get-SpecopsFirstDayPassword:

> Get-SpecopsFirstDayPassword

Username     FromDateInUtc         ToDateInUtc           InviteSent
--------     -------------         -----------           ----------
sierra.test3 12/6/2024 8:00:00 AM  12/26/2024 8:00:00 AM      False
sierra.test2 12/5/2024 9:00:00 AM  12/8/2024 9:00:00 AM       False
sierra.test1 12/4/2024 6:00:00 AM  12/7/2024 6:00:00 AM       False

Invites, if configured, are now queued up and will be sent on the first user counting in the onboarding timeframe, or you can send them immediately using Send-SpecopsFirstDayPasswordNotification

For more information about First Day Password, see:

https://specopssoft.com/blog/configure-initial-password-remote-onboarding/
https://specopssoft.com/blog/secure-new-hire-passwords-employee-onboarding/