Using Novell SecureLogin to Enable Web Applications for Single Sign-on
Articles and Tips: article
Consultant
Novell, Inc.
kalewis@novell.com
01 May 2002
This AppNote details an example of using Novell SecureLogin 3.0 to enable a Web application for single sign-on functionality. The application used to illustrate the key features of this product is MyRealBox.
- Introduction
- Overview of the Process
- Evaluating Web Application Behavior
- Creating the Initial Script
- Customizing the Script
- Testing the Script
- The Complete Solution
- Conclusion
|
Topics |
authentication, login, single sign-on, security, Web applications |
|
Products |
Novell SecureLogin 3.0 |
|
Audience |
network administrators, integrators, consultants |
|
Level |
beginner |
|
Prerequisite Skills |
familiarity with login security and Web applications |
|
Operating System |
n/a |
|
Tools |
none |
|
Sample Code |
yes |
Introduction
In today's computing environment, Web applications provide a cross-platform, clientless method of delivering information to corporate users. This information is sometimes sensitive, and therefore users must authenticate to Internet applications for access. As the demand for this type of application rapidly increases, users will have to remember more and more username/password combinations. But herein lies the dilemma. When users are forced to remember varying username and password combinations for each Internet site they access, they often write their credentials on calendars, on paper placed in a desk drawer, or on sticky notes hidden under the keyboard. Stringent password policies requiring special characters, non-repeating characters, and case-sensitive passwords characters add complexity, which often introduces a greater security risk due to the increased chance of human error. As a result, security is compromised.
The ideal solution for sites that require this added layer of security is to provide a method to automatically furnish the required credentials when prompted by the Web application, with the usernames and passwords being based on the users' initial network authentication. Such a solution is especially attractive if it provides policies that enforce stringent usernames and passwords, while reducing the total cost of ownership.
Novell's single sign-on solution, Novell SecureLogin, enables administrators to reduce the total cost of ownership normally incurred when adding applications to an environment that requires high levels of security. SecureLogin harnesses the power of Novell eDirectory through its use of inheritance in its corporate scripts. When placed near the top of the directory tree, these scripts provide instructions for a particular application that flow down to single sign-on enable all users below the Organization or Organizational Unit level.
SecureLogin enables administrators to set and enforce stringent password policies for the username ($Username) and password ($Password) variables. Thus you can enforce existing policies or quickly introduce new policies customized for each Internet page that requires authentication. This component-based solution includes the SecureLogin client, a scripting language, a Window Finder tool, and the Prolauncher and Terminal Launcher applications. The inclusion of these components provides a feature-rich solution for enabling a wide range of environments-from the simplest Windows or DOS-based applications to the most complex Citrix, mainframe emulation, and Telnet applications-to be enabled for single sign-on.
This AppNote introduces some of the key features of SecureLogin, including the SecureLogin client, the scripting language, and other tools, by looking at a real-world example scenario. The scenario is to single sign-on enable the authentication to MyRealBox, an Internet application that provides an e-mail account to users, much like Yahoo or HotMail. This scenario highlights many of the advantages of the SecureLogin solution.
Overview of the Process
The overall process of using SecureLogin to totally automate the authentication process of a Web application is outlined below.
Evaluate the behavior of the application. This involves the following items:
Identify the platforms (such as the Internet, Microsoft Windows, and so on) that are used by the application for entering user credentials.
Identify the initial authentication page for the application.
Determine whether a URL (or portion of the URL) is used to identify the individual Internet page or the entire Web site. If the URL identifies the entire site, you must identify some text that uniquely identifies the Internet page.
Determine if the URL is the same each time the page is displayed. If so, each URL can be used as a platform and be tied together with the "SetPlat" command. If the URL changes, the root portion of the URL must be used. When the root portion of the URL is used, each page is identified by some unique text on the page. This information is needed when setting up the initial script with the wizard.
Identify the Internet page and unique identification text or Windows dialog box that indicates the user has successfully authenticated to the application.
Identify the Internet page or Windows dialog box that indicates an unsuccessful attempt to authenticate to the application.
Identify the Internet page and unique identification text or Windows dialog box used to allow the user to change the password. Also determine if the user will need to access other information on this page.
Determine whether or not the application expires passwords, and if so, identify the page and process involved.
Determine whether or not the application revokes accounts, and if so, identify the page or dialog box presented and the message within the page or dialog box.
Generate an initial script using the SecureLogin wizard.
Customize the script generated by the SecureLogin wizard to include commands to handle incorrect initial password entry and to allow users to change their passwords once they have successfully authenticated to the application.
Test the script to ensure correct operation based on the application's features.
The remaining sections in this AppNote show how to perform each of these steps for the MyRealBox application scenario.
Evaluating Web Application Behavior
Due to certain behavior of Internet pages, it can be challenging to enable Web-based applications for single sign-on. Unique obstacles arise due to the use of frames, Java, or CGI scripting, and may require the use of the URL to identify the Internet page being displayed. Another obstacle is when an Internet page changes to a different page to display errors, without providing a place to enter user credentials. In this case, the user must change back to the original URL to re-enter the username and password. Additionally, some Web sites present a Windows message to indicate that incorrect credentials have been entered or to prompt the user to re-enter credentials. This presents a problem because the focus is switched to the message box and not returned to the original Internet page, and yet the two platforms must alter the same credential set.
To evaluate Web application behavior for SecureLogin purposes, you need to identify the following:
Entry points into an application that require credentials to be entered
Error or informational messages that need a response
Actions necessary to execute proper password changes
Application Entry Point
For MyRealBox, the application's initial entry point occurs when the user sets the browser to the http://www.myrealbox.com URL and the initial page shown in Figure 1 is launched.
Initial entry point for the MyRealBox application.
This page provides information to both prospective and current users, giving prospective users the opportunity to sign up for the new service and existing users a place to enter credentials. Users who already have MyRealBox accounts can enter their username and password and click the Logon button. After a successful authentication to the MyRealBox Internet service, the Internet page shown in Figure 2 is displayed.
Page displayed upon successful authentication to MyRealBox.
Incorrect Entry of Credentials
If the user incorrectly enters the credentials, the dialog box shown in Figure 3 is displayed.
Dialog box displayed for invalid credentials.
This is a Windows dialog box that prompts the user for the User Name and Password. Once these are typed in, the user clicks the OK button to present the new credentials to the application. This dialog box is displayed repeatedly until the user either enters the correct credentials or clicks the Cancel button.
Password Change Function
The password change function of the MyRealBox application may occur only after a user has successfully authenticated. To change the password, the user clicks the "Preferences" link from the MyRealBox page. The page shown in Figure 4 is then displayed.
Users can change theri MyRealBox passwords from this Preferences page.
In the Change Your Password portion of this page, users must enter their current password, type a new password, and type the new password again to verify that the passwords entered are the same. The user must then click "Apply" at the top right of the change password section of the page. If the user enters an incorrect password in the "Old Password" input box or the password entered into the "New Password" and "Retype Password" input boxes do not match, the application re-displays the dialog box shown in Figure 3 above.
This completes the evaluation of the MyRealBox application, as we have reviewed the entry point, the error or informational message when users enter invalid credentials, and the change password functionality. The following table lists the pertinent information we have gathered for the myrealbox.com application.
|
Platforms involved in completing the solution |
Internet, Windows |
|
URL used to identify the individual Internet page or the entire Web site |
myrealbox.com |
|
Text to uniquely identify the Internet page if the URL identifies the entire site |
"MRB Statistics" |
|
Text to indicate the user has successfully authenticated to the application |
none |
|
Internet page or dialog box that indicates an unsuccessful attempt to autenticate to the application |
Generic Windows dialog box with input boxes for credentials |
|
Internet page and unique identification text or Windows dialog box used to allow the user to change the password - also if the user will need to access other information on this page |
Page contains other user functions |
|
Determine if there is a need to script for revoked accounts |
Accounts are not revoked |
|
Determine if the application expires passwords |
Passwords are not expired |
Again, some Internet applications may have fewer things to consider, while others may have more, such as expired passwords or revoked accounts. If you are unfamiliar with these aspects of the application you are working with, gather the information from someone who is familiar with the application.
Creating the Initial Script
You use the SecureLogin wizard to create the initial script. The wizard captures the platform used and identifies the Web page presented. Using the wizard begins exactly like manually entering the credentials on the initial MyRealBox Web page that is presented when the user sets the browser to http://www.myrealbox.com.
Choosing the "Save" Option
After you enter the username and password and click the Logon button, SecureLogin recognizes that credentials have been entered and launches the dialog box shown in Figure 5.
The SecureLogin wizard's first dialog box.
This dialog box presents you with two options. When you choose the "Save for all pages at this web site" option, the URL for the Internet page is reduced to the portion of the URL that is common among all pages in the Web site (in our case, myrealbox.com). The "Save for only this page" option is applicable only when the URL is unique within the entire Web site and the URL remains constant each time the page is launched. This option causes SecureLogin to store the entire URL to identify the Internet page.
In MyRealBox, a portion of the URL following the base URL changes each time a user launches the initial Internet page. For example, the first time the initial page is opened the URL is:
http://www.myrealbox.com/a?AQAAAAEAAAAAAAAAAAAAAAAAAABj AAAASBMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
After the page is closed and opened again, the URL changes to: http://www.myrealbox.com/a?AQAAAAEAAAAAAAAAAAAAAAAAAACN AAAASBMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
(The two-character difference in the URLs is indicated in boldface type.) Because of the changing URL, the second option cannot be used to uniquely identify the Internet Page. So you should accept the first option and click "Yes" to continue. Before looking at that option, however, it is helpful to review what happens when you select the other command buttons:
No. If you choose "No", the application does not create a platform for the URL, create a script for the application, or store the credentials provided for the authentication to the application. The wizard also stops its execution. The next time the application is launched, the user is presented with the choices once again.
Never. Clicking "Never" causes SecureLogin to create a platform name for the entire Web site, create a script containing only a comment ("# do no login to this platform"), and then stop the execution of the wizard. Any time the Internet page or any page within the site is launched, this SecureLogin script runs. Since the script consists of only a comment, nothing happens.
Details. This option is described under "Viewing Details" below.
To view the default script created when you select "Never," right-click on the Secure Login icon found in the system tray and select "Manage logins" to see the dialog box shown in Figure 6.
SecureLogin's Manage Logins dialog box.
Choose the application name and click the Edit button to see the dialog box shown in Figure 7.
SecureLogin's Application dialog box.
Click on the Script tab to display the default script, as shown in Figure 8.
SecureLogin's default script when "Never" is chosen.
The "#" sign is used to denote a comment. This script means that any site having "myrealbox.com" in it will do nothing since its only command is a comment, which is ignored by the script processor. Although the script will execute each time an Internet page with "myrealbox.com" is launched, the user will not notice any delay.
Viewing Details
Going back to the Manage Logins dialog box (Figure 5), when you click on the Details >> button the dialog box in Figure 9 is displayed.
SecureLogin's Details dialog box.
This dialog box displays the URL SecureLogin will use to identify the application as a platform using the current settings. It also identifies the Username and uses asterisks to indicate that the password has been received. Should you desire to use a different URL to identify the application, click the down-arrow at the right of the URL box to display other choices as shown in Figure 10.
Selecting alternate URLs.
Since the URL for MyRealBox is not the same each time the Internet page is launched, the only other choice the wizard gives you for this application is "www.myrealbox.com". For this example, leave the default of "myrealbox.com" selected.
Accept the first option by clicking Yes to continue. Now the MyRealbox mail application will be launched with the user automatically authenticated to the MyRealBox site.
Reviewing the Generated Script
Review the SecureLogin application by right-clicking on the icon in the system tray and selecting the "Manage Logins" option. Notice that "myrealbox.com" is listed for the application. To view the script generated by the wizard for MyRealBox, highlight "myrealbox.com" in the list and click Edit. The dialog box in Figure 11 is displayed.
SecureLogin's Application dialog box with username filled in.
Click on the Script tab to display the script generated by SecureLogin (see Figure 12).
Generic script generated by the SecureLogin wizard.
The script shown here is a generic one without any custom features added. Here's what it does. When a URL is launched with "myrealbox.com" in it, the Secure- Login script will send the username stored in the $Username variable and the password stored in the $Password variable using the Type command. The "password" keyword that follows $Password tells SecureLogin to encrypt the password when displaying it to ensure that if the password is placed in a wrong field, security is not compromised.
This script enables SecureLogin to input the username and password into the Internet application for the user. Should a user initially enter an incorrect password, the default script will store this invalid password and present it each time the Internet page is launched. The user will then have to change the password within the SecureLogin application. To prevent the user from having to perform these steps and to handle other errors and future password changes, you will need to make customizations as described in the next section.
Customizing the Script
Because the script produced by the SecureLogin wizard provides no error checking, it will repeatedly provide the incorrect credentials if the user enters an incorrect password during the initial script creation. So the first step in customizing the script is to provide some error checking.
Handling Incorrect Password Entry
Start this script customization by identifying the initial page and setting the script to execute the commands only if this page is detected. This is done by identifying the URL and using it as a platform name, or by identifying text that is unique to the initial screen.
In MyRealBox, "MRB Statistics" is text that can be read from the initial page for identification. You can use this in an "if -text" script command as follows:
if -text "MRB Statistics" type $Username type $Password password endif
This amended script presents the dialog box in Figure 13 to the user when no user credentials exist.
Dialog box that prompts the user to enter Single Sign-on variables.
You can further enhance the script by adding control ID numbers to identify which input box the credentials should be placed into. Adding "#1" to the end of the "type $Username" command tells the script to place the username into the first input box found on the page. Likewise, "type $Password #2" tells the script to place the password in the second input box on the page. When using control IDs, you must use the "click" command to identify the proper button to execute. Thus, placing the command "click #1" after the "type $password #2" command tells the script to click on the first button (the OK button).
One last customization step is needed to complete this portion of the script. To change the generic prompt for the user to enter credentials to a more meaningful prompt for the application, use the "setprompt" command. This command is followed by the desired prompt text enclosed within quotation marks. By specifying "Please enter your MyRealBox credentials" in the "setprompt" command, you can have the script prompt the user for credentials when none exist and display display a customized prompt, as shown in Figure 14.
The same dialog box with a customized prompt.
The script customization so far is as follows:
if -text "MRB Statistics" type $Username #1 type $Password #2 click #1 setprompt "Please enter your MyRealBox credentials." endif
Now that you have customized the initial script to identify the initial Internet page and the presentation of the dialog box has been modified to capture the initial credentials, the next step is to identify the dialog box displayed should the user initially enter an incorrect password.
Using the Window Finder Tool
When a user enters an incorrect password, the Internet application presents the user with a Windows dialog box to allow the user a chance to enter the correct credentials. Figure 15 shows the Windows dialog box presented to the user when an incorrect password is entered in MyRealBox.
Dialog box displayed when an incorrect password is entered.
For Windows applications, Novell SecureLogin provides a "Window Finder" tool to uniquely identify a Windows dialog box. This tool provides information needed to identify the dialog box, input boxes, buttons, and any other text that the dialog box displays. It can be used to identify the site information, the username dialog box, the password dialog box, and the OK button within a dialog box.
To launch the Window Finder tool, click Start | Program Files | Novell Secure- Login | Window Finder. The dialog box shown in Figure 16 is displayed.
SecureLogin's Window Finder dialog box.
To use the tool, right-click the SecureLogin icon in the middle of this dialog box and drag the icon to the Windows dialog box you have open from your application. By varying the target area that is enclosed by the circular line, you can select a complete dialog box, an input box, or a label.
For MyRealBox, the information shown in Figure 17 is gathered by dragging the icon until the entire dialog box is selected.
Information gathered by selecting an entire dialog box.
Since this same dialog box is used for many applications, you can use the Window Finder to identify the exact location of the text via the dialog ID/control ID. This information will be read from the Windows dialog box to determine if it should be used for the MyRealBox application.
Dragging the SecureLogin icon over the "Site" text results in the captured information shown in Figure 18.
Information gathered by selecting an area of text.
You can also use the Window Finder tool to capture the dialog ID/control ID information to place text into an input box. For example, the information gathered for the "User Name" input box is shown in Figure 19.
Information gathered by selecting the "User Name" input box.
You can gather the dialog ID/control ID information from the Password input box in the same way, as shown in Figure 20.
Information gathered by selecting the "Password" input box.
Finally, you can capture the dialog ID/control ID information for the OK button, as shown in Figure 21.
Capturing the information for a button.
Windows dialog boxes are identified using the Windows titles and control ID numbers. The "Dialog" and "EndDialog" commands enclose the "Title" and "Ctrl" commands used to identify the Windows Title and control ID numbers respectively. The title for the Windows dialog box presented when the user enters an incorrect password is "Enter Network Password". The control IDs for the username and password are 1218 and 1219, respectively. The control ID of 1041 represents the site text "mail.myrealbox.com".
The following script commands identify the Windows dialog box:
Dialog Title "Enter Network Password" Ctrl "#1218" Ctrl "#1219" ctrl #1041 EndDialog
Using Control ID to Identify Applications
Again, the Windows dialog box used to prompt users to re-enter their credentials is a generic dialog box used by many applications. However, the dialog box does contain text that can identify the application using it. This text can be used to determine which application the Windows dialog box is representing. The text is obtained by reading the control ID number 1041 as determined above by the Window Finder tool. The script determines if the dialog box is to be acted upon using the following command:
readtext #1041 ?website
This command reads the text located by the dialog ID/control ID "1041" and stores this text into the temporary variable "?website". After this information is read from the dialog box, the script tests the value of the variable using an "if" statement to compare the temporary variable holding the text read from the dialog ID/control ID to "mail.myrealbox.com". If the values match, the user will be prompted to re-enter the credentials using the "DisplayVariables" command, and the script will pass the username and password data entered by the user to the username and password fields identified by dialog/control IDs 1218 and 1219, respectively. SecureLogin then clicks at dialog ID/control ID 1 to resubmit the credentials. Otherwise, the script is halted with the "EndScript" command.
The following script demonstrates this process:
if ?website eq "mail.myrealbox.com" displayvariables else endscript endif Type "$Username"#1218 Type "$Password"#1219 Click #1
Using the "SetPlat" Command
At this point two separate scripts exist: the Internet script which writes its credentials to the platform "myrealbox.com", and the Windows script which writes its credentials to "iexplore.exe". Since this is actually just one application, you need to unify the functioning of the scripts via the "setplat" command. This command should be the first command in the Internet script and the first command following the "enddialog" command in the Windows script.
The "setplat <"platform name">" command tells the script to use the credentials stored in the platform name. For this example, "myrealbox" is used as the platform name. The following command sets the platform to "myrealbox":
Setplat "myrealbox"
Password Change Scripting
The final step to complete the SecureLogin script customization is to add the change password functionality. In MyRealBox, the Internet page to change passwords is reached by clicking on the "Preferences" link after the user has successfully authenticated to the MyRealBox mail account (see Figure 22).
MyRealBox page for allowing users to change their passwords.
This Internet page allows users to perform tasks other than changing their password. Therefore, once the page is identified, the script should ask users if they want to change their password.
Since the URL/platform name for the application represents the entire site, you use the "if -text" command to identify the page. Again, it is necessary to choose text that does not exist on another Internet page. For example, you might choose "Old Password:" for the text, as shown below:
if -text "Old Password:" endif
Once the page is identified, you use the "MessageBox" command to inform the user by presenting a dialog box containing a message and an OK button. Or, in the case of MyRealBox, you can use the "-yesno" switch and a temporary variable like "?ans" to elicit a response from the user to determine if the user wants to change passwords or perform some other task. This response allows the script to determine how the user should navigate through the script.
The use of this command is demonstrated below:
messagebox "Would you like to change your password?" -yesno ?ans
The execution of this command presents the user with a dialog box containing the message "Would you like to change your password?" and Yes and No buttons, as shown in Figure 23.
Prompting the user to make sure they want to change the password.
In this case, the "MessageBox" command records the user's response in the temporary "?ans" variable. The script uses an "if" statement to determine the user's response by evaluating the value of the temporary variable as shown below:
if ?ans eq "no" endscript else type $Password #3 changepassword $Password type $Password #4 type $Password #5 submit endif
If the value of "?ans" is "no", the endscript command terminates the execution of the script so that the user will be able to perform other functions. Otherwise, the script will type the current MyRealBox password into the "Old Password" input box using the "type $Password #3" command. The script then executes the "changepassword" command, which is followed by a variable to act on. In this case, it is a permanent variable, $Password, and the dialog box in Figure 24 is presented to the user.
Dialog box presented for changing the user password.
Once the user enters and confirms the new password and clicks OK, SecureLogin will verify that the password typed in the "New Password" and "Confirm Password" input boxes are the same. The script will place the password into the "New Password" and "Re-Type Password" fields on the Internet page. It will then send the Tab and Enter keys to the Internet application via the "submit" command.
Note: The "submit" command is new to SecureLogin 3.x and was introduced to eliminate the need to Tab to a button to set the focus prior to sending the Enter key or Space Bar to execute.
Instead of a permanent variable, you could use a temporary variable such as ?Pass, thus allowing the script to determine if the user successfully authenticates to the application prior to changing the password. If this option is chosen, use the "Set" command (Set $Password ?Pass) to set the permanent password equal to the temporary password.
The entire script necessary to perform the password change is shown below:
if -text "Old Password:" messagebox "Would you like to change your password?" -yesno ?ans if ?ans eq "no" endscript else type $Password #3 changepassword $Password type $Password #4 type $Password #5 submit endif endif
Testing the Script
You should test SecureLogin scripts in a phased approach. The SecureLogin wizard generates the initial script; the other functions should be performed to determine if the script will place the credentials on an Internet page other than the one intended. These other functions may include invalid password entry, change password, expired password, or expired account pages. Following this approach ensures that the script only performs for the Internet page it is written for.
The MyRealBox application only needed testing for the change password Internet page. After the SecureLogin wizard created the initial script, this testing process revealed that the initial script places credentials on the change password Internet page. Therefore, it was necessary to use the "if -text" command to identify text unique to the initial page. Although this testing process may seem unnecessary for simple applications like MyRealBox, following this methodology ensures that a script accurately captures each Internet page or message even when tackling complex applications.
The Complete Solution
The complete solution for this application requires two scripts. The first (Internet) script identifies the initial Web page, stores the credentials into the SecretStore using the "myrealbox" platform, retrieves the credentials from the SecretStore using the "myrealbox" platform, delivers them to the application, and processes password changes. The second (Windows) script executes if the initial credentials entered by the user are incorrect, re-displaying the credentials so that the user can change them. The second script also stores the credentials into the SecretStore using the "myrealbox" platform. The complete scripts are shown below by platform name.
Myrealbox.com
setplat "myrealbox" if -text "MRB Statistics" type $Username #1 type $Password #2 click #1 setprompt "Please enter your MyRealBox credentials." endif if -text "Old Password:" messagebox "Would you like to change your password?" -yesno ?ans if ?ans eq "no" endscript else type $Password #3 changepassword $Password type $Password #4 type $Password #5 submit endif endif
IExplore.exe
Dialog Title "Enter Network Password" Ctrl "#1218" Ctrl "#1219" ctrl #1041 EndDialog Setplat "myrealbox" readtext #1041 ?website if ?website eq "mail.myrealbox.com" displayvariables else endscript endif Type "$Username"#1218 Type "$Password"#1219 Click #1
Conclusion
Novell SecureLogin provides a customizable suite of applications capable of securely enabling application for single sign-on in the most challenging of enterprise environments. The scripting language enables an organization to maintain a similar look and feel for all user messages throughout all applications, without sacrificing ease of management and security. Through the use of corporate scripts, SecureLogin creatively utilizes the inheritance of the directory to quickly distribute the solution to users within the organization. With unparalleled manageability, users can effortlessly access their data and securely manage their passwords. SecureLogin is an industry-leading software solution for multiple operating system environments and hardware platforms, yielding superior performance and easy administration for password administrators and less headaches and frustrations for users company-wide.
For Further Reference
For more information about Novell SecureLogin, visit the product home page at http://www.novell.com/products/securelogin.
Product documentation can be found in the \Docs\en directory of the product CD. The NSLADM30.PDF file contains additional information about installation and configuration, as well as a list of commands with a description of their functions.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.