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.

  1. Start PowerShell.
  2. 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'