Terminal Type Applications

Terminal Type Applications

Terminal type windows manage SSO in text fields emulating a line mode terminal. The terminal must be displayed in a text-edit control field.

NOTE: Some emulator windows may not meet this requirement. In this case, the use of other methods like OLE/Automation interface access is necessary.

The way this window type works is slightly different from the way other window types work, since the SSO events correspond to the display of messages; in addition, all the SSO states are managed in the same window.

Once the connection has been set up, SSO is disabled for this window.

Two window types offer the management of terminals:

• Terminal (from Standard plug-in).
• MSTelnetW2KXP (from Microsoft applications plug-in).

NOTE: Enterprise SSO also works with PUTTY.

The detection of these window types is the same as for the Windows type.

However, the Actions part covers all standard window types: it is used to manage the opening of a full session (including bad and new passwords management) running in text mode and in a single Windows control field (usually an Edit field). It simulates the user keyboard entries and controls the state of the connection status by detecting text banners.

In this section:

• Terminal
• Microsoft TelnetW2KXP
• Banners

Terminal

This window type has been created to manage the terminal connections in Edit fields, especially the Windows remote access pre- and post- dial-up terminals.

Its configuration window is the following:

The Host Control field must contain the whole text used for connection. Using the target icon, click the terminal window; this will copy the text across.

The behavior regarding the text banners is defined by clicking on the Banners button (see Banners).

If you have difficulties or if you want to optimize the processing, you can also set up the timing between two searches for banners.

Once SSO has been performed, or in case of failure, it is possible to click a button to close the window. Using the target icon, click the terminal window; this will copy the button across.

Microsoft TelnetW2KXP

Two window types are available for managing the Microsoft TelnetW2KXP application:

 

Window Type	Description
MSTelnetW2KXP	Telnet Microsoft for Windows 2000 and XP OS
MSTelnet	Obsolete for compatibility purpose

Its configuration window is the following:

If you have difficulties or if you want to optimize the processing, you can also change the performance-tuning parameters:

• The timer between the detection of two banners.
• The timeout canceling the SSO for the window.

Banners

The banners configuration window is the following:

This window allows you to specify SSO events (the detection of text in a new text line) and the behavior to be associated with them.

The possible behaviors are:

 

Event	Description
Identifier	The text indicates a username request.
Password	The text indicates a password request.
Custom Parameter	An additional parameter is requested.
Connection OK	The text indicates that the connection is successful. It stops the SSO.
Enter new password	The text indicates that a new password is requested.
Confirm new password	The text indicates that the same new password must be confirmed.
Bad password	The text indicates that there is a wrong password in the security database.
Connection refused	The text indicates that the connection failed. It stops the SSO.
Do not press Enter key if the value is greater than...	Defines the number of characters above which the Enter key is not sent. If the value is 0, the Enter key is never sent.

To add an event, you must:

• Indicate the text to look for in the Banner field.
• Select the associated event.
• Click the Add button.

To edit an event, you must:

• Select it in the list.
• Click the Edit button: it will disappear, and the information is displayed in the bottom fields.
• Edit the information.
• Click the Add button: the information is then added at the bottom of the list.

To delete an event, you must:

• Select it in the list, click the Delete button.

The HLLAPI Plug-in

The HLLAPI Plug-in

Subject

This section describes how to enable SSO or account collect (in Access Collector mode) for applications using HLLAPI.

HLLAPI Definition

The HLLAPI (High Level Language Application Program Interface) is an IBM API that allows a PC application to communicate with a mainframe computer. HLLAPI requires a PC to run a 3270 emulation software and then defines an interface between a PC application and the emulation software.

IMPORTANT: In the next sections, the term "HLLAPI applications" designates the applications that are using HLLAPI.

In this section:

• Configuring the HLLAPI Plug-in
• Enabling SSO for HLLAPI Applications
• HLLAPI Application Keys

Configuring the HLLAPI Plug-in

If the default configuration parameters used to implement the HLLAPI plug-in are not working with your HLLAPI application, or if you want to configure Single Sign-On for different types of HLLAPI applications installed on the same workstation, you must modify keys and values in the Windows Registry to fit your requirements.

IMPORTANT: Modifying the Windows Registry may damage your Windows system. It is strongly recommended to be accommodated with the Registry Editor to modify keys and values

In this section:

• Configuring the HLLAPI Plug-in for a Single Application
• Configuring the HLLAPI Plug-in for Different Types of Applications
• HLLAPI Plug-in Registry Keys

Configuring the HLLAPI Plug-in for a Single Application

 

1. Start the Registry Editor and add the HLLAPI key in HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch
2. Add the values detailed in HLLAPI Plug-in Registry Keys depending on your requirements.

NOTE: It is not mandatory to set all the values listed in "HLLAPI Plug-in Registry Keys". If a value is not set, the default value data is used.

Configuring the HLLAPI Plug-in for Different Types of Applications

 

1. Start the Registry Editor and add the HLLAPI key in HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch
2. Create the following value:

 

Value name	EnableMultiEmulator
Description	Enables/disables the management of different types of HLLAPI applications on the same workstation.
Type	REG_DWORD
Value data	0: disabled. 1: enabled.
Location	HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI

3. Add as many sub-keys as there are types of applications in HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HLLAPI.

   Example: to add Attachmate EXTRA! and Rumba terminal emulation applications, you can create the following sub-keys:

   HKLM\SOFTWARE\Enatel\SSOWatch\HLLAPI\Attachmate EXTRA!

   HKLM\SOFTWARE\Enatel\SSOWatch\HLLAPI\Rumba

4. Add in each sub-key the values detailed in HLLAPI Plug-in Registry Keys depending on your requirements.

   Example:

   [HKLM\SOFTWARE\Enatel\SSOWatch\HLLAPI\Attachmate EXTRA!]

   "HllLibrary"="C:\\Program Files\\Attachmate\\E!E2K\\ehlapi32.dll"

   "HllEntryPoint"="hllapi"

   "HLLAPI-32bit"=dword:00000000

   HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HLLAPI\Rumba

   "HllEntryPoint"="hllapi"

   "HllLibrary"="D:\\Program Files\\NetManage\\RUMBA\\System\\ehlapi32.Dll"

   "HLLAPI-32bit"=dword:00000001

   "IgnoreWindowsHandle"=dword:00000001

   "UseTitleInDetection"=dword:00000001

 

HLLAPI Plug-in Registry Keys

NOTE: If the EnableMultiEmulator key is set to 1 (see Configuring the HLLAPI Plug-in for Different Types of Applications), the registry keys listed in this section that are located directly under HKLM\SOFTWARE\Enatel\SSOWatch\HllAPI are ignored.

 

Value name	EnableMultiEmulator
Description	Enables/disables the management of different types of HLLAPI applications on the same workstation.
Type	REG_DWORD
Value data	0: disabled. 1: enabled.
Location	HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI

 

Value name	HllLibrary
Description	DLL file that must be used by the HLLAPI plug-in. IMPORTANT: If the EnableMultiEmulator key is set to 1, this value must be set (no default value allowed).Replace this text with a notation that requires the reader's attention.
Type	REG_SZ
Value data	Pathname of the .DLL file. Default value: PCSHLL32.dll
Location	Single application: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI Multi applications: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI\<App. Name>, where <App. Name> is the name of the HLLAPI application.

 

Value name	HllEntryPoint
Description	Name of the HLLAPI function in the DLL file. IMPORTANT: EnableMultiEmulator key is set to 1, this value must be set (no default value allowed).
Type	REG_SZ
Value data	Default value: hllapi
Location	Single application: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI Multi applications: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI\<App. Name>, where <App. Name> is the name of the HLLAPI application.

 

Value name	HLLAPI-32bit
Description	Specifies that the HLLAPI application is a 32-bit application. IMPORTANT: If the EnableMultiEmulator key is set to 1, this value must be set (no default value allowed).
Type	REG_DWORD
Value data	1 (default): 32-bit application 0: 16-bit application
Location	Single application: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI Multi applications: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI\<App. Name>, where <App. Name> is the name of the HLLAPI application.

 

Value name	IgnoreWindowsHandle
Description	Allows Enterprise SSO to support HLLAPI libraries which are not able to return Windows handle properly.
Type	REG_DWORD
Value data	1: enabled. 0 (default): disabled.
Location	Single application: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI Multi applications: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI\<App. Name>, where <App. Name> is the name of the HLLAPI application.

 

Value name	UseTitleInDetection
Description	Allows the Enterprise SSO engine to detect the title of the HLLAPI application.
Type	REG_DWORD
Value data	1 (default): enabled (displays the Title check button in the Detection tab. For more details, see The Detection Tab). 0: disabled.
Location	Single application: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI Multi applications: HKEY_LOCAL_MACHINE\SOFTWARE\Enatel\SSOWatch\HllAPI\<App. Name>, where <App. Name> is the name of the HLLAPI application.

Enabling SSO for HLLAPI Applications

Subject

To enable SSO for HLLAPI applications, you must declare the application in the Enterprise SSO configuration and define the window types that must be detected by Enterprise SSO, as described in the following procedure.

Before starting

• Your emulation software must be configured to establish connections through HLLAPI.
• Check that the global configuration parameters used to implement the HLLAPI plug-in are correctly set (as described in Configuring the HLLAPI Plug-in ).

Procedure

1. In ESSO Enterprise Studio, create a new Application.

   The Application object appears under the Applications node.

2. Right-click the Application object and select New Window.

   The Window Properties window appears.

3. Fill-in the General tab with the following guideline: in the Window Type drop down list, define one of the following screens:
   • HLLAPI Login: login screen of the HLLAPI application.
   • HLLAPI Bad Password: screen indicating a wrong password/username.
   • HLLAPI New Password: screen requesting a new password (this screen can be a specific screen or the login screen. Not available in Access Collector mode).
   • HLLAPI Standard: screen that does not need any authentication data (not available in Access Collector mode).
   • HLLAPI Confirm Password: new password confirmation screen (not available in Access Collector mode).
   • HLLAPI Bad New Password: screen indicating that the new password in not correct (not available in Access Collector mode).
4. If necessary, fill-in the Options tab.

   IMPORTANT: If you are defining an HLLAPI New Password screen, and if the new password must be provided in the login screen, then select Use Manual SSO State Conditions, click Configure and select SSO has been done. Password has expired and must be changed.

5. Fill-in the Detection tab: see The Detection Tab.
6. Fill-in the Actions tab: see The Actions Tab.
7. Click the OK button.

   The Window object appears under the Application object.

8. To define other HLLAPI window types, restart from Step 2.

 

In this section:

• The Detection Tab
• The Actions Tab

The Detection Tab

Subject

The section gives information on how to fill-in the Detection tab for HLLAPI window types. This tab allows you to define the screen requirements to enable SSO.

Description

• The Connection Type area:

  This area allows you to specify the communication standard used by the application.

IMPORTANT: If the connection type information is not available at HLLAPI level, Enterprise SSO does not take into account this parameter.If you do not know the connection type, select or clear all check boxes.

• The Strings to Detect area:

  You must fill-in this area to define the strings that Enterprise SSO must detect to enable SSO. Read carefully the following guidelines:

  • Enter the name of a string to detect.
  • Absence of: select this check box to specify that the string must not appear in the application window.
  • Position area: fill in this area to specify the position of the string to detect in the application window:
  • Select Check Position.
  • Define the row and column numbers of the string.
  • Select Relative Coordinates if you want to specify a position relative to the position of the cursor.
  • Click the Title check button to enter a part of the title of the window to be detected so that SSO is performed on the emulator.

  NOTE: This button is displayed only if the UseTitleInDetection key has been positioned. For more information, see Configuring the HLLAPI Plug-in . Not all emulators enable you to retrieve the title name of the window.

  • Click Add.

Example

 

In this example, Enterprise SSO enables SSO if:

• The Account Name string is located in the application window on the same row as the cursor (relative coordinates) and 14 columns before.
• The Password string does not appear in the application window.

The Actions Tab

Subject

The section gives information on how to fill-in the Actions tab for HLLAPI window types. This tab allows you to define the authentication data that Enterprise SSO must send to the terminal emulator.

Description

• The SSO Steps area:

This area allows you to sort and modify the actions that must be performed by Enterprise SSO in the terminal emulator window.

• The Actions area:

  This area allows you to define the data that Enterprise SSO must send to the terminal emulator. Fill-in the window as follows:

  • Send SSO parameter: select this option if you want to send an SSO parameter, and select in the drop down list the wanted entry.
  • Send Key: select this option if you want to send a "common" key (as <enter> for example), and select the wanted key in the drop down list.
  • Send if previous parameter shorter than: (activated only when the <tab> key is selected) when you select this check box, a tab is sent if the parameter is smaller than the number of characters you enter in the text field.
  • Send Text: select this option either if you want to send a key that does not appear in the Send Key drop down list, or if you want to enter another text to send. Enter the text in the corresponding field.

    NOTE: For more information on the list of keys that are compatible with many emulator software applications, see HLLAPI Application Keys .

  • Once by instance: (appears only with the HLLAPI Standard window type). Select this check box if you want to specify that Enterprise SSO must carry out the actions listed in the SSO Steps area only one time per session instance. You can use this option to send further actions upon the detection of HLLAPI screens other than the HLLAPI screen types listed in the General tab.
  • The Other button: if the actions listed above do not meet your requirements, you can define extended actions, by clicking the Other button.

    The following window appears:

    

    Fill-in this window as follows:

  • Sleep: select this option to suspend Enterprise SSO for a specified time before processing the next displayed action in the SSO Steps area.
  • Exit DLL: select this option to call a function in an external DLL. If the function is found in the DLL, the indicator turns green.

    NOTE: When SSO is implemented, the DLL is searched in the directory defined in the %PATH% environment variable of the user who is logged on If it is not found, the DLL is searched in the same directory as the one used during the configuration process.For more details on external DLL, see Extension DLL.

  • Set cursor: select and define this option to set the cursor in a specific area of a window.

• Do not prompt for user account: when you select this check box, if a user reconnects to an application and has several accounts, it is the active account that is automatically used.

HLLAPI Application Keys

The following table lists the keys that are compatible with many emulator software applications.

 

Mnemonic	Meaning	3270	5250	VT
@B	Left Tab	Yes	Yes	No
@C	Clear	Yes	Yes	No
@D	Delete	Yes	Yes	No
@E	Enter	Yes	Yes	No
@F	Erase EOF	Yes	Yes	No
@H	Help	No	Yes	No
@I	Insert	Yes	Yes	No
@J	Jump (SetFocus)	Yes	Yes	No
@L	Cursor Left	Yes	Yes	Yes
@N	New Line	Yes	Yes	Yes
@O	Space	Yes	Yes	Yes
@P	Print	Yes	Yes	Yes
@R	Reset	Yes	Yes	No
@T	Right Tab	Yes	Yes	Yes
@U	Cursor Up	Yes	Yes	Yes
@V	Cursor Down	Yes	Yes	Yes
@X*	DBCS (Reserved)	Yes	Yes	No
@Y	Caps Lock (No action)	Yes	Yes	No
@Z	Cursor Right	Yes	Yes	Yes
@0	Home	Yes	Yes	No
@1	PF1/F1	Yes	Yes	No
@2	PF2/F2	Yes	Yes	No
@3	PF3/F3	Yes	Yes	No
@4	PF4/F4	Yes	Yes	No
@5	PF5/F5	Yes	Yes	No
@6	PF6/F6	Yes	Yes	Yes
@7	PF7/F7	Yes	Yes	Yes
@8	PF8/F8	Yes	Yes	Yes
@9	PF9/F9	Yes	Yes	Yes
@a	PF10/F10	Yes	Yes	Yes
@b	PF11/F11	Yes	Yes	Yes
@c	PF12/F12	Yes	Yes	Yes
@d	PF13	Yes	Yes	Yes
@e	PF14	Yes	Yes	Yes
@f	PF15	Yes	Yes	Yes
@g	PF16	Yes	Yes	Yes
@h	PF17	Yes	Yes	Yes
@i	PF18	Yes	Yes	Yes
@j	PF19	Yes	Yes	Yes
@k	PF20	Yes	Yes	Yes
@l	PF21	Yes	Yes	No
@m	PF22	Yes	Yes	No
@n	PF23	Yes	Yes	No
@o	PF24	Yes	Yes	No
@q	End	Yes	Yes	No
@s	ScrLk (No action)	Yes	Yes	Yes
@t	Num Lock (No action)	Yes	Yes	Yes
@u	Page Up	No	Yes	No
@v	Page Down	No	Yes	No
@x	PA1	Yes	Yes	No
@y	PA2	Yes	Yes	No
@z	PA3	Yes	Yes	No
@A@C	Test	No	Yes	No
@A@D	Word Delete	Yes	Yes	No
@A@E	Field Exit	Yes	Yes	No
@A@F	Erase Input	Yes	Yes	No
@A@H	System Request	Yes	Yes	No
@A@I	Insert Toggle	Yes	Yes	No
@A@J	Cursor Select	Yes	Yes	No
@A@L	Cursor Left Fast	Yes	Yes	No
@A@Q	Attention	Yes	Yes	No
@A@R	Device Cancel (Cancels Print Presentation Space)	Yes	Yes	No
@A@T	Print Presentation Space	Yes	Yes	Yes
@A@U	Cursor Up Fast	Yes	Yes	No
@A@V	Cursor Down Fast	Yes	Yes	No
@A@Z	Cursor Right Fast	Yes	Yes	No
@A@9	Reverse Video	Yes	Yes	No
@A@b	Underscore	Yes	No	No
@A@c	Reset Reverse Video	Yes	No	No
@A@d	Red	Yes	No	No
@A@e	Pink	Yes	No	No
@A@f	Green	Yes	No	No
@A@g	Yellow	Yes	No	No
@A@h	Blue	Yes	No	No
@A@i	Turquoise	Yes	No	No
@A@j	White	Yes	No	No
@A@l	Reset Host Colors	Yes	No	No
@A@t	Print (Personal Computer)	Yes	Yes	No
@A@y	Forward Word Tab	Yes	Yes	No
@A@z	Backward Word Tab	Yes	Yes	No
@A@−	Field −	No	Yes	No
@A@+	Field +	No	Yes	No
@A@<	Record Backspace	No	Yes	No
@S@E	Print Presentation Space on Host	No	Yes	No
@S@x	Dup	Yes	Yes	No
@S@y	Field Mark	Yes	Yes	No
@X@1	Display SO/SI	Yes	Yes	No
@X@5	Generate SO/SI	No	Yes	No
@X@6	Display Attribute	No	Yes	No
@X@7	Forward Character	No	Yes	No
@X@c	Split vertical bar (¦)	No	Yes	No
@M@0	VT Numeric Pad 0	No	No	Yes
@M@1	VT Numeric Pad 1	No	No	Yes
@M@2	VT Numeric Pad 2	No	No	Yes
@M@3	VT Numeric Pad 3	No	No	Yes
@M@4	VT Numeric Pad 4	No	No	Yes
@M@5	VT Numeric Pad 5	No	No	Yes
@M@6	VT Numeric Pad 6	No	No	Yes
@M@7	VT Numeric Pad 7	No	No	Yes
@M@8	VT Numeric Pad 8	No	No	Yes
@M@9	VT Numeric Pad 9	No	No	Yes
@M@-	VT Numeric Pad -	No	No	Yes
@M@,	VT Numeric Pad ,	No	No	Yes
@M@.	VT Numeric Pad .	No	No	Yes
@M@e	VT Numeric Pad Enter	No	No	Yes
@M@f	VT Edit Find	No	No	Yes
@M@i	VT Edit Insert	No	No	Yes
@M@r	VT Edit Remove	No	No	Yes
@M@s	VT Edit Select	No	No	Yes
@M@p	VT Edit Previous Screen	No	No	Yes
@M@n	VT Edit Next Screen	No	No	Yes
@M@a	VT PF1	No	No	Yes
@M@b	VT PF2	No	No	Yes
@M@c	VT PF3	No	No	Yes
@M@d	VT PF4	No	No	Yes
@M@h	VT HOld Screen	No	No	Yes
@M@(space)	Control Code NUL	No	No	Yes
@M@A	Control Code SOH	No	No	Yes
@M@B	Control Code STX	No	No	Yes
@M@C	Control Code ETX	No	No	Yes
@M@D	Control Code EOT	No	No	Yes
@M@E	Control Code ENQ	No	No	Yes
@M@F	Control Code ACK	No	No	Yes
@M@G	Control Code BEL	No	No	Yes
@M@H	Control Code BS	No	No	Yes
@M@I	Control Code HT	No	No	Yes
@M@J	Control Code LF	No	No	Yes
@M@K	Control Code VT	No	No	Yes
@M@L	Control Code FF	No	No	Yes
@M@M	Control Code CR	No	No	Yes
@M@N	Control Code SO	No	No	Yes
@M@O	Control Code SI	No	No	Yes
@M@P	Control Code DLE	No	No	Yes
@M@Q	Control Code DC1	No	No	Yes
@M@R	Control Code DC2	No	No	Yes
@M@S	Control Code DC3	No	No	Yes
@M@T	Control Code DC4	No	No	Yes
@M@U	Control Code NAK	No	No	Yes
@M@V	Control Code SYN	No	No	Yes
@M@W	Control Code ETB	No	No	Yes
@M@X	Control Code CAN	No	No	Yes
@M@Y	Control Code EM	No	No	Yes
@M@Z	Control Code SUB	No	No	Yes
@M@u	Control Code ESC	No	No	Yes
@M@v	Control Code FS	No	No	Yes
@M@w	Control Code GS	No	No	Yes
@M@x	Control Code RS	No	No	Yes
@M@y	Control Code US	No	No	Yes
@M@z	Control Code DEL	No	No	Yes
@Q@A	VT User Defined Key 6	No	No	Yes
@Q@B	VT User Defined Key 7	No	No	Yes
@Q@C	VT User Defined Key 8	No	No	Yes
@Q@D	VT User Defined Key 9	No	No	Yes
@Q@E	VT User Defined Key 10	No	No	Yes
@Q@F	VT User Defined Key 11	No	No	Yes
@Q@G	VT User Defined Key 12	No	No	Yes
@Q@H	VT User Defined Key 13	No	No	Yes
@Q@I	VT User Defined Key 14	No	No	Yes
@Q@J	VT User Defined Key 15	No	No	Yes
@Q@K	VT User Defined Key 16	No	No	Yes
@Q@L	VT User Defined Key 17	No	No	Yes
@Q@M	VT User Defined Key 18	No	No	Yes
@Q@N	VT User Defined Key 19	No	No	Yes
@Q@0	VT User Defined Key 20	No	No	Yes
@Q@a	VT Backtab	No	No	Yes
@Q@r	VT Clear Page	No	No	Yes
@Q@s	VT Edit	No	No	Yes
@@	@	Yes	Yes	Yes
@$	Alternate Cursor (The Presentation Manager Interface only)	Yes	Yes	Yes
@<	Backspace	Yes	Yes	Yes

 

Advanced Configuration

Advanced Configuration

The window types provided with Enterprise SSO allow you to enable SSO or account collect (in Access Collector mode) for a wide range of applications. But there are some applications that cannot be managed with these standard types. In this case, Enterprise SSO proposes two solutions:

• Custom Scripts (Custom Scripts and Custom Scripts HTML that allow you to define precisely the actions to be performed in a Windows window or in an HTML page; it is even possible to call a function from an external DLL.
• The OLE/Automation interface that offers to benefit from the Enterprise SSO security data access management: with this approach: it is possible to entirely redefine the methods of detection and actions while keeping the same account management, collection, secure-storage mechanisms, etc.

In this section:

• Custom Scripts Plug-ins
• Extension DLL

Custom Scripts Plug-ins

The Custom Script and Custom Script HTML plug-ins open Enterprise SSO to some applications neither managed by the standard nor dedicated plug-ins. It offers a "scripting logic" while keeping the same simple and user-friendly configuration interface offered by ESSO Enterprise Studio and enables you to call a function from an external DLL.

IMPORTANT: The Custom Script HTML plug-in is deprecated. Use only the Custom Script plug-in to create new scripts. You must use the Custom Script HTML plug-in only to modify windows defined through this plug-in. To migrate windows created with the Custom Script HTML plugin, create the same windows using the Custom Script plug-in.

They use the same detection mechanisms already used for this kind of window in the Standard plug-in. The detection property page is the same.

However, you can select the combo box by passing the cursor over the text area or by clicking the button displaying all the different choices.

The difference is in the Actions tabbed panel of the Windows Properties window that allows you to create a logically ordered list of specific actions.

The main behavior of the window: Login, Bad Password, New Password or New Password Confirmation window is automatically deduced from the configured actions, except for Bad Password, which must be manually specified.

In this section:

• Basic Concepts
• The Actions Tab
• Script Editor

Basic Concepts

In this section:

• Scripting Logic
• Data "Buffer"

Scripting Logic

Actions are executed one after the other Their execution is based on a True or False state, which is transmitted to each action, and sometimes modified by some of them. An action is executed only if its state (Condition) corresponds to the current state, or if no state is specified for this action (No condition).

The initial state of an action is True.

The following table summarizes the behavior by indicating whether an action is performed based on its execution condition and the current state. The symbol ü means that the action is performed.

 

State Condition	True	False
None	ü	ü
True	ü
False		ü

This logic allows you to manage simple actions of If…Then…Else… type.

Data "Buffer"

All the actions include a context that contains the following data:

• The current state: this can be modified by any action, thus affecting the execution of the next actions.
• The Handle of the currently processed window.
• A memory Buffer allowing data to be passed between actions.
• The identifier of the connected application user.
• The associated password.
• The value of the last recovered SSO parameter (other than the identifier and the password).
• The account associated with the application in the security database.
• A pointer to custom user data.

The context data is maintained in a data buffer that is initialized before each Script execution in the following way:

• The current state is set to True.
• The window Handle is initialized with the Handle of the currently processed window.
• The memory buffer is empty.
• The identifier, password, and account name are initialized with current values. If the window has the "Bad password" value, the user is requested to provide the correct password during this step.
• The pointer to custom user data is set to NULL.

The Actions Tab

By default, the Actions tabbed page is empty. The following figure shows an example of a filled-in Actions tabbed page.

The list of actions to be performed is displayed in a read-only state, and a check box allows you to specify whether or not this window manages bad passwords. To build or edit a script, you must use the Script Editor.

Script Editor

The Script Editor window is made up of four elements:

• 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 action parameters.

In this section:

• Script Editor Toolbar
• Script Editor Actions

Script Editor Toolbar

The toolbar allows you to create new actions, modify their execution conditions, and move actions.

 

Button	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)
	Modify the execution condition to Always execute
	Modify the execution condition to Execute if True
	Modify the execution condition to Execute if False

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 (not supported by Microsoft Edge).	Send a JavaScript (not supported by Microsoft Edge).
	Get Control Text (not supported by Microsoft Edge).	Get Field Text (not supported by Microsoft Edge).
	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	Display a message box
	Input box	Input box
	Check certificate	Check certificate
	Change SSO State	-
	Copy buffer to param	-

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
Action description.
Send Key/String (Custom Script only)
		Modify state
		Modify buffer
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 or 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 rather 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. NOTE: To send an additional key, select None, Shift, Alt, or Ctrl from the Additional key drop down 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. Select String and fill-in the field to send a specific string.

 

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 or 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 Application level (for details, see The "Parameters" Tab) String format: enables to modify the letter case of the SSO parameter to send. Available formats: No modification. Convert to lowercase. Convert to uppercase. Convert to capitalized. 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 are IMPORTANT: The Send Command Message action works only for: 32 bits applications running on a 32 bits OS. 64 bits applications running on a 64 bits OS.Replace this text with a notation that requires the reader's attention.

 

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. IMPORTANT: 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 from 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. The Perform SSO as a different user action authorizes the SSO execution of a second user for the same application. When you select this check box, Enterprise SSO requests a second user to authenticate during SSO. IMPORTANT: The second user must have a valid account for the application.

 

Click Button (Custom Script only)
		Modify state
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. IMPORTANT: Select the Perform double click check box if you want to enable double click to select the value of a field. NOTE: 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 needsReplace this text with a description of a feature that is noteworthy.

 

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
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 Application level (for details, see The "Parameters" Tab. Item Label: a text string to look for in an item.

 

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 searched in the PATH associated with the connected user’s environment and if it is not found, it will be searched in the same directory as the one used during the configuration process. For more details on how to write external functions, see Extension DLL.

 

Sleep (Custom Script and Custom Script HTML)
		Modify state
This action suspends Enterprise SSO 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
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. You can compare the result with a regular expression and by selecting the This is a regular expression check box. IMPORTANT: this action must be preceded by the Get SSO parameter => Identifier action or the Get Control Text action. NOTE: You can use http://rubular.com to edit and test regular expressions. If you enter: %LOGIN%, you are comparing the buffer with the login. %ROLE%, you are comparing the buffer with the role specified in Enterprise SSO.

 

Check certificate (Custom Script and Custom Script HTML)
		Modify state
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
This action stops the script and returns one of the following statuses: 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: Enterprise SSO ignores the window. Disable the Application: Enterprise SSO ignores the application.

 

Special Event (Custom Script and Custom Script HTML)
		Modify state
This action allows you to trigger one of the events listed in the Special Event area. NOTE: the Resynchronize user password event allows you to display the Enterprise SSO Change Password window, which allows you to change also the user's password.

 

Create a Label (Custom Script and Custom Script HTML)
		Modify state
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
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
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. In the message box value, to add a: New line, enter \n. Tabulation, enter \t. If the user can click No or Cancel, the state is set to False. Select Buffer content to enable the user to see the content of the buffer. This feature enables the user to see his login and password. The user's answer can be saved in an SSO parameter. When SSO is performed in a Yes/no box type and the user answers, this answer is then saved and the question will not be asked again. However, if the value of the saved parameter differs, then the question is asked again. NOTE: 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.

 

Change SSO State (Custom Script only)
		Modify state
This action allows you to force the modification of the current SSO state. Example: if you select no SSO done, then the following actions will be played regarding this state.

 

Copy buffer to param (Custom Script only)
		Modify state
This action allows you to force the filling of the current buffer with the content of the parameter selected in the drop down list.

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.

An Enterprise SSO extension library sample can be found in the Enterprise SSO 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 but it can read them.
• All these elements are defined in the C/C++ header files SSOWatchSSOData.h and SSOWatchWindows.h.

In this section:

• Function Prototyping
• SSOWatchSSOData Structure
• Return Code

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:

struct SSOWatchSSOData

{

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 which can change between versions of Enterprise SSO. It must be compared to SSOWATCHSSODATA_VERSION.

The (m_bState) state 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 can be used to call Win 32 functions that need a window handle as a parameter; but it should not be modified.

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. It is not used by Enterprise SSO (except of course by external functions) and it remains valid during the entire execution of the same script.

NOTE: The members: m_pInternal, m_pInternalCred et m_pInternalInstance must not be modified. They are reserved for internal use by Enterprise SSO.ce this text with a description of a feature that is noteworthy.

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
SSORET_OK	The function ended with no error.
SSORET_SSODONE	The function ended with no error and SSO has been performed.
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 order (for example, bad password window found before the logon window).
SSORET_SSOALREADYDONE	SSO has already been performed 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. This 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	User has disabled SSO for this application.

OLE/Automation Interface

OLE/Automation Interface

For some specific applications like line terminal emulators, or applications that cannot be configured with any of the Enterprise SSO window types, Enterprise SSO provides an OLE/Automation interface.

Enterprise SSO behaves like a COM server and accepts calls from several clients. These clients connect with the COM protocol using high-level programming languages like Visual Basic, or any language that supports this kind of programming interface (which is the case of most terminal emulators like: Hummingbird Exceed, AttachMate Extra, …). You may also use this interface from any C/C++ program.

Clients connecting to Enterprise SSO use the active Enterprise SSO configuration and benefit from Enterprise SSO application behavior management and password policies.

By default, access to Enterprise SSO 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.

In this section:

• Definition of Enterprise SSO OLE/Automation Interface
• The ISSOEngine Interface
• Interface ISSOApplication
• Code Example
• Return Codes

Definition of Enterprise SSO OLE/Automation Interface

The OLE/Automation interface provides two types of objects:

• An object that represents Enterprise SSO: this object is the connection point to this interface. Through this object you can access Application objects.
• Application objects that give access to the application’s security information: login identifier, password, optional parameters. Application objects can manage the synchronization of these parameters.

The ISSOEngine Interface

ISSOEngine provides the GetApplication2 and the GetSSOEngineState functions.

IMPORTANT: The GetApplication function is obsolete and should not be used.

 

In this section:

• GetApplication2
• GetSSOEngineState

GetApplication2

Description

The function returns an interface pointer to ISSOApplication, unless the application is not found in the Enterprise SSO configuration or the challenge is not matched or this application is not configured to allow OLE/Automation access its security information.

When more than one account is associated with an application, Enterprise SSO asks the user to choose which account Enterprise SSO must use during this session. This choice will be kept until the interface pointer to ISSOApplication is released. The only way to change account is to use GetApplication2 again.

Prototypes

• C/C++:

  HRESULT GetApplication2(/*[in]*/ BSTR strAppName,

/*[in]*/ BSTR strChallenge,

/*[in]*/ LONG hWnd,

/*[out]*/ IDispatch *pIDispatch)

• Visual Basic:

GetApplication2(strAppName as String,

strChallenge as String,

hWnd as Long) as Objetct

Parameters

• strAppName is the name of the application as defined in the active configuration of Enterprise SSO (for security purposes, this string is case sensitive).
• strChallenge is the password used to protect the OLE link. This password must match the password defined in the applications settings of the Enterprise SSO configuration.
• hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Returns a pointer to the ISSOApplication interface.

Example

Dim oSSO, oApp As Object

Set oSSO = CreateObject (“SSOEngine.SSOEngine”)

Set oApp = oSSO.GetApplication2 ("MyApplication","Password",0)

GetSSOEngineState

Description

This function returns values corresponding to the state of Enterprise SSO.

Prototypes

• C/C++:

HRESULT GetSSOEngineState(/*[out]*/ LONG *plSSOEngineState)

• Visual Basic:

Get SSOEngineState () as Long

Parameters

No parameters.

Return Value

Returns the state of Enterprise SSO, as described in the following table:

 

Return Value	Engine State
0	Started
2	Stopped
4	Suspended

Interface ISSOApplication

Once the ISSOApplication interface pointer has been obtained, the following methods (or functions) and properties (or parameters) are available:

 

Methods	Properties
GetSSOParameter	LoginID
GetNewPassword	Password
GetUserApplicationPassword
Get_IsExpired

In this section:

• Properties
• Methods

Properties

In this section:

• The LoginId Property
• The Password Property

The LoginId Property

Description

Read-only property that returns the account name associated with the application.

Prototypes

• C/C++:

HRESULT get_LoginId([in] LONG hWnd, [out] BSTR *pVal)

• Visual Basic:

app.LoginId(hWnd As Long) As String

Parameters

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Name of the account associated with the application.

The Password Property

Description

Read/Write property for retrieving or setting the application password.

Prototypes

• C/C++:

HRESULT get_Password(/*[in]*/ LONG hWnd, /*[out]*/ BSTR *pVal)

HRESULT put_Password(/*[in]*/ LONG hWnd)

Visual Basic:

app.Password(hWnd As Long) As String

Parameters

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Password of the application.

Methods

In this section:

The GetSSOParameter Method

The GetUserApplicationPassword Method

The GetNewPassword Method

The get_IsExpired Method

The GetSSOParameter Method

Description

Method that returns an SSO parameter which name is in strParameterName. The strParameterDesc parameter is a user-friendly description if Enterprise SSO needs to prompt the user for the parameter value.

Prototypes

C/C++:

HRESULT GetSSOParameter(/*[in]*/ LONG hWnd,

/*[in]*/ BSTR strParameterName,

/*[in]*/ BSTR strParameterDesc,

/*[out]*/ BSTR *pVal)

Visual Basic:

app.GetSSOParameter(hWnd As Long,

strParameterName As String,

strParameterDesc As String) As String

Parameters

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

strParameterName is the name of the SSO parameter to retrieve.

strParameterDesc is a user-friendly description (or a label) if Enterprise SSO needs to prompt the user for the parameter value.

Return Value

Returns the SSO parameter.

The GetUserApplicationPassword Method

Description

This method collects the password of the running application by asking the user to enter it. This method returns the password as a string.

Prototype

C/C++:

HRESULT GetUserApplicationPassword(/*[in]*/ LONG hWnd,

/*[out]*/ BSTR *pVal)

Visual Basic:

GetUserApplicationPassword(hWnd As Long) As String

Parameters

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Returns the password as a string.

The GetNewPassword Method

Description

Prompts the user for a new password (or creates a new one automatically, following the password policy) for the running application.

IMPORTANT: You must call the Password property when you use this method to save the new password.

Prototypes

• C/C++:

HRESULT GetNewPassword(/*[in]*/ LONG hWnd,

/*[out]*/ BSTR *pstrPassword)

• Visual Basic:

app.GetNewPassword(hWnd As Long) As String

Parameters

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Returns a new password for the running application.

Example

NewPassword$ = oApp.GetNewPassword(0) // Asks for a new password.

oApp.Password(0) = NewPassword$ // Saves the new password.

The get_IsExpired Method

Description

This method allows you to know if the password has expired. It must be used after the GetNewPassword method.

Prototypes

C/C++:

HRESULT get_IsExpired(/*[in]*/ LONG hWnd,

/*[out]*/ BOOL *pbExpired)

Visual Basic:

app.IsExpired(hWnd As Long) As Long

Parameter

hWnd is the window handle of the application where the OLE/Automation script runs. This handle allows the blocking of input to the application window when Enterprise SSO asks for security information, so that Enterprise SSO windows does not appear under the application window (in the background). If this information is not available or you do not know how to get it, provide the value 0.

Return Value

Returns True if the password has expired.

Code Example

To use these interfaces, you must first connect to Enterprise SSO by creating an "SSOEngine.SSOEngine" object:

Dim oSSO, oApp
Set oSSO = CreateObject("SSOEngine.SSOEngine")

This returns an interface pointer to ISSOEngine that allows you to call the GetApplication2 method:

Set oApp = oSSO.GetApplication2(" NomApp ", " password ", 0)

Then you can use the security information:

Wscript.Echo " Login: " & oApp.LoginId(0)
Wscript.Echo " Password: " & oApp.Password(0)

Once you have finished with the objects, you must free them (otherwise, Enterprise SSO will not be stopped safely):

Set oApp = Nothing
Set oSSO = Nothing

Return Codes

Return codes are HRESULT with the FACILITY_ITF feature.

 

Define	Value	Meaning
SSOAPI_OK	0	OK
SSOAPI_INVALID_SERVICE	1	Account or Service empty.
SSOAPI_ACCESS_DENIED	2	No Account exists.
SSOAPI_SUBAPI_ERROR	3	Generic error from User Provisioning underlying API.
SSOAPI_INVALID_SERVICE_TYPE	4	Invalid Service Type (User Provisioning only).
SSOAPI_UNKNOWN_ERROR	5	Unknown error.
SSOAPI_MEMORY_FAILED	6	Out of memory.
SSOAPI_INVALID_PASSWD	7	Invalid password: this return code is managed by the OLE/Automation API.
SSOAPI_UNKNOWN_PARAMETER	8	Unknown parameter.
SSOAPI_INVALID_PARAM_NAME	9	Invalid parameter name.
SSOAPI_INVALID_FLAG	10	Internal.
SSOAPI_SERVICE_NOT_FOUND	11	Service not found for the system type provided. Similar to ACCESS_DENIED.
SSOAPI_SERVER_ERROR	12	Error while accessing the security server.
SSOAPI_PASSWD_NOT_CHANGED_ YET	13	The password change is not taken into account yet.
SSOAPI_NOMOREAPP	14	No more applications in the application list.
SSOAPI_NOTREADY	15	Not ready (for example: smart card removed).
SSOAPI_UNKNOWN_APPLICATION	16	Unknown application.
SSOAPI_CANCELLED_BYUSER	17	Application instance disabled by the user.
SSOAPI_CANCELLED_BYUSER_APPLICATION	18	Application disabled by the user.
SSOAPI_DISABLED_APPLICATION	19	Application already disabled by the user.