Reference Material | PowerShell cmdlets
All operations that can be performed using the Specops Password Reset administration tools can also be performed from Windows PowerShell.
Getting started
Specops Password Reset includes the following Windows PowerShell cmdlets. To get started you will need to Register the Specops Password Reset Powershell snapin.
- Start PowerShell.
- Register the snapin by using the following command:
Add-PSSnapin Specopssoft.SpecopsPasswordReset
Administration cmdlets
For a list of all the Specops Password Reset administration cmdlets from Powershell, use the following command:
Get-command –noun passwordreset*
The cmdlets that are used to administrate Specops Password Reset from PowerShell are:
- Get-PasswordResetSettings
- New-PasswordResetMailSettings
- New-PasswordResetOneTimePasswordSettings
- New-PasswordResetQuestionDefinition
- New-PasswordResetSecretQuestionsSettings
- New-PasswordResetSettings
- Disable-PasswordResetPolicy
- Remove-PasswordResetEnrollment
- Update-PasswordResetSettings
The New- and Get-PasswordResetSettings cmdlets both have the -GpoName, -GpoGuid and -DomainName switches. If the DomainName is not specified the domain where the user is currently logged on will be used. If you use the -GpoName remember that multiple GPOs can be returned.
Note: The cmdlets will not create the Group Policy Objects for you. The GPOs to be used must exist and can be created and linked from the Group Policy Management Console (GPMC).
Create new Password Reset Settings object for a GPO
This sample shows you how to create and store the initial settings for Specops Password Reset in a GPO.
$prs = New-passwordresetsettings –gponame “My First Gpo” $prs.SecretQuestionsSettings = $null $prs | update-PasswordResetSettings ##You can also add a value for SecretQuestionsSettings
Note: This will not enable Specops Password Reset for the selected GPO. In order to enable Specops Password Reset for a GPO you have to add a one time password settings object or a secret questions settings object to the password reset settings object.
Add default questions
This sample shows you how to add a defauly question to a password reset settings object.
$prs = get-passwordresetsettings -GpoName “My First Gpo” $question = New-passwordResetQuestionDefinition -Question “my new question” –MinLength 3 –Required $prs.Questions.AddQuestionDefinition($question) $prs | update-PasswordResetSettings
Add localized questions
This sample shows you how to add a localized question to a password reset settings object.
$prs = get-passwordresetsettings -GpoName “My First Gpo” $question = New-passwordResetQuestionDefinition -Question “What is your mothers maiden name?” –MinLength 3 –Required $prs.Questions.AddQuestionDefinition($question) $LocalizedQuestion = $question.GetLocalizedQuestion() $LocalizedQuestion.Question = “vad är din mammas flicknamn?” $prs.questions.AddLocalizedQuestion( $LocalizedQuestion, “sv-SE” ) $prs | update-PasswordResetSettings
Enable secret questions
This sample shows you how to enable the secret questions setting.
$prs = get-passwordResetSettings –GpoName “My First GPO” $secretQuestionsSettings = new-PasswordResetSecretQuestionsSettings -numberOfAllowedCustomQuestion 3 –NumberofQuestion 3 $prs.SecretQuestionsSettings = $secretQuestionsSettings $prs | update-PasswordResetSettings
Disable secret questions
This sample shows you how to disable the secret questions setting.
$prs = get-passwordresetSettings –gponame “My First Gpo” $prs.SecretQuestionsSettings = $null $prs | update-PasswordResetSettings
Enable mail settings
This sample shows you how to override the default mail settings that are configured on the server.
$prs = get-PasswordResetSettings –GpoName “My First Gpo” $PasswordResetMailSettings = New-PasswordResetMailSettings –smtpServer “ServerName.test.com" -portnumber 25 $prs.MailSettings =$PasswordResetmailSettings $prs | update-PasswordResetSettings
Revert to default mail settings
This sample shows you how to rollback to the mail settings that are configured on the server.
$prs = Get-PasswordResetSettings -Gponame “My First GPO” $prs.MailSettings = $null $prs | update-PasswordResetSettings
Enable one time password
This sample shows you how to configure one time passwords.
$prs = get-PasswordResetSettings –gpoName “ My First Gpo” $otp = New-PasswordResetOneTimePasswordSettings –from “ServerName.test.com” –to “test@test.qa” –body “here is your one time password : [=%code%=] “ $prs.MobileVerificationSettings = $otp $prs | update-PasswordResetSettings
Disable one time password
This sample shows you how to disable one time passwords.
$prs = Get-PasswordResetSettings -Gponame “My First GPO” $prs.MobileVerificationSettings = $null $prs | update-PasswordResetSettings
Autoenrollment cmdlets
We recommend using the normal enrollment process, having each end user answer a number of questions, in Specops Password Reset. However if this cannot be done, users can be automatically enrolled by the administrator with the following cmdlet:
- New-PasswordResetEnrollment
To use this cmdlet some additional PowerShell scripting is required.
The New-PasswordResetEnrollment has the following required parameters:
- -userName – the name of the user to enroll
- -questionsAndAnswers – a hash table containing the questions and answer for the user
Optionally the following two parameters can be used to:
- -serverName – the name of the Specops Password Reset server
- -serverPort – the port used when communicating with the server
If the two parameters above are omitted they will be read from the registry. On a computer where the SPR admin tools has been installed, these values should be present in the registry.
Note: In order to use the New-PasswordResetEnrollment cmdlet the user performing the call must be a member of the Specops Password Enrollment Agents security group on the Specops Password Reset server. If the group does not exist on the server, it must be created.
Autoenroll a user
To enroll one user with hard coded values:
New-PasswordResetEnrollment -userName Bob -questionsAndAnswers ([ordered] @ {'What is your name?'='Bob';' What is your social security number?'='12345'})
Autoenroll users using a CSV file
The information used for the answers can for example be collected from a text file. The following example assumes that a csv file with the following content is used:
User,SSN,ShoeSize
Bob,12345,8
Karen,6789,6
To use this file as a datasource for the enrollment the following script could be used:
foreach ($line in (Import-csv c:\temp\qaimport.csv)) {$qa = [ordered]@{} $qa.Add("What is your social security number?", $line.SSN) $qa.Add("What is your shoe size?", $line.ShoeSize) New-PasswordResetEnrollment -User $line.User -QuestionsAndAnswers $qa }
Autoenroll users using information in Active Directory
To use data that is stored on the Active Directory object for each user, a function like the following could be created:
function EnrollUsers($ouPath) { $searcher = New-Object DirectoryServices.DirectorySearcher $searcher.SearchRoot = (New-Object DirectoryServices.DirectoryEntry $ouPath) $searcher.PageSize = 1000 $searcher.Filter = '(&(objectCategory=user)(userAccountControl:1.2.840.113556.1.4.803:=512))' $searcher.PropertiesToLoad.Add('name') > $null $searcher.PropertiesToLoad.Add('employeeNumber') > $null $searcher.PropertiesToLoad.Add('department') > $null $searcher.PropertiesToLoad.Add('division') > $null $users = $searcher.FindAll(); foreach ($user in $users) { $name = $user.Properties.name $department = $user.Properties.department $division = $user.Properties.division if ($name -and $department -and $division) { $qa = [ordered]@{} $qa.Add("In which department do you work?", $department) $qa.Add("In which division do you work?", $division) New-PasswordResetEnrollment -userName $name -questionsAndAnswers $qa Write-Host 'Enrolled' $name } else { Write-Host 'Failed to enroll' $name } } }
The above function needs to be called with a parameter that is the LDAP path of an OU. The enrollment will be performed on all the users in the OU.
EnrollUsers 'LDAP://OU=SomeSprDudes,DC=acme,DC=com'