PowerShell cmdlets

Specops Password Reset administration is built with scripting in mind. All operations that you can perform from the administrative user interfaces you can perform from Windows PowerShell.

Specops Password Reset includes several Windows PowerShell cmdlets.

Register the Specops Password Reset Powershell snapin

To start using the Specops Password Reset cmdlets, start PowerShell and register the snapin by using the following command:

Add-PSSnapin Specopssoft.SpecopsPasswordReset

Administration cmdlets

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

To get a list of all the Specops Password Reset administration cmdlets from within PowerShell, use the following command:

Get-Command -Noun PasswordReset*

This will produce a list, similar to that above.

Examples

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.

Create new Password Reset Settings object for a GPO

This sample will create and store the initial settings for Specops Password Reset in a GPO.

$prs = New-PasswordResetSettings -GpoName 'My First GPO'
$prs.Save()

Add default questions

This sample show you how to add a default question to a password reset settings object.

$prs = Get-PasswordResetSettings -GpoName 'My First GPO'
$question = New-PasswordResetQuestionDefinition -Question "What is your mother's maiden name?" -MinLength 3 -Required
$prs.AddQuestionDefinition($question)
$prs.Save()

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 mother's maiden name?" -MinLength 3 -Required
$localizedQuestion = $question.GetLocalizedQuestion()
$localizedQuestion.Question = "Vad är din mammas flicknamn?"
$prs.AddQuestionDefinition($question)
$prs.AddLocalizedQuestion($localizedQuestion, "sv-SE")
$prs.Save()

Enable secret questions

This sample shows you how to enable the secret questions setting.

$prs = Get-PasswordResetSettings -GpoName 'My First GPO'
$secretQuestionsSettings = New-PasswordResetSecretQuestionsSettings
$secretQuestionsSettings.NumberOfAllowedCustomQuestions = 2
$secretQuestionsSettings.NumberOfQuestions = 3
$resetSettings.SecretQuestionsSettings = $secretQuestionsSettings
$resetsettings.Save()

Disable secret questions

This sample shows you how to disable the secret questions setting.

$prs = Get-PasswordResetSettings -GpoName 'My First GPO'
$resetSettings.SecretQuestionsSettings = $null
$resetsettings.Save()

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
$passwordResetMailSettings.SmtpServer = 'server name'
$passwordResetMailSettings.FromEMailAddress = 'frommail@someserver.com'
$passwordResetMailSettings.PortNumber = 25
$prs.MailSettings = $passwordResetMailSettings
$prs.Save()

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.Save()

Enable one time password

This sample show you how to configure one time password.

$prs = Get-PasswordResetSettings -GpoName 'My First GPO'
$otp = New-PasswordResetOneTimePasswordSettings
$otp.From = 'from@someserver.com'
$otp.Body = 'Here is your one time password: [=%Code%=]'
$prs.OneTimePasswordSettings = $otp
$prs.Save()

Disable one time password

This sample show how to disable one time password.

$prs = Get-PasswordResetSettings -GpoName 'My First GPO'
$prs.OneTimePasswordSettings = $null
$prs.Save()

Autoenrollment cmdlets

It is strongly recommended to use the normal Enrollment process in Specops Password Reset, that is, having each end user supply answers to a number of questions. However if this for some reason cannot be done, users can also be automatically enrolled by the administrator. A cmdlet called New-PasswordResetEnrollment is available for this purpose.

To use this cmdlet some additional PowerShell scripting is required in order to read answers and, optionally, questions from some type of data source for all users.

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 have been installed, these values should be present in the registry.

Examples

To start using the cmdlets, start PowerShell and register the snapin.

Autoenroll a user

To enroll one user with hard coded values:

New-PasswordResetEnrollment -userName Bob -questionsAndAnswers @{'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 = @{}
  $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 = @{}
            $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'

Page last modified on May 08, 2009, at 03:00 PM

Related