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.

  1. Start PowerShell.
  2. Register the snapin by using the following command:
Copy

Shell Script

Add-PSSnapin Specopssoft.SpecopsPasswordReset

Administration cmdlets

For a list of all the Specops Password Reset administration cmdlets from Powershell, use the following command:

Copy

Shell Script

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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$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.

Copy

Shell Script

$prs = get-PasswordResetSettings –gpoName “ My First Gpo” $otp = New-PasswordResetOneTimePasswordSettingsfrom “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.

Copy

Shell Script

$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:

Copy

Shell Script

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:

Copy

Shell Script

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:

Copy

Shell Script

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.

Copy

Shell Script

EnrollUsers 'LDAP://OU=SomeSprDudes,DC=acme,DC=com'