6.1.1 Example Application Definition for the Test Application

The Application Definition for the PSL Password Test Application (PasswordTest.Exe) provides an example of a typical Windows* Application Definition, including error handling and changing the password. Remember, the password for this application is hard coded to single when the application is closed and restarted. This can cause confusion when setting strong password policies and changing passwords. You must also create a password policy called PwdTestPolicy, per the password policy defined in this Application Definition. The password policy must require a minimum of 6 characters, but no complex rules, in order to use single as a password.

Here is the sample Application Definition in its entirety. Following this Application Definition is the explanation of what each section does.

# Set Password Policy
RestrictVariable $Password PwdTestPolicy
Application Definition continued on the next page
# ==== BeginSection: Log on ====
Dialog
Class "#32770"
Ctrl #1001
Title "Log on"
EndDialog
SetPrompt "Username =====>"
Type $Username #1001
SetPrompt "Password =====>"
Type $Password #1002
SetPrompt "Domain =====>"
Type $Domain #1003
Click #1
SetPrompt "Please enter your Username and Password to access NSL Test.  SecureLogin will remember and automatically log you on in future. IT Helpdesk x4546"
# ==== EndSection: Log on ====
# ==== BeginSection: Log on Failure ====
Dialog
Class "#32770"
Title "Log on Failure"
EndDialog
# Read the error message and set it as a temporary variable, then clear it
ReadText #65535 ?ErrorMessage
Click #2
# If log on failed, display the current stored Username and Password and prompt the user to verify them, then retry log on
If "You have failed to log on." -In ?ErrorMessage
DisplayVariables "Log on to PSL Test Application failed. The password for this app must be single when it first starts up. IT Helpdesk x4563"
# Press Alt>F and L to invoke the Logon box so the User doesn't have to.
Type -Raw "\Alt+F" 
Type -Raw "L" 
Type $Username
Type $Password
Type $Domain
EndIf
# ==== EndSection: Log on ====
# ==== Begin Section: Change Password ====
# Change Password Dialog Box
Dialog
Class "#32770"
Title "Change Password"
EndDialog
# Backup password, fill in the Old Username and Password, then start the change password routine
Application Definition continued on the next page
Set ?PwdBackup $Password
Type $Username #1015
Type $Password #1004
ChangePassword ?NewPwd "Please enter a new password for the appli-cation."
Type ?NewPwd #1005
Type ?NewPwd #1006
Click #1
# Change Password Successful message
Dialog
Class "#32770"
Ctrl #65535 "You have changed the password successfully." 
Title "Change Successful"
EndDialog
# Clear Application owned message and accept new password
Click #2
Set $Password ?NewPwd
# ==== End Section: Change Password ====

6.1.2 Application Definition Explained

You can use the same Application Definition to show what function each section performs. Dialog/EndDialog blocks define a windows dialog box. When the dialog box appears, SecureLogin detects this dialog box is based on the information found within the dialog block. The Dialog/EndDialog block must contain enough information for the block to be unique, or the Application Definition will run when other dialog boxes owned by the same executable with the same information appear.

When SecureLogin detects all the information between Dialog and EndDialog is contained in the dialog box on the screen (for example, the application logon box, the change password box, or the failed logon box), it runs the Application Definition commands until it sees the next dialog statement or the end of the Application Definition, whichever is applicable. The order does not matter in windows Application Definitions, because SecureLogin watches for all dialog boxes while the executable is running. Use a logical order for troubleshooting purposes.

6.1.3 Dialog Boxes

The following Application Definition example shows screen captures of the relevant dialog boxes. You can use the Window Finder tool to gather information about the title of the window, class names, dialog IDs, and so on. Use the wizard to automate the Application Definition creation.

Table 6-1 Description

Application Definition Section Comments	Comments
# Set Password PolicyRestrictVariable $Password PwdTestPolicy	This restricts the $Password variable to comply with the Password Policy "PwdTestPolicy".
# ==== BeginSection: Log on ====Dialog Class "#32770" Ctrl #1001 Title "Log on"EndDialog	When PasswordTest.Exe runs, SecureLogin will watch for dialog boxes that appear and match the information defined between the Dialog/EndDialog commands. You can specify all values, or a few, as long as the information specified is unique to that dialog box.
SetPrompt "Username =====> "Type $Username #1001 SetPrompt "Password =====> "Type $Password #1002 SetPrompt "Domain =====>" Type $Domain #1003 Click #1 SetPrompt "Please enter your Username and Password to access NSL Test. SecureLogin will remember and automatically log you on in future. IT Helpdesk x4546" # ==== EndSection: Log on ====	Type the stored ($) Username variable into #1001, and so on. SetPrompt is used to customize the window the user sees when they have no credentials stored. When the user first runs a newly single sign-on enabled application, SecureLogin will prompt for their logon credentials, and store and remember them for future log on attempts.
	Title is Log on. Class is #32770. Username field is Control ID #1001. Password field is Control ID #1002. Other field is Control ID #1003. The OK button is Control ID #1.
	This dialog box is only displayed the first time the Application Definition is run by a user. It prompts the user to enter their credentials for SecureLogin to store them. The SetPrompt command is used throughout the example Application.
	This is the logon failure dialog box. Title is logon Failure. Class is #32770. The OK button is Control ID #2. The error message is Control ID #65535
	This is the change password dialog box. Username field is Control ID #1015. Old Password field is Control ID #1004. New Password field is Control ID #1005. Confirm field is Control ID #1006. The OK button is Control ID #1.
	The ChangePassword command is used in the example Application Definition to display a dialog box for the user to enter their new password. The dialog box is customized to provide more information for the user.