9.1 Custom Scripts Plug-ins
9.1.3 Script Editor
The Script Editor window is made up of four parts:
A toolbar.
An actions list.
A dynamic panel allowing you to edit selected action parameters.
The OK and Cancel buttons. The actions list has three columns:
The actions.
The execution condition (or state).
The actions parameters.
9.1.3.1 Script Editor Toolbar
The toolbar allows you to create new actions, modify their execution conditions, and move actions.
ICON DESCRIPTION
Create a new action placed after the first selected action
Delete one or several action(s) Move up one (or several) action(s) Move down one (or several) action(s)
ICON DESCRIPTION
Modify the execution condition to Execute if True
Modify the execution condition to Execute if False
9.1.3.2 Script Editor Actions
The action creation icon in the toolbar displays a menu with a list of all the available actions. The table below summarizes the available actions, showing the correspondence between the two types of plug-ins (Custom Script and Custom Script HTML).
ICON CUSTOM SCRIPT CUSTOM SCRIPT HTML
Send Key/String Send String to Form Field Send SSO
parameter
Send SSO Parameter to a field
Send Command Message
Not Available.
Send a JavaScript Send a JavaScript
Get Control Text Get Field Text
Get SSO parameter Get SSO parameter
Click Button Send an HTML event
Select Item in list Select Item in an HTML List Call External
Function
Call External Function
Sleep Sleep
Compare Compare
Return Return
Special Event Special Event
Create a Label Create a Label Jump to Label
(Goto)
Jump to Label (Goto)
Display a message box
ICON CUSTOM SCRIPT CUSTOM SCRIPT HTML
Input box Input box Check certificate Check certificate
The rest of this subsection describes the different actions; each action description is introduced by a table summarizing its main characteristics:
The action’s name and its icon.
Properties associated with the action.
Information as to whether or not the action modifies the buffer and/or state.
[ICON] ACTION NAME
Modify state
Modify buffer
Description
Send Key/String (Custom Script only)
Modify state
Send Key/String (Custom Script only)
This action allows you to send characters (keyboard keys or strings) to a target window (the window being the primary, active window) or to a target control field/button in a window.
In the Target area, it is strongly recommended to select Send to the Control
(use the target icon button to select the control field). If it is not possible, that is if the window has no control fields or buttons it is better to select Send to the Window than Focused Window. Then, if necessary, modify the sending method (it is recommended to use the Automatic method. If it does not work, try another method depending on your application).
In the Send Key/String area, define the characters you want to send in the target window:
Select Key to send keyboard keys, as Enter, Tab, SHIFT+Tab, Space, Escape for example.
To send an additional key, select None, Shift, Alt, or Control from the Additional key dropdown list.
Select String and fill in the field to send a specific string.
Select Buffer to send the memory buffer content.
Send String to Form Field (Custom Script HTML only)
Modify state
Modify buffer
This action allows you to send strings to a target form field in an HTML page. In the Target area, use the HTML target button to fill in the field (the HTML page containing the target form field must be displayed).
In the Send Key/String area, define the string you want to send in the target HTML form field:
Select Buffer content to send the memory buffer content.
Send SSO Parameter (Custom Script only)
Modify state
Modify buffer
This action allows you to send an SSO parameter of a user account to a target window (the window being the primary, active window) or to a target control field/button in a window.
For details on the Target area, please see the Send Key/String action above. In the Parameter to Send area, define the SSO parameter you want to send:
Identifier: the user identifier for the current application.
Password: the associated password of the user identifier.
New Password: a new password. In this case, the window is considered to be a NewPassword window type.
Confirm Password: the confirmation of the new password. In this case, the window is considered to be a ConfirmPassword window type.
Custom Parameter: to activate this option, you must define a parameter at the Application level (for details, see Section 3.6.2.5, ""Parameters" Tab").
Do not prompt for user account: you can select this option if the user has several accounts.
The transmitted SSO parameter is copied to the memory buffer.
Send Command Message (Custom Script only)
Modify state
Modify buffer
Read carefully the instructions written in the Send command message area.
Send a JavaScript
Modify state
This action enables you to send a JavaScript if the address bar is displayed in Internet Explorer, Firefox and Chrome.
Send an HTML event (Custom Script HTML only)
Modify state
Sends an event (navigation, button click, item to be checked or execution of a JavaScript) to the active HTML browser)
This action is particularly useful if you want to execute JavaScript code.
Get Control Text (Custom Script only)
Modify state
Modify buffer
This action reads the text contained in a targeted control field. The recovered text is also copied to the memory buffer.
Get SSO Parameter (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action retrieves the value of an SSO parameter of a user account
(identifier, password…) and copies it to the memory buffer. For a description of the options, see the Send SSO Parameter action above.
Click Button (Custom Script only)
Modify state
Modify buffer
This action allows you to simulate a mouse click on:
A targeted button or on a targeted check box;
Any specific field in the window.
Select the Perform double click check box if you want to enable double click to select the value of a field.
If you have targeted a check box, do not forget to select Change the button state and click either Check or Uncheck depending on your needs.
Select Item in List (Custom Script) or Select Item in an HTML List (Custom Script HTML)
Depending on the selected Selection Mode, the interface of this window is slightly different:
By Item Number:
By Parameter:
By Item Label:
Modify state
Modify buffer
This action allows you to select an element from a list. The list must be targeted with the target icon. The supported list types are:
ListBox.
ComboBox.
ComboBoxEx32.
The selection can be performed by:
Item Number: the element number (position) to select, 0 being the first.
Parameter: the parameter is defined at the Application level (for details, see Section 3.6.2.5, ""Parameters" Tab".
Call External function (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action allows you to call a function in an external DLL.
Click the Search button to choose the DLL.
Enter the function name in the Function field. If the function is found in the DLL, the indicator turns green. Otherwise, it remains red.
When SSO is implemented, the DLL will first be looked for in the PATH associated with the connected user’s environment. If it is not found, it will be looked for in the same directory as the one used during the configuration process.
For more details on how to write external procedures, see Extension DLL.
Sleep (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action suspends SSOWatch for the time specified (in milliseconds). Two buttons (500 ms and 1000 ms) allow you to quickly configure the most common wait times.
Compare (Custom Script and Custom Script HTML)
Modify state
Compare (Custom Script and Custom Script HTML)
This action compares the memory buffer contents with a given character string. The comparison is case sensitive.
The state is then modified, depending on the result of this comparison – True if the string is found, False otherwise.
Check certificate (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action enables you to check the SSL certificate of a web server before performing the SSO. The check is done by comparing the web server certificate with a local certificate
You must provide the following information:
The web server where to download the certificate from.
The location of the local certificate.
Return (Custom Script and Custom Script HTML)
Modify state
Return (Custom Script and Custom Script HTML)
You must use Return actions to stop the script. It returns one of the following status:
OK: no problem.
SSO Done: the identifier and/or password or parameters have been successfully sent to the application. This stop code should be used in all the custom scripts that use the Send SSO Parameter function (identifier, password).
Disable the Window: SSOWatch ignores the window.
Disable the Application: SSOWatch ignores the application.
Special Event (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action allows you to trigger one of the events listed in the Special Event area.
The Resynchronize user password event allows you to display the SSOWatch Change Password window, which allows you to change also the user's login.
Create a Label (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action allows you to create a label in the custom script, to manage
conditional operations. You must use this action if you want to use the Jump to Label (Goto) action.
Jump to label (Goto) (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action is only available if you have already defined a Create a Label action. It allows you to define a jump in your custom script. It is strongly
recommended to use this action in association with a condition (True/False), to avoid infinite loops.
Display a message box (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action allows you to display a message box in order to ask a question to the user. Use the available options to define the content of your message box. If the user can click No or Cancel, the state is set to False.
Click the Buffer content radio button to enable the user to see the content of the buffer. This feature enables the user to see his login and password.
You can use this action to check if a window is detected or to check that the return code of an external function is OK, in order to adjust a Custom Script.
Input box (Custom Script and Custom Script HTML)
Modify state
Modify buffer
This action allows you to define an input box. Select Allow value selection from list or combobox if you prefer to display a list of items the user can select rather than a standard input field where he can enter any text.
Extension DLL
The DLL enables you to perform the integration of an application with the SSO where the other methods have failed. This means creating a specific SSO agent for a specific application; which requires programing skills.
A SSOWatch extension library sample can be found in the SSOWatch package (CustomDllSample)
To be included in an Enterprise SSO script, an external function must respect the following rules:
It must publish a C interface.
It must accept a single parameter that is a pointer to a SSOWatchSSOData data structure.
It must return a specific return code.
It must be able to read and modify the memory buffer.
It must be able to read and modify the current state.
It must not modify other fields that are read only in the SSOWatchSSOData structure.
All these elements are defined in the C/C++ header files SSOWatchSSOData.h and SSOWatchWindows.h.
Function Prototyping
An external function must use the prototype:
extern « C » DWORD (*)(SSOWatchSSOData *)
SSOWatchSSOData Structure
The following structure defines the SSOWatchSSOData structure provided as a parameter to the external function. This structure contains the data that is carried from one action to another:
int m_nVersion; // R BOOL m_bState; // RW HWND m_hWnd; // R TCHAR m_szBuffer[SSOWATCHSSODATA_BUFFERLEN+1];// RW TCHAR m_szIdentifier[SSOWATCHSSODATA_IDLEN+1];// R TCHAR m_szPassword[SSOWATCHSSODATA_PWDLEN+1]; // R TCHAR m_szParam[SSOWATCHSSODATA_PARAMLEN+1]; // R LPCTSTR m_szCredential; // R void *m_UserData; // RW void *m_pInternal; // -- void *m_pInternalCred; // -- void *m_pIternalInstance; // -- };
The version number (m_nVersion) indicates the version of this structure. It can change between versions of SSOWatch It must be compared to
SSOWATCHSSODATA_VERSION.
The state (m_bState) indicates the state of the last action (TRUE or FALSE) and can be modified to change the execution of the next actions.
m_hWnd contains the handle of the currently processed window. It should not be modified. It can be used to call Win 32 functions that need a window handle as a parameter.
m_szBuffer is the memory buffer. It can be modified if required.
m_szCredential, m_szIdentifier and m_szPassword respectively contain the name of the service associated with the application being processed, and the identifier and password of the user for this service. These parameters should not be modified. m_szParam
contains the last SSO Parameter retrieved with the "Get SSO" action. None of these fields should be modified.
m_szCredential contains a string in the form: Account="…"
m_UserData is a pointer to custom user data, and is not used by SSOWatch (except of course by external functions). It remains valid during the entire execution of the same script
The members: m_pInternal, m_pInternalCred and m_pInternalInstance should not be modified. There are reserved for internal use by SSOWatch.
Return Code
The function must return a code that is a combination of one of the values in the following table together with the code SSORET_STOP if the script must be stopped.
CODE DESCRIPTION
CODE DESCRIPTION
SSORET_SSODONE The function ended with no error and SSO has been done.
SSORET_PASSWORDERROR An error occurred during password management.
SSORET_NOREGISTRATION The user is not registered for the application. SSORET_PARAMETERERROR An error occurred during the recovery of an
SSO parameter.
SSORET_WRONGWINDOWSEQUENCE This window should not have been processed in this context (for example, bad password window found before the logon window). SSORET_SSOALREADYDONE SSO has already been executed for this
window.
SSORET_WAITFORPASSWORDCHANGE The application is waiting for a confirmation of password update.
SSORET_PASSWORDCHANGED The password has been changed. SSORET_REMOTEERROR An error occurred during access to the
security database.
SSORET_WINDOWERROR An error occurred while the current window was being processed – the window will be disabled.
SSORET_APPLICATIONERROR An error occurred while the current application was being processed – the entire application will be disabled.
SSORET_USERCANCELLED_ INSTANCE
User has disabled SSO for this application instance.
SSORET_USERCANCELLED_ APPLICATION
10 OLE/Automation Interface
For some specific applications like line terminal emulators, or applications that cannot be configured with any of the SSOWatch window types, SSOWatch provides an
OLE/Automation interface.
SSOWatch behaves like a COM server and accepts calls from several clients. These clients connect with the COM protocol, or use high-level programming languages like Visual Basic, or any language that supports this kind of programming interface (most terminal emulators like Hummingbird Exceed or AttachMate Extra do). You may also use this interface from any C/C++ program.
Clients connecting to SSOWatch use the active SSOWatch configuration and benefit from SSOWatch application behavior management and password policies.
By default, access to SSOWatch objects using OLE/Automation interface is forbidden. You have to explicitly authorize this action in the general options of the application object. For security reasons, you must specify a password in the configuration to protect access.