|
|
|
|
|
Searching accounts and resetting passwords in Microsoft Active Directory using LDAP
Search and reset password
This example project describes an UMRA application that searches the user accounts in an Active Directory domain. The accounts are shown in a form table. From the table, the end-user selects a user account and specifies a new password for the account. When the form is submitted, the password is reset.
Figure 59: UMRA Forms client showing Reset password application.
Example project location
The example project can be found at the following location, relative to the UMRA Console directory:
.\Example Projects\LDAP\ActiveDirectory\SearchResetPassword
The UMRA application contains the following projects:
Project |
Description |
LdapAd_Init |
Initialize all of the variables used by the other projects of the application. This project is executed by the other projects. |
LdapAd_Search |
Search the user accounts in Active Directory using an LDAP query. The resulting user accounts are stored in a table that is passed to the next project of the wizard. |
LdapAd_ResetPassword |
Present the form to the end-user. When the form is submitted, reset the password of the selected user account. |
Table 12: Projects of the UMRA application to reset passwords
The next sections describe each of the projects in detail.
Project: LdapAd_Init
Initialization project
The project only contains a script, not a form. The project's script only sets a number of variables and it is executed by the other projects: LdapAd_Search and LdapAd_ResetPassword.
Figure 60: Variable initialization with project LdapAd_Init.
By using this method, the environment dependant variables need to be updated only in this project. The following variables are initialized by the project:
Variable |
Example value |
Description |
%LdapServer% |
king.tools4ever.local3 |
The DNS name of the Active Directory domain controller that runs the LDAP Server. |
%LdapAccount% |
cn=Administrator,cn=Users,dc=tools4ever,dc=local3 |
The full distinguished name of the administrative account that is authenticated on the domain controller. The account needs to have sufficient privileges to reset the password of the domain accounts. |
%LdapPassword% |
bA0U@HGWxUhz8MqG/+Uf23P#/qEDIG8A+ |
The password of the account that is authenticated. The password is stored encrypted in the UMRA script. |
%SearchBase% |
ou=Sales,dc=tools4ever,dc=local3 |
The part of the Active Directory tree from which user accounts must be obtained. |
Table 13: Variables initialized with project LdapAd_Init.
When the script of the project is executed, the variables are initialized.
Project: LdapAd_Search
Searching for user accounts
The project searches for the user accounts that must be presented to the end-user. The results are stored in a table variable that is shown in the form of project LdapAd_ResetPassword. The project is configured as the initial project of project LdapAd_ResetPassword.
The project only contains a script, not a form.
Script action: Execute script
Initializing variables by calling other script
In the first script action, the variable initialization script LdapAd_Init is called to initialize the variables used in the subsequent script actions.
Figure 61: Script action: Execute script of project LdapAd_Init.
The subsequent script actions do not use environment specified variable settings. To customize this UMRA application for another network environment, only the LdapAd_Init script needs to be updated.
Script action: Setup LDAP session
Setup secure LDAP session
With this script action, the LDAP session is setup with the LDAP Server.
Figure 62: Script action: Setup LDAP session.
Since in subsequent script actions, a password of a user account is reset, the session must be setup using SSL encryption. This is a requirement from the Microsoft LDAP implementation. If SSL is not used, the search action will succeed, but the password reset action will always fail.
The LDAP session is setup using the values of the variables specified in project LdapAd_Init. The resulting LDAP session is stored in variable %LdapSession% as specified by property Ldap session.
Script action: Search LDAP
LDAP search specification
In the next action, the search is performed. The search uses the initialized LDAP session (%LdapSession%) and returns the results in table variable %LdapUsers%.
Figure 63: Script action: Search LDAP.
In this particular case, the search is performed in Active Direcotory subtree
ou=Sales,dc=tools4ever,dc=local3
as specified by variable %SearchBase%. All users found (objectClass=User) are returned. For each user account, the common name (cn), a phone number (telephoneNumber) and the distinguished name is obtained. The common name is needed to show to the end-user. The phone number is included to show how additional attribute values can be collected. The distinguished name is required to uniquely identify the user account, when the account is selected and the password of the account is reset.
When the action is executed, the table data is stored in output variable %LdapUsers%. This variable is used in the next project of the UMRA application.
Project: LdapAd_ResetPassword
Reset password project
This is the main project of the UMRA application. It contains both a form and a script. The form shows the table with user accounts and the input fields for the new password. The script actually resets the password of the selected user account.
Figure 64:UMRA form project LdapAd_ResetPassword with form and script to reset the password of an Active Directory user account using secure LDAP..
Besides a number of explanation text fields the form contains the following fields:
- Table with user accounts
- Two input fields for the new password
- Button to submit the form.
Figure 65: Resulting form of ProjectLdapAd_ResetPassword.
These fields are described in detail in the next sections.
Form field: Table with user accounts
Variable generic table
The table is defined as a generic table and with table type: Variable. To configure the table, the name of the variable and the names of the columns contains by the table variable must be specified.
Figure 66: Generic table of the variable type. Specification of the name of the variable with table data and the name of the columns of the table.
The name of the variable corresponds with the name of the variable generated by script action Search LDAP of project LdapAd_Search: %LdapUsers%. The project LdapAd_Search is configured as the initial project of this project. The script of the initial project is executed just before the form of this project is created. In this application, the script of project LdapAd_Search fills the variable %LdapUsers% with user accounts.
Table columns and return variable
The variable %LdapUsers% only holds the table data, not the name of the columns. Therefore, the column names must be specified separately. When the generic table is configured, the table columns can be setup.
Figure 67: Specification of the columns shown in the form and the variable returned.
The Columns tab of the Configure table window shows the available columns and the configured columns. The available columns correspond with the columns specified for the generic table variable. In this example project, all three columns are configured. The column with the DistinguishedName has a zero width and an associated variable: %DistinguishedName%. The name does not look very user-friendly (example: cn=John, ou=Sales, dc=tools4ever, dc=local2). It therefore has a zero width, e.g. is not visible. When the end-user selects an account from the list, the distinguished name of the user account is copied into the variable and passed to the UMRA Service when the form is submitted.
Form fields: Password text input fields
Password fields
Two input text fields are used to specify the new password. Initially, the input fields are empty. When the end-user has entered the password and confirmation field and the form is submitted, the values are copied to %NewPassword% and %ConfirmPassword% and sent to the UMRA Service.
Figure 68: Password input text field specification.
The script of the project will process the specified values to reset the password.
Form fields: Reset password submit button
Submit button actions
When the user clicks the Reset password submit button, a number of actions are executed. First, the values of the form field variables are set according to the form input. This information is then sent to the UMRA Service.
Figure 69: Form actions executed by the UMRA Service when the Reset password button is clicked by the end-user.
The following actions are then executed by the UMRA Service:
- Check the input fields of the submitted form: A check is performed to see if a user account is selected. If this is not the case, an error message is returned and the other script actions are not executed.
- Execute the script of the project that contains the form: The script of the project is executed. The script resets the password of the selected user account and is described in the next sections.
- Return the form of project LdapAd_ResetPassword: The wizard starts over again and presents the screen with user accounts to the end-user.
The script of the project initializes a secure LDAP session with the LDAP Server and resets the password of the selected user account. The script is executed as one the button actions.
Script action: Delete a specific variable
When the form is submitted and processed, the same form is presented again. To reset the internal queue with variables, the %ScriptMessage% variable is reset. This variable is used to show a message to the end-user and not automatically reset. Since the message from the previous session is no longer needed the variable must be reset. (If it was not reset, error messages from the previous session would still popup in the UMRA Forms client).
Figure 70: Script action: Delete a specific variable.
Note that all variables are reset as specified by the submit button action Return the form of project LdapAd_ResetPassword with 2 exceptions: The variables %UmraFormSubmitAccount% and %ScriptMessage% are maintained.
Script action: If-Then-Else
Check password input
The script then checks the specified password and confirmed password with an If-Then-Else script action.
Figure 71: Script action: If-Then-Else to check the password and confirmed password
If the values of the variables %ConfirmPassword% and %NewPassword% correspond, execution of the script continues with the script action with label Start.
Figure 72: If-Then-Else specification.
If the values are not equal, an error message is generated by setting the variable %ScriptMessage% and jumping to the end of the script (Action: Go to label Ready).
When everything is fine, the script continues at the Start location.
Script action: Execute script
Variable initialization
The variable initialization script LdapAd_Init is called to initialize the variables used in the subsequent script actions.
Figure 73: Script action to execute the initialization script.
When the variables are initialized, the LDAP session is setup.
Script action: Setup LDAP session
Setup secure LDAP session
With the action, the LDAP session is setup. The action properties are all specified by variables.
Figure 74: Script action to setup a secure LDAP session.
SSL required to reset password
Note that the session must be setup with SSL. If SSL is not used, the LDAP Server will not accept the password reset action. This is a restriction enforced by the Active Directory LDAP Server implementation. When the session is initialized successfully, the session is stored in variable %LdapSession% as specified by the action property Ldap session.
Script action: Load LDAP modification data
Password attribute specification
Next, the LDAP modification data used to reset the password is initialized. To reset a password, the attribute unicodePwd must be used
Figure 75: Script action to initialize the LDAP modification data with the password attribute value.
For the attribute, the type of modification is set to Replace since the existing password is replaced by a new one. The value of the attribute is set equal to the value of variable %NewPassword% as specified by the end-user. The resulting LDAP modification data is stored in variable %LdapData%.
Note: Internally, the unicodePwd attribute is handled a bit different compared to the other attributes, see knowledge base article KB269190 to check the details.
Script action: Modify directory service object (LDAP)
Password reset action
Finally, the password of the user account is reset.
Figure 76: Script action to reset the password.
The action uses the following properties:
- LDAP session: The LDAP session object, as initialized by script action Setup LDAP session.
- Object name: The distinguished name of the directory service item of which one or more attribute values must be modified. In this case, the directory service item is the user account. The name of the account corresponds with the account selected in the form table with user accounts. The attribute value is specified with variable %DistinguishedName%. The variable is the output variable of the form table and determined when the user selects the Reset password submit button.
- Object data: The modification data, specified by variable %LdapData% as determined by the previous action.
When executed successfully, the password is reset. Next a No operation action is executed. This action is used only as a script location reference. The action is jumped to when the entered password is incorrectly confirmed.
Script action: Delete a specific variable
Variable cleanup
When the script is executed, the wizard starts over again. To make sure that all variables are reset, the variable used for the selected user account is reset.
Figure 77: Script action to delete the %DistinguishedName% variable.
This action is not required since the variable is already reset by the action Return the form of project LdapAd_ResetPassword specified for the Reset password submit button. When the script is used in another project, this might not be the case.
Logging information
UMRA Service log
When executed successfully, the UMRA Service produces a log file as shown below.
Form is generated by the UMRA Service
09:11:22 12/09/2005 Form message: '12/09/2005,09:11:22,"SSP\J. Vriens","Forms list",OK,N/A,"1 projects found for user 'SSP\J. Vriens'."'
09:11:24 12/09/2005 Executing form initialization project 'LdapAd_Search'.
09:11:24 12/09/2005 Variable 1: %UmraFormSubmitAccount%=SSP\J. Vriens
09:11:24 12/09/2005 Calling project 'LdapAd_Init'. Executing script of project.
09:11:24 12/09/2005 Variable 1: %UmraFormSubmitAccount%=SSP\J. Vriens
UMRA Service connects to LDAP Server using SSL
09:11:24 12/09/2005 Setting up LDAP session with host 'king.tools4ever.local3'. Using SSL encryption: 'Yes'.
09:11:24 12/09/2005 User name: 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'.
09:11:24 12/09/2005 Secure LDAP session established with host 'king.tools4ever.local3' (Protocol: 'TLS 1.0 client-side', encryption: 'RC4 stream', cipher strength: 128 bits, hash: 'MD5', 128 bits, key exchange: 'RSA', 2048 bits).
09:11:24 12/09/2005 Authenticating user 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'...
09:11:24 12/09/2005 User 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3' successfully authenticated on LDAP server host 'king.tools4ever.local3'.
09:11:24 12/09/2005 LDAP session information stored in variable '%LdapSession%'.
UMRA Service instructs LDAP Server to search for user accounts
09:11:24 12/09/2005 Searching LDAP with filter 'objectClass=User' in tree 'ou=Sales,dc=tools4ever,dc=local3' using session variable '%LdapSession%'. Scope: 'Subtree'.
09:11:24 12/09/2005 No time out interval used.
09:11:24 12/09/2005 No size limit used.
219 user accounts found, form is presented to end-user
09:11:24 12/09/2005 Search action successfully completed, 219 entries found, stored in variable '%LdapUsers%'.
09:11:24 12/09/2005 Form message: '12/09/2005,09:11:24,"SSP\J. Vriens","Form load",OK,LdapAd_ResetPassword,'
End-user selects a user account, enters password and clicks submit button
09:11:45 12/09/2005 Variable 1: %DistinguishedName%=CN=Actanth Dane,OU=Sales,DC=tools4ever,DC=local3
09:11:45 12/09/2005 Variable 2: %NewPassword%=hio78^
09:11:45 12/09/2005 Variable 3: %ConfirmPassword%=hio78^
09:11:45 12/09/2005 Variable 4: %UmraFormSubmitAccount%=SSP\J. Vriens
09:11:45 12/09/2005 Variable 5: %LdapServer%=king.tools4ever.local3
09:11:45 12/09/2005 Variable 6: %LdapAccount%=cn=Administrator,cn=Users,dc=tools4ever,dc=local3
09:11:45 12/09/2005 Variable 7: %LdapPassword%=bA0U@HGWxUhz8MqG/+Uf23P#/qEDIG8A+
09:11:45 12/09/2005 Variable 8: %SearchBase%=ou=Sales,dc=tools4ever,dc=local3
09:11:45 12/09/2005 Variable 9: %LdapSession%=(0,0X0)
09:11:45 12/09/2005 Variable 10: %LdapUsers%=Table with 219 rows
09:11:45 12/09/2005 Variable 11: %NowDay%=09
09:11:45 12/09/2005 Variable 12: %NowMonth%=12
09:11:45 12/09/2005 Variable 13: %NowYear%=2005
09:11:45 12/09/2005 Variable 14: %NowHour%=09
09:11:45 12/09/2005 Variable 15: %NowMinute%=11
09:11:45 12/09/2005 Variable 16: %NowSecond%=45
09:11:45 12/09/2005 Deleting variable '%ScriptMessage%'.
UMRA Service compares entered password and confirmed password
09:11:45 12/09/2005 If-Then-Else condition [Variable '%ConfirmPassword%' (text) equals (case sensitive) variable '%NewPassword%'] result is TRUE, continue script execution with action 'Start'.
09:11:45 12/09/2005 Calling project 'LdapAd_Init'. Executing script of project.
09:11:45 12/09/2005 Variable 1: %DistinguishedName%=CN=Actanth Dane,OU=Sales,DC=tools4ever,DC=local3
09:11:45 12/09/2005 Variable 2: %NewPassword%=hio78^
09:11:45 12/09/2005 Variable 3: %ConfirmPassword%=hio78^
09:11:45 12/09/2005 Variable 4: %UmraFormSubmitAccount%=SSP\J. Vriens
09:11:45 12/09/2005 Variable 5: %LdapServer%=king.tools4ever.local3
09:11:45 12/09/2005 Variable 6: %LdapAccount%=cn=Administrator,cn=Users,dc=tools4ever,dc=local3
09:11:45 12/09/2005 Variable 7: %LdapPassword%=bA0U@HGWxUhz8MqG/+Uf23P#/qEDIG8A+
09:11:45 12/09/2005 Variable 8: %SearchBase%=ou=Sales,dc=tools4ever,dc=local3
09:11:45 12/09/2005 Variable 9: %LdapSession%=(0,0X0)
09:11:45 12/09/2005 Variable 10: %LdapUsers%=Table with 219 rows
09:11:45 12/09/2005 Variable 11: %NowDay%=09
09:11:45 12/09/2005 Variable 12: %NowMonth%=12
09:11:45 12/09/2005 Variable 13: %NowYear%=2005
09:11:45 12/09/2005 Variable 14: %NowHour%=09
09:11:45 12/09/2005 Variable 15: %NowMinute%=11
09:11:45 12/09/2005 Variable 16: %NowSecond%=45
UMRA Service connects to LDAP Server using SSL
09:11:45 12/09/2005 Setting up LDAP session with host 'king.tools4ever.local3'. Using SSL encryption: 'Yes'.
09:11:45 12/09/2005 User name: 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'.
09:11:46 12/09/2005 Secure LDAP session established with host 'king.tools4ever.local3' (Protocol: 'TLS 1.0 client-side', encryption: 'RC4 stream', cipher strength: 128 bits, hash: 'MD5', 128 bits, key exchange: 'RSA', 2048 bits).
09:11:46 12/09/2005 Authenticating user 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'...
09:11:46 12/09/2005 User 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3' successfully authenticated on LDAP server host 'king.tools4ever.local3'.
09:11:46 12/09/2005 LDAP session information stored in variable '%LdapSession%'.
LDAP modification data is setup with new password
09:11:46 12/09/2005 Storing LDAP modification data in variable '%LdapData%'.
09:11:46 12/09/2005 LDAP modification data:
09:11:46 12/09/2005 ************** Modification data element: 0 *************
09:11:46 12/09/2005 Operation: 'replace', type of data: 'binary'
09:11:46 12/09/2005 Attribute: 'unicodePwd'
09:11:46 12/09/2005 Binary data
Password is reset
09:11:46 12/09/2005 Modifying LDAP directory service object 'CN=Actanth Dane,OU=Sales,DC=tools4ever,DC=local3' with LDAP modification data obtained from variable '%LdapData%'.
09:11:46 12/09/2005 LDAP directory service object 'CN=Actanth Dane,OU=Sales,DC=tools4ever,DC=local3' successfully modified.
09:11:46 12/09/2005 Deleting variable '%DistinguishedName%'.
Wizard starts over again
09:11:46 12/09/2005 Executing form initialization project 'LdapAd_Search'.
09:11:46 12/09/2005 Variable 1: %UmraFormSubmitAccount%=SSP\J. Vriens
09:11:46 12/09/2005 Calling project 'LdapAd_Init'. Executing script of project.
09:11:46 12/09/2005 Variable 1: %UmraFormSubmitAccount%=SSP\J. Vriens
09:11:46 12/09/2005 Setting up LDAP sessions with host 'king.tools4ever.local3'. Using SSL encryption: 'Yes'.
09:11:46 12/09/2005 User name: 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'.
09:11:46 12/09/2005 Secure LDAP session established with host 'king.tools4ever.local3' (Protocol: 'TLS 1.0 client-side', encryption: 'RC4 stream', cipher strength: 128 bits, hash: 'MD5', 128 bits, key exchange: 'RSA', 2048 bits).
09:11:46 12/09/2005 Authenticating user 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3'...
09:11:46 12/09/2005 User 'cn=Administrator,cn=Users,dc=tools4ever,dc=local3' successfully authenticated on LDAP server host 'king.tools4ever.local3'.
09:11:46 12/09/2005 LDAP session information stored in variable '%LdapSession%'.
09:11:46 12/09/2005 Searching LDAP with filter 'objectClass=User' in tree 'ou=Sales,dc=tools4ever,dc=local3' using session variable '%LdapSession%'. Scope: 'Subtree'.
09:11:46 12/09/2005 No time out interval used.
09:11:46 12/09/2005 No size limit used.
09:11:46 12/09/2005 Search action successfully completed, 219 entries found, stored in variable '%LdapUsers%'.
09:11:46 12/09/2005 Next form project: 'LdapAd_ResetPassword' ('LdapAd_ResetPassword')
09:11:46 12/09/2005 Form message: '12/09/2005,09:11:45,"SSP\J. Vriens","Form submit",OK,LdapAd_ResetPassword'