Autoenroll users for self-password reset

If the Security questions & answers verification option is enabled for self-service password reset, users need to enroll for password self-service. Enrollment is a one-time process where users provide answers to security questions. If your organization stores employee data such as social security numbers, places of birth, ID numbers, or similar, you can enroll users automatically by preloading the data into their Q&A profiles.

In this tutorial, you will learn how to enroll users for password self-service using PowerShell cmdlets, and how to configure Adaxes to automatically enroll new users and update enrollment data for already enrolled users.

PowerShell cmdlets for enrollment

To enroll and cancel enrollment for password self-service, use the following PowerShell cmdlets:

• New-AdmPasswordSelfServiceEnrollment
• Remove-AdmPasswordSelfServiceEnrollment

New-AdmPasswordSelfServiceEnrollment

The New-AdmPasswordSelfServiceEnrollment cmdlet enrolls a user for password self-service.

Required parameters:

• Identity – specifies the user to enroll. You can identify a user by the distinguished name (DN), GUID, security identifier (SID), full name and Security Accounts Manager (SAM) account name. You can also set the parameter to an object variable (e.g. $myUser) or pass a user object through the pipeline to the parameter.

• QuestionsAndAnswers – specifies a hash table that maps security questions to answers.

• AdaxesService – specifies the DNS name of the Adaxes service that will be used to execute the cmdlet.

Example 1 – Enroll a user with hard-coded questions and answers

Import-Module Adaxes

$question1 = "What are the last 4 digits of your credit card?"
$answer1 = "1234"
$question2 = "What is your social security number?"
$answer2 = "987654321"

New-AdmPasswordSelfServiceEnrollment JohnSmith `
    -QuestionsAndAnswers @{$question1=$answer1;$question2=$answer2} -AdaxesService localhost

Example 2 – Enroll users via a CSV file

Import-Module Adaxes

$question1 = "What are the last 4 digits of your credit card?"
$question2 = "What is your social security number?"

foreach ($line in (Import-Csv c:\qa.csv))
{
    $answer1 = $line.CardDigits
    $answer2 = $line.SSN

    New-AdmPasswordSelfServiceEnrollment $line.User `
        -QuestionsAndAnswers @{$question1=$answer1;$question2=$answer2} -AdaxesService localhost
}

The example assumes that a CSV file with the following content is used:

User,CardDigits,SSN
JohnSmith,1234,654321
JimWillis,1122,332211

Remove-AdmPasswordSelfServiceEnrollment

The Remove-AdmPasswordSelfServiceEnrollment cmdlet cancels password self-service enrollment for a user account.

Required parameters:

• Identity – specifies the user to disenroll. You can identify a user by the distinguished name (DN), GUID, security identifier (SID), full name and Security Accounts Manager (SAM) account name. You can also set the parameter to an object variable (e.g. $myUser) or pass a user object through the pipeline to the parameter.

• AdaxesService – specifies the DNS name of the Adaxes service that will be used to execute the cmdlet.

Example:

Remove-AdmPasswordSelfServiceEnrollment JohnSmith -AdaxesService localhost

Permissions

By default, users are allowed to perform the enroll and disenroll operations only for themselves. The permissions to enroll and disenroll other users are granted with the help of security roles. To allow enrolling and disenrolling users, a security role must contain the Enroll/Disenroll User permission.

 How to add Enroll/Disenroll User permission {id=howto_grantrights}

• Launch Adaxes Administration console.

• Expand Adaxes service \ Configuration \ Security Roles.

• Select the security role you want to modify.

  

• In the Permissions section on the right, click Add.

  

• In the list of object types, select User.

• In the General permissions section, select the Enroll/Disenroll User (Password Self-Service) permission in the Allow column.

  

• Click OK and then click Save changes.

  

To enroll users for password self-service using a PowerShell script, the script must be executed under an account that has the permissions necessary to read data from the data source (CSV file, HR database, etc.) and enroll users for password self-service in Adaxes.

Enrollment by schedule

You can configure Adaxes to automatically enroll new users and update Q&A profiles of existing ones if the information used for their enrollment changes. For this purpose, you can use a built-in scheduled task, Self-password reset enroller. The task automatically runs a PowerShell script for user enrollment on a predefined schedule.

By default, the task is disabled. Before enabling it, you need to modify the PowerShell script it executes to get enrollment data from your data source.

To activate the Self-password reset enroller task:

1. Launch Adaxes Administration console.

    How {id=launchConsole}

   • On the computer where Adaxes Administration console is installed, open Windows Start menu.

   • Click Adaxes Administration Console.

     

2. Expand Adaxes service \ Configuration \ Scheduled Tasks \ Builtin and select Self-password reset enroller.

   

3. Right-click the Run PowerShell script action and then click Edit Action in the context menu.

   

4. Click the Edit button and modify the PowerShell script to get data from your data source.

   

   By default, the script gets enrollment data from a Microsoft SQL Server database. If your data is stored in an MS SQL database, specify your database host, change the database name, table, fields, etc.

   For information on how to create scripts for business rules, custom commands, and scheduled tasks, see Server-side scripting.

5. If necessary, change the user account used to run the script.

   

   The user account must have the rights to read data from the data source and enroll users for password self-service in Adaxes. By default, the script is executed using the Adaxes service account that has the rights needed to enroll users for password self-service.

6. Click OK and then click Save changes.

   

7. To enable the scheduled task, right-click it, point to All Tasks, and click Enable.

   

---