Advanced NetIQ SecureLogin Solutions Lecture · Advanced NetIQ SecureLogin Solutions Lecture NIQ14....

www.novel l .comNovell Training Services

AT T L I V E 2 0 1 2 L A S V E G A S

Advanced NetIQ SecureLogin SolutionsLecture

N I Q 1 4

NIQ14: NetIQ SecureLogin Scripting

No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

M a y 1 3 , 2 0 1 2 N I Q 1 4 : N E T I Q S E C U R E L O G I N S C R I P T I N G

Legal Notices

Novell, Inc., makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.

Further, Novell, Inc., makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to make changes to any and all parts of Novell software, at any time, without any obligation to notify any person or entity of such changes.

Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses. See the Novell International Trade Services Web page (http://www.novell.com/info/exports/) for more information on exporting Novell software. Novell assumes no responsibility for your failure to obtain any necessary export approvals.

Copyright © 2009 Novell, Inc. All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Novell, Inc., has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed on the Novell Legal Patents Web page (http://www.novell.com/company/legal/patents/) and one or more additional patents or pending patent applications in the U.S. and in other countries.

Novell, Inc.

404 Wyman Street, Suite 500

Waltham, MA 02451

U.S.A.

www.novell.com

Online Documentation: To access the latest online documentation for this and other Novell products, see the Novell Documentation Web page (http://www.novell.com/documentation).

Novell Trademarks

For Novell trademarks, see the Novell Trademark and Service Mark list (http://www.novell.com/company/legal/trademarks/tmlist.html).

Third-Party Materials

All third-party trademarks are the property of their respective owners.

Copying all or part of this manual, or distributing such copies, is strictly prohibited.To report suspected copying, please call 1-800-PIRATES.

Version 12

http://www.novell.com/info/exports/

http://www.novell.com/company/legal/patents/

http://www.novell.com/documentation

http://www.novell.com/documentation

http://www.novell.com/company/legal/trademarks/tmlist.html

No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

SECTION 1 NIQ14: Secure Login Scripting: Advanced SecureLogin Scripting 5

Objective 1 Agenda 6

Objective 2 Tools and Procedures Used In Class 7

Objective 3 Scripting for Authentication Failures and Exceptions 20

Handling Failed Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Scripting Password Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Handling Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Objective 4 Scripting Complex Authentication Dialogs 43

Dialogs that have a Parent / Child Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Coding for Window Refreshes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54


3Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1


Version 14

NIQ14: Secure Login Scripting: Advanced SecureLogin Scripting

No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

S E C T I O N 1 NIQ14: Secure Login Scripting: Advanced SecureLogin Scripting

The material in this session is part of a two-day Scripting class offered by Novell Training. It is quite likely that this material require MORE than the 4-hours allocated for this class. This is done intentionally. Some students are very experienced with similar material, so the lab should offer some challenge to those individuals. Some students are less familar and therefore a second glance at the instructions may be necessary. The idea of the session is to provide an opportunity—not a challenge. With that in mind, work at a relaxed paced so that you may gain the most from the experience.

This session is intended to follow the Introduction to Novell SecureLogin Class. The introductory class:

provided an overview of Novell SecureLogin (NSL) and the problems addresses by NSL

discussed the architecture of NSL

introduced other software technologies related to NSL

provided hands-on work with some beginning scripting challenges.

The purpose of this class is to demonstrate how to manage application dialogs via scripting (Application Definitions) that go beyond providing just a username and password. This class will use scripting techniques to build more intelligence into Application Definitions for such things as:

scripting for login failures

handling change password dialogs

dealing with authentication dialogs when users cancel out of the dialog

and more!


5Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Objective 1 Agenda

The class will start by covering the tools and the procedures for using those tools, that will be used throughout this class. We start here because you will be going through a repetitive process that includes using those tools and procedures when building or enhancing application definitions.

Learning how to script for authentication failures and exceptions is the next section. This section teaches how to code your application definitions to deal with such conditions as a user providing incorrect credentials or clicking a Cancel button.

Then you will learn how to deal with applications whose authentication dialog screens have a structure more complex than just a user name and password field. For instance, applications that have authentication dialogs that:

have buttons that are contained within a hidden parent/child window structure

or have buttons are in different locations on a dialog whenever the application runs

or use drop-down pick lists

can be problematic when trying to SSO-enable the application.


Version 16


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Objective 2 Tools and Procedures Used In Class

This section covers the tools and procedures for using those tools that will be used repetitively throughout class. The topics in this section include:

Using a tool called the Application Simulator

Editing application definitions using the NSL Tray icon (also called PMU—Personal Management Utility)

Deleting passwords and credentials using the Tray icon.

NOTES:


7Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Applications that display authentication dialogs (especially Windows applications) can handle the dialog screens in many different ways. This means that providing a learning environment for coding application definitions that handle many types of authentication dialogs can be problematic. Providing such a learning environment using third party applications can be impractical due to:

costs associated with licensing the applications

disk space requirements. Using many different applications may require so much disk space as to make using virtual machine technology impossible due to hardware restrictions.

the learning curve associated with learning many different applications so that they may be scripted is too great for a one or two day class.

For these reasons you will be using a single application that is designed to simulate many different types of authentication dialog screens. This tool was originally developed by Novell’s Actividentity partner and is called the Application Simulator. Using the Application Simulator provides a learning environment where you can learn how to code for different types of authentication dialog challenges without having to install or learn many different applications.


Version 18


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The Application Simulator is a program named ASTrainer.exe. This program can be found in your lab environment on the Windows server VM. The program is located in a folder called ASTrainer in E:\NSLApps of the VM.

ASTrainer gives you the flexibility you need in your lab environment by:

presenting several different types of authentication dialog screens

allowing you to configure the Application Simulator’s behavior

being able to define new users to the Application Simulator and lock or unlock those user’s login accounts.

NOTES:


9Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The Application Simulator offers the following types of login scenarios:

simple authentication dialog with just a user name field, password field, an OK button, and a Cancel button

authentication dialogs requiring that the user make a selection from a drop-down list or pick a selection in a list box

buttons on the authentication screen that change position relative to one another on successive invocations

authentication dialog screen whose window title changes with successive invocations

The Application Simulator maintains a “database” of users that are allowed to authenticate using the various login scenarios. Clicking Tools > Configuration from the Application Simulator’s menu bar provides four tabs. These tabs can be used to control the behavior of, and the messages displayed by, the Application Simulator.

Clicking the Users tab as shown in the graphic above, allows for the management of the user accounts that are allowed to login to the Application Simulator using one of the login dialogs. On the Users tab, you can:

define new user accounts or delete existing user accounts


Version 110


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

modify passwords

lock, unlock, disable, or expire accounts.

Selecting the Messages tab allows you to specify the exact messages displayed by the Application Simulator when different kinds of authentication events occur.

For instance, when a user listed on the Users tab exceeds the maximum number of unsuccessful login attempts, the “AccountLocked” message is displayed to the user. This message states: “Your account is locked. Please call the help desk.” These messages can be customized to simulate actual messages that your production applications generate for the same type of authentication event.

NOTES:


11Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The Settings tab allows you to determine the Application Simulator’s behavior for the following:

the number of unsuccessful attempts a user can generate before the Application Simulator locks that user’s account

what string to display as the title on the main Application Simulator window

whether or not case sensitivity should be enforced in passwords

whether a “Login Success” type message should be displayed to the user when they successfully log into the Application Simulator using one of the login scenarios

if the user should be prompted with a “are you sure” type of dialog prior to logging out.

NOTES:


Version 112


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

During your exercises you will occasionally lock out one of the Application Simulator’s user accounts. To unlock the user’s account complete the following:

1. From the Application Simulator’s main menu select Tools > Configuration.

2. Click the Users tab.

3. Double-click the cell that says Yes under the Locked column for the desired user. Select No.

4. Close the Application Simulator down and restart it.

Now the user’s account is unlocked and can be used again during your lab exercises.

NOTES:


13Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

You will be using the Personal Management Utility to develop and modify Application Definitions. The process of getting an Application Definition to function the way you want with all the dialog screens produced by the application is an iterative process. To modify an existing Application Definition follow this simple three step procedure:

1. Right-click the NSL icon in the System Tray; select Manage Logins

2. Highlight the desired Application Definition under Applications in the left pane.

3. Click the Definition tab.

You should develop the coding practice of commenting your Application Definitions. Any line that begins with a pound sign (#) is regarded as a comment line and is ignored when the Application Definition runs.

Good coding practice is to clearly delineate the code associated with each Dialog Specification Block (DSB). Note in the example above you see:

## BeginSection: “Login Window”

Dialog

indent your code here


Version 114


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

EndDialog

## EndSection: “Login Window”

This clearly delineates the code designed to process the application’s login window

Also note in the above graphic that each line of code (including comment lines) is numbered. If there is a syntax error in one of the lines, NSL will identify the offending line by its line number when NSL tries to execute the Application Definition.

NOTES:

During the testing process for Application Definitions you may need to change or verify the password used by the application. This is especially true when building code to detect a login failure. You will need to do this when using the Application Simulator (ASTrainer.exe) in class. To view and change an application’s stored password:

1. Right-click the NSL icon in the System Tray and select Manage Logins


15Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

2. Highlight the particular Application Definition under the Applications heading in the left pane. The ASTrainer Application Definition is selected in the example above.

3. Click Show passwords.

4. Change the password if required for testing.

5. Click OK.

IMPORTANT: NSL allows users to display their own passwords by default. However this option can be disabled globally by setting Allow users to view passwords to No in the General Preferences at a container level using iManager or the NSL Administrative Utility (slmanager.exe).

NOTES:

During the testing of Application Definitions you may need to simulate the first time NSL captures the credentials for the application, multiple times. To do this you must clear the stored credentials associated with the Application Definition. This will simulate a new account running the application for the first time to the NSL Client.


Version 116


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

To delete stored credentials for an Application Definition:

1. Right-click the NSL icon in the System Tray and select Manage Logins.

2. Highlight the desired Application Definition name under Applications in the left pane.

3. Click the Details tab.

4. Select Username.

5. Click the Delete button and select Credential.

6. Select Password and repeat Step 5.

7. Click OK.

Next time the Application Definition is used, it will run as though it was running for the very first time.

NOTES:

More on Dialog Specification Blocks:

As stated in the first day of class, in order for NSL to process a given application dialog screen there must be a Dialog Specification Block (Dialog / EndDialog statements) coded to detect that screen in the Application Definition.


17Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Dialog Specification Blocks can be coded with more or less precision depending on how similar the dialog screens are that are generated by the application. If an application generates multiple dialogs that are very similar in structure, the Application Definition will need to have more code contained within the Dialog Specification Blocks in order to accurately determine which dialog is displayed at any given moment.

In the graphic above, both Dialog Specification Blocks (DSB 1 and DSB 2) will detect the login dialog screen shown. However DSB 2 describes the dialog with much greater detail.

DSB 1 detects the dialog if:

1. it has a class ID of 32770

2. and has a title on the dialog of “Login - Simple”

However if this application puts out dialogs with the same structure, DSB 1 may not be detailed enough to discriminate between different dialogs.

But DSB 2 will detect the this particular dialog only if all of the following are true:

1. it has a title on the dialog of “Login - Simple”

2. has a class ID of 32770

3. contains a field with a Dialog ID of 1001 (this is the field where the user types in their user name.)

4. contains a field with a Dialog ID of 1002 (this is the field where the user types in their password.)

5. has a button with the text “Login” on the button

6. has a button with the text “Cancel” on the button

7. has a field that has a Dialog ID of 1027 and that field contains the string “Username:”

8. has a field that has a Dialog ID of 1028 and that field contains the string “Password:”

9. and finally, has a static pane in the dialog that has a Dialog ID of 1009. (This is the part of the dialog that contains graphic underneath the Window Title and above the Username field.)

The information needed to code DSB 1 is easily found with the Window Finder utility. However, you would need to leverage the SLScriptBuilder utility if you wanted to take the code shown in DSB 2 and copy it directly into an Application Definition.

The SLScriptBuilder utility (SLScriptBuilder.exe) will create the code shown in DSB 2 and then allow you to copy that code to the clipboard. Then that DSB could be pasted into the Application Definition you are building using the Personal Management Utility.

You will get an opportunity to use both Window Finder and SLScriptBuilder in this course.


Version 118


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

NOTES:

The SecureLogin Application Definition Guide is a good reference to have handy when writing Application Definitions. This is a PDF file that can be downloaded from Novell’s web site at:

http://www.novell.com/documentation/securelogin70/

NOTES:


19Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Objective 3 Scripting for Authentication Failures and Exceptions

This section will teach you how to code for authentication failures and exceptions in your Application Definitions. Specifically, you will learn how to code for dialogs that:

are displayed on authentication failures

allow the user to change their password

give the user the ability to cancel off the screen.

NOTES:

Handling Failed Logins

Your Application Definitions should be “smart” enough to account for authentication failures. So when an incorrect password value is entered into a password field, the Application Definition can give the user an opportunity to correct the situation without having to place a call to the Help Desk.

Your “failed login” code should handle dialogs displayed by the application due to such things as:

the user entering an incorrect password the first time the application is launched


Version 120


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

changing the user’s password in the application. The password that was stored for the Application Definition previously, is no longer current. The user needs the opportunity to enter their newly changed password so NSL can store the new password value.

the application leverages the user’s Directory password for the authentication dialog and the host operating system forces the user to change their Directory password at a regular interval.

You will need to understand the structure of the dialog screens put out by the application in the event that these types of authentication failures occur.

NOTES:

You could allow users to correct the login information using the NSL Client when they need to change the password for an application. However the more self-correcting an application definition is, the easier it is for the user to correct the problem themselves without having to contact the help desk!

In the upcoming exercise on handling a failed login you will follow this general procedure for building a more self-correcting application definition:

1. Set an incorrect password for the Application Simulator in the NSL Tray icon’s console.


21Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

2. Generate a login failure by trying to log into the Application Simulator.

3. Then you will use Window Finder to analyze the “login failed” dialog put out by the Application Simulator

4. Edit your Application Definition to detect the “login failed” dialog so the user can correct the failed login.

5. Test your Application Definition

6. Repeat steps 4 and 5 until your Application Definition allows the user to correct the failed login.

NOTES:

You will need to change the password for a user defined in the Application Simulator in order to generate a “login failure” dialog.

From the PMU Console you will need to:

Select the ASTrainer Windows application

Change the password of the demouser1 to the value novell

Click Apply to save your changes.


Version 122


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Next time you attempt to login to the Application Simulator using demouser1, a login failure dialog screen will be generated. This occurs because the Application Simulator has a different password defined internally for demouser1 than the NSL Client has cached locally.

NOTES:

Once you change the password for the demouser1 user in the PMU Console you will need to generate the login failure dialog so that it can be analyzed.

To generate the “login failure” dialog from the Application Simulator click Action on the menu bar followed by Login > Login - Simple. This will generate the “login failure” dialog shown above.

This example demonstrates a parent / child relationship between windows. The window entitled “Login - Simple” will spawn the “login failure” dialog which is a second window entitled “Application Simulator”. Knowing information about parent dialogs can also be used to identify child dialogs. On this second window you will need to dismiss the box in your Application Definition by clicking the OK button.

NOTES:


23Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Once the “login failure” dialog has been generated you will need to use the Window Finder to analyze the structure of the dialog.

NOTES:


Version 124


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Before attempting to modify your Application Definition to detect a login failure let us discuss two commands that will be very important in making your Application Definition behave as desired. These commands are:

DisplayVariables

Ctrl

The purpose of the DisplayVariables command is to allow your Application Definition to be able to prompt the user for the values of the variables that where not entered correctly. This command will display a NSL dialog that will contain a prompt of your choosing, plus data entry fields for each variable you want the user to re-enter.

In the example in the graphic above, the user sees a dialog that has a prompt that says: “Please re-enter credentials” and two data entry fields. One for the user name and the other for the password. The values of those date entry fields will be stored in the $Username and $Password fields.

NOTES:


25Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The Ctrl command is frequently used in Dialog Specification Blocks to help the NSL Client recognize when a given application screen is displayed.

The syntax of the Ctrl statement requires that you specify the Control ID as a minimum. The Control ID would be determined using the Window Finder or SLScriptBuilder utilities.

Ctrl can also specify text that should be on the given control. In the first example above, the control has to have an ID of 32772 and have the string “Cancel” (without the quotes) on the control.

In your next exercise the control will have two lines of text separated by a Return character. You can use a Regular Expression to specify that you are not interested in the value of the second line by using the syntax shown in the second example above. The (.*) in the command is the Regular Expression.


Version 126


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The modifications to your Application Definition to detect the “login failure” dialog will follow the general structure shown in the above graphic.

When you do your exercise try to use just this page as a guide along with the syntax listed in the previous two pages.

NOTES:


27Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

NOTES:


Version 128


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Scripting Password Changes

Applications that require authentication can also force users to periodically change their passwords. Your Application Definitions should recognize those dialogs enforcing the password change so that users can continue to access the applications they need.

You can add “change password” Dialog Specification Blocks to your Applications Definition by:

using the Add Application Wizard

or by manually editing the Application Definition using the PMU Console.

NOTES:


29Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Manually Editing Application Definitions to Detect Password Changes

NSL only detects Login dialog screens. So if you need to add a “Change Password” Dialog Specification Block you either need to manually launch the Wizard as shown previously, or modify the Application Definition directly.

When editing the Application Definition directly you first need to understand what the user would normally have to do on the application’s “Change Password” dialog screen.

In our sample Application Simulator application, the user will:

need to enter their old password

enter a new password

confirm the new password

click the Change Button.

Your “Change Password” code would also need to save the new value for the Password variable. So that the next time the application’s Login dialog is processed, NSL will supply the new password to the application.

NOTES:


Version 130


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Before making any manual changes to your Application Definition you need to analyze the structure of the application’s “Change Password” dialog. In the case of our Application Simulator example, the information shown in the graphic above should be determined using the Window Finder utility.

NOTES:


31Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Implementing changes to your Application Definition that handle the “Change Password” dialog will require the use of the ChangePassword and Set commands.

The ChangePassword command is used to display a dialog to the user that will prompt for a new value for a password variable.

In the graphic above, the example ChangePassword command prompts the user with the string “Please enter a new password now:” and takes the value the user types in for the new password and stores it in a Runtime Variable named ?NewPass.

The Random parameter can be used to invoke the Random Password Generator so that the user doesn’t type in a password. Typically the Random parameter is used in conjunction with a Password Policy so that the randomly generated password conforms to standards you set in the policy.

NOTES:


Version 132


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The Set command is used to assign values to variables. These variables can be either Runtime Variables or Stored Variables.

In the syntax shown in the above graphic, what is being assigned to the variable can be any of the following:

a string enclosed in double quotes

the value of another Runtime Variable

the value of another Stored Variable

or the value of a Directory Variable.

In the first example above, the value of ?TempVar which is a Runtime Variable is being assigned to the Stored Variable named $DirVar.

The second Set example assigns the value “1” to the Runtime Variable named ?Count.

The last Set example takes the value stored in the Runtime Variable named ?NewPIN and stores in the Stored Variable named $Password_PIN in the Directory.

NOTES:


33Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Shown in the graphic above is the general structure of the changes that should be made to your ASTrainer - Simple Application Definition in order to handle the “Change Password” dialog of the Application Simulator.

During the upcoming exercise try to use this page along with the previous pages on the syntax of the ChangePassword and Set commands in modifying your Application Definition.

NOTES:


Version 134


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Handling Exceptions

Your Application Definitions should be coded so that they can handle exceptions. Types of exceptions include the following:

the user is asked to enter the value for some variables and cancels that process

the user is presented with a dialog to change a password and cancels off the screen

the user cancels a pick list.


35Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Use Cases for Handling Exceptions

Your Application Definitions can be coded to prevent users from doing the following when running SSO-enabled applications:

circumventing the NSL login dialog to use the application’s login authentication directly

This means that the user can only access the application via NSL.

cancelling off a change password dialog

This forces the user to change their password when requested.

cancelling a dialog screen that requests some “access related” information other than user name and password

For instance, the user can be prevented from leaving a dialog that requests a server address or name.

The OnException and ClearException commands are used to give your Application Definitions these types of capabilities.


Version 136


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The example you will code will ensure that the user can only access the application under the control of NSL. So as in the example above, if a user does cancel the NSL authentication screen, both the NSL authentication dialog and the application’s authentication dialog are closed. The application you will be SSO-enabling to demonstrate this coding technique is called POPUP.

Syntax for Exception Handling

Essentially, the purpose of the OnException command is to detect when the user has clicked a Cancel button on a dialog. When OnException detects that a Cancel button has been clicked, a subroutine named in the OnException command is executed. This subroutine can run any NSL script commands that you desire. Once the subroutine is complete, control is transferred to the NSL script command immediately following the OnException statement that called the subroutine.

The OnException command syntax specifies the type of exception and the name of the subroutine to call.

In the example shown in the graphic above, when the user clicks a Cancel button on a change password dialog, a subroutine named CHPassCan is called. After the CHPassCan subroutine completes, control would be returned to the statement immediately following the OnException command.


37Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

NOTES:

OnException commands remain active until they are specifically turned off. So this means that the OnException command will apply to your entire Application Definition from the point it is set to the end of the script.

You can stop exception processing by using the ClearException command. The only parameter on the ClearException command is the type of exception that you want to turn off.

NOTES:


Version 138


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

It is fairly common for NSL administrators to terminate the execution of the Application Definition in the OnException subroutine.

In the example above, a Dialog Specification Block is coded to detect an authentication screen for the company’s financial application. This application expects a user name and PIN on it’s authentication screen.

If the user clicks the Cancel button while on this application dialog the EnterVariablesCancelled exception is triggered, causing control to be transferred to the EndItAll subroutine.

The EndItAll subroutine clicks a button (probably a Yes button in response to an “are you sure” type of dialog) and then terminates the Application Definition with an EndScript command.

IMPORTANT: Note that the called subroutine is delineated by the Sub/EndSub commands. All script commands between Sub and EndSub are executed when the subroutine is called.


39Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Practicing Exception Processing with the POPUP Application

The POPUP Application will be used to practice your exception handling coding skills. As with the other applications used in class, you need to analyze the structure of the POPUP application login dialog. The Window Finder utility that you have been using, can do the job. However there is another dialog analysis utility that you will be using in the upcoming exercise that can be very helpful in building Dialog Specification Blocks. This utility is called SLScriptBuilder.

NOTES:


Version 140


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

SLScriptBuilder is a utility that can help you properly code Dialog Specification Blocks so that the various dialogs produced by an application can be accurately detected by the Application Definition.

You can use SLScriptBuilder to glean the same kind of information about the structure of a dialog that Window Finder can provide. However SLScriptBuilder has the advantage of producing a Dialog Specification Block for a given dialog that can then be copied and pasted directly into the Application Definition you are building or modifying.

NOTES:


41Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The graphic above shows a side-by-side comparison of the information displayed by SLScriptBuilder on the left and Window Finder on the right. Note that SLScriptBuilder provided more information with one “drag-and-drop” on the login dialog than Window Finder did.

SLScriptBuilder provided the Dialog IDs of the OK and Cancel Buttons by dragging the icon in the upper left corner of SLScriptBuilder and dropping it on the entire POPUP login dialog. This information about the OK and Cancel buttons was also included in the Dialog Specification Block created by SLScriptBuilder.

SLScriptBuilder can be very useful when trying to code an Application Definition for an application that produces multiple dialogs that have very similar structure.

NOTES:


Version 142


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Objective 4 Scripting Complex Authentication Dialogs

This section deals with handling some of the more complex aspects of scripting authentication dialogs. This discussion covers dialog boxes that are related to one another or have unusual aspects to their structure. The topics in this section include:

Parent / Child Architecture

Handling Window Refreshes

Dialogs that have a Parent / Child Architecture

Applications that you want to SSO-enable may produce dialog windows that are separate distinct windows or the dialogs may be related to one another. In this subsection you will learn about:

the types of Parent / Child architectures

how to code for these relationships in your Application Definitions

a utility you can use to clearly show the relationship between dialogs.


43Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Types of Parent / Child Architecture.

In some applications, one dialog window may create or “spawn” another dialog. For instance, the dialog that was spawned may be created when the user enters incorrect credentials or when the user has to acknowledge the entry of some type of data on a form.

An application coded in such a fashion is said to have a Parent / Child architecture in the dialogs it displays. The Parent dialog is the owner of the dialog it spawned.

As a user of the application you may readily see the relationship between the dialogs. However it is possible to code Parent / Child dialogs so that the relationship between the dialogs is not readily apparent.


Version 144


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The graphic above shows the POPUP application you have already used. This application pops up a dialog when the user enters incorrect credentials. This child dialog must be acknowledged (and then dispatched) by the user by clicking an OK button. The user can not re-enter their credentials without dealing with the child dialog.

These two dialogs demonstrate a Parent / Child relationship that is “modal” in nature. This type of Parent / Child relationship between dialogs is characterized by:

displaying two distinct dialog windows

the child dialog is created in front of the parent dialog that created it

the child dialog has focus and you can not interact with the parent dialog until you have dispatched the child.


45Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The way the modal Parent / Child relationship works is shown in the graphic above. When the user enters either an incorrect user name and/or password the login dialog spawns a child dialog with an OK button.

The user has to acknowledge the child dialog by clicking a control (an OK button) to close the dialog. Only then can the user re-enter their credentials on the parent login dialog.


Version 146


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

However, Parent / Child dialogs can have an “embedded” relationship. In this case the boundaries of each dialog is not easily seen because the child dialog is contained within the boundaries of the parent dialog.

The graphic above shows an application called three.exe. In the authentication screen for three.exe, there is an embedded Parent / Child architecture. The data entry fields for the username and password are in a separate dialog from the dialog that contains the OK and Cancel buttons.


47Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Coding Ramifications of Parent / Child Dialogs.

Parent / Child architecture has an impact on how you code for those types of applications. It is important to understand the ramifications of this architecture so that your Application Definitions function properly for your users. Parent / Child architecture means that:

You must code a Dialog Specification Block to be able to detect when the child dialog is displayed. However, the code associated with the child’s Dialog Specification Block may need to drop credentials (using the Type command) into fields on the parent dialog. The problem is that when the child dialog is detected, it has focus; not the parent dialog containing the input data entry fields.

Entering credentials, and acknowledging the entry of those credentials, may involve controls that exist in two different dialogs; even though all the controls appear to be on the same dialog window.

You must use some type of coding mechanism in your Application Definition that can detect the relationship between the parent and the child dialogs.


Version 148


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The coding mechanism that is employed in Application Definitions to define the relationship between a child dialog and its parent is the Parent / EndParent block. Parent / EndParent blocks allow a child dialog to test for, or act upon, the controls (buttons and fields) that are located in its parent dialog.

You can code the same kind of statements in a Parent / EndParent block that you can code in a Dialog Specification Block (Dialog / EndDialog block). For instance, this means that you can code:

Title, Class, and/or Ctrl commands that can recognize the structure of the child’s parent dialog

Type or Click commands to drop information into edit fields, or click buttons on the parent dialog.

It is important to understand the flow of control when coding Parent / EndParent blocks. If any of the commands in the Parent / EndParent block are not true, execution of the Application Definition will pick up beginning at the next Dialog / EndDialog block, not the next Parent / EndParent block.


49Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Parent / EndParent blocks can be nested within one another if needed. For instance you might have a Dialog / EndDialog block that reads the text on a given button within the child dialog. This Dialog Specification Block might have a Parent / EndParent block associated with it, that identifies the child’s dialog by its window title. And nested within this Parent / EndParent block is another Parent / EndParent block that identifies the parent dialog by its window title and window class.

In the graphic above, is an example of a Dialog Specification Block that has an associated Parent / EndParent block that will be executed if the Dialog / EndDialog block evaluates to true.

The Dialog Specification Block looks for a dialog that has a title on the window of “Financial System” and has a text field that contains the string “User and/or Password incorrect.” This is the application’s login failure dialog.

If this Dialog / EndDialog block evaluates to true, then the following will happen:

1. The DisplayVariables command is used to put up an NSL dialog that requests values for the Username and PasswordPIN variables from the user.

2. The OK button on the NSL dialog is clicked.


Version 150


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

3. If the parent dialog of the login failure dialog has the following characteristics:

a. A text field with Dialog ID 1001 that contains the string “Enter User and PIN for Finance System.”

b. A button with the Dialog ID of 1 that has the text “Login” on it.

4. If #3 is true then

a. Fill field with Dialog ID 1002 on parent dialog with the value of the Username variable.

b. Fill field with Dialog ID 1003 on parent dialog with the value of the PasswordPIN variable.

c. Click the Login Button on the parent dialog.

Identifying Parent / Child Dialogs.

A general rule of thumb is that if you can not SSO-enable an application using the Add Application Wizard you probably need to specify Parent / EndParent blocks.

The SLScriptBuilder utility can recognize Parent / Child relationships between dialogs and build Dialog Specification Blocks including the Parent / EndParent block for you. Then you can copy and paste this code into your Application Definition.


51Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

To show the Parent / Child relationship you need to check the boxes for Read all child controls and Read all parent windows before dragging the magnifying glass icon from SLScriptBuilder to the dialog. In the graphic shown above the magnifying glass icon was dropped on the child dialog window which is the “login failed” dialog.

In the example above, the Dialog / EndDialog block recognizes the “login failed” dialog. The Parent / EndParent block identifies all the controls (data entry fields, text prompts, and buttons) within the parent dialog. The parent dialog is the login screen for the application.

In the above example the child dialog is embedded within the boundaries of the parent dialog. NSL can get confused when trying to drop credentials in embedded dialogs. SLScriptBuilder can provided you with all the structure information you need to properly code your Parent / EndParent block within the Dialog Specification Block.

If the Magnifying Glass icon was dragged and dropped onto the title bar of Three.EXE, SLScriptBuilder would have displayed only the following:

Dialog

Title “Three.EXE - Authentication”


Version 152


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Class “ThunderRT6FormDC”

Ctrl #1 “Cancel”

Ctrl #2 “OK”

Ctrl #3 “User Credentials”

Ctrl #4

Ctrl #5

EndDialog

Notice that this Dialog/EndDialog Block (DSB) does not identify the dialog that actually contains the User name and Password fields. This would cause NSL to become confused to the point that NSL would not enter the credentials into the proper fields and click the OK button.

But if SLScriptBuilder is used to analyze the embedded dialog the following DSB is created:

Dialog

Title “User Credentials”

Class “ThunderRT6Frame”

Ctrl #4

Ctrl #5

Parent

Title “Three.EXE - Authentication”

Class “ThunderRT6FormDC”

Ctrl #1 “Cancel”

Ctrl #2 “OK”

Ctrl #3 “User Credentials”

Ctrl #4

Ctrl #5

EndParent

EndDialog

Note that this DSB recognizes the embedded Child Dialog (with the title of “User Credentials”) while at the same time describing the Parent dialog (with the title of “Three.EXE - Authentication) shown in the above graphic. However, if any of the conditions specified in the Parent/EndParent block are not met, control is transferred to the next Dialog/EndDialog block coded in the Application Definition.


53Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Coding for Window Refreshes

This section will introduce the concept of WM_Events. There are literally hundreds of Window Management events. These events can be detected by NSL if you know what to look for. One WM_Event you will need to understand and code for is the “window refresh”.


Version 154


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

A Little Background Information on Windows Programming

It is useful to understand a little background information on Windows programming in order to better understand how NSL can interact with Win32 programs. In particular it is helpful to have an overview of how the Windows OS communicates to applications.

The Windows operating system is what is referred to as event driven. This means that any Win32 application must have a mechanism by which it can receive messages from the OS and send requests to the OS.

Windows (the OS) will send messages to a particular function within a Win32 application called the message or event handler. The message handler will inform the application when some type of event has occurred to one of the application’s windows (not the OS). These events include such things as a window being moved, resized, or closed. Also, an application can request windowing related services from the OS. These requests from the application fall into the following types:

The application needs to register a window with the OS.

The application needs the OS to create a window for its use.


55Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The application asks the OS to perform some type of maintenance activity on one of its windows. This could be something like refreshing the window with a different caption.

Or the application can ask the OS to destroy a window that it no longer needs.

These windowing related messages that flow from the OS to the application’s message handler and from the application to the OS are collectively referred to as WM_Events. As you might guess, WM stands for Windows Message.

There are well over 200 different WM_Events. However some more common WM_Events and their purpose are as follows:

WM_Create - An application will request that the OS allocate memory for a window of a particular class (A window class is sort of like a template for a window of a particular type.) And that the window be registered with the OS. This event does not however cause the window to be displayed to the user.

WM_SHOWWINDOW - Can be used to hide a currently displayed window or display a window that was created via the WM_CREATE event.


Version 156


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

WM_ACTIVATE - Before a user can provide input to one of the application’s windows that window must be activated. Even though multiple windows from multiple applications may be displayed at any given time, only one of those windows can be the active window.

WM_SIZE - An application will receive this message from the OS when the user changes the size of a window.

WM_MOVE - When a user repositions a window on the desktop, the OS needs to update information on where that window is located. This message provides the updated location information to Windows.

WM_DESTROY - This message tells the OS to close a given window and reclaim the memory the window was using.

NSL’s ability to recognize authentication screens is based on detecting when a WM_CREATE event occurs. When you code a Dialog Specification Block (DSB) in an Application Definition, you are providing NSL with the knowledge it needs to detect the WM_CREATE event that will define and register that particular window.

However by default, NSL can not detect when an existing window simply has a caption or text change due to a window refresh. That is because a screen refresh is not the result of a WM_CREATE event; it is the result of a WM_SETTEXT event. So in order for your Application Definition to function properly, the DSB must specifically look for a WM_SETTEXT event.


57Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

You can instruct NSL to look for any kind of WM_Event by coding the Event command in the DSB. From the syntax shown above you can see that the only parameter to the Event command is the name of the WM_Event you want NSL to trap.

So the example above could be coded in a DSB to trap the occurrence of a window refresh.


Version 158


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

As an example of the properly detecting a screen refresh, lets assume you want to change the POPUP application so that when a user changes the application’s password, that password is not stored in the Directory until the application reports back that the password change was accepted.

So you decide to use the Window Finder or SLScriptBuilder utility to build a DSB for the application’s dialog that reports a successful password change. The DSB in lines 47 through 50 in the above graphic, seem to describe the dialog shown above perfectly.

Then you code lines 52 and 53. These lines take the new password and store it into the Directory, and then print a message to the user stating that their new password has been stored in the Directory.

Upon testing your modified Application Definition you find that a new password never gets stored into the Directory. So it is as if the new DSB never detects the application window stating that the password was changed correctly. The reason for this behavior is shown on the next two pages.


59Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

The reason that the newly coded DSB is not detected, and therefore the new password is not stored in the Directory, is that the window that show that a user has successfully logged in, and the window that says the a new password has been accepted are not two different windows. They are the same window where a refresh has occurred. Since they are the same window, NSL doesn’t look into the Application Definition to run any new lines of code.


Version 160


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

If you use SLScriptBuilder to analyze the structure of the windows you can see that they have the exact same titles, Windows class, and buttons. They also both have a static control field with ID 1002. The only difference in the Control 1002 field is the text. But this second window was not created using the WM_CREATE event. If it had, the DSB would have worked. Instead, the WM_SETTEXT event was used to simply update the contents of the existing window.


61Version 1


No

vell T

rainin

g S

ervices (e

n) 12

Ap

ril 201

1

Since you can see that the window actually changed, you know that some type of WM_Event occurred. Therefore the question becomes what WM_Event type changed the existing window?

Microsoft does provide a utility called Spy++ that can monitor all the different types of Windows events. This utility can be used to help you determine how to properly code the Event command in the DSB.


Version 162

Advanced NetIQ SecureLogin Solutions Lecture · Advanced NetIQ SecureLogin Solutions Lecture NIQ14....

Documents

Transcript of Advanced NetIQ SecureLogin Solutions Lecture · Advanced NetIQ SecureLogin Solutions Lecture NIQ14....