This technical note explains how to create Reflection for the Web 2008 single sign-on macros using the Reflection for the Web credential store.
Reflection for the Web version 8.5 includes support for single sign-on macros, including Express Logon macros for users of IBM 3270 sessions.
Single sign-on to the host takes advantage of macros that you record as part of terminal session setup. In contrast to regular macros, which record and play back just one sequence of events, single sign-on macros let you create a collection of macros that combine to handle a variety of logon scenarios, such as:
By recording a collection of macros, you create a tree-like structure with different branches that the macro system can take as it plays back the macro and encounters different host screens. When the macro successfully completes playing, the credentials are stored on the Reflection server and subsequent launches of the same session retrieve and play back the saved values.
Note: It is not possible to load balance web servers if Single Sign-on (SSO) macros are being used. The credentials store associated with SSO macros cannot be synchronized among multiple management servers.
Saving user credentials to the Reflection server requires Data Protection API (DPAPI) support included with Microsoft Windows 2000 or higher. DPAPI is a pair of function calls that provide data protection for user and system processes at the operating system level, so there is no browser requirement. The credentials are encrypted and decrypted using a key associated with a user's Windows logon credential on a given machine. If Windows DPAPI support is not available or if a non-identity-based authentication method is used, single sign-on macros will still play back, but the user will be prompted for their credentials each time the macro plays.
To implement single sign-on, make the following configuration changes in the Reflection Administrative WebStation.
Click Access Control Setup > Configure and enable an identity based authentication method.
Note: Identity based authentication is not supported for methods None and NTFS.
The following steps show how to record the first macro of your single sign-on collection. Some steps are geared towards an IBM mainframe (for example, the use of fields), but other host types are generally similar.
Note: Only an administrator can create single sign-on macros for a terminal session, and only while creating or editing the session in the Administrative WebStation.
To record your first single sign-on macro:
Note: When entering data into host fields, if the cursor does not automatically move to the next required field, use the Tab key to move to the field.
Each prompt that you responded to when recording the macro is shown on a separate row in the top half of the dialog box. You cannot directly edit these rows. Instead, select a row and change the settings in the lower half of the dialog box to update the display.
The following options are available for each step in the macro:
Retrieve user response from credential store:
This is the default setting for items identified as passwords during macro recording. The first time a user plays back the macro, a prompt appears for his or her credentials. The credentials are stored and then retrieved from the credential store on subsequent logons.
Playback user response from row:
Some host logon prompts require the same data as that entered in at a prior prompt. This option lets you specify another row of the macro whose value should be used during this step.
Always prompt user for value:
This setting causes the macro to always prompt the user for a response. It can be used to handle an expired password, a mistyped entry, or when no credential is stored for the value.
User response overwrites values in credential store for row:
If the option to always prompt is selected, this setting is used to indicate whether the response to the prompt should be saved as the value of a different macro row.
Embed fixed user response in macro:
This transmits the literal string entered during the recording process to the host.
Provides the prompt text for macro rows that always prompt the user for a value.
Note the following:
For a new sessionClick Map session access, assign the appropriate access to users for this session, and then click Save Settings.
For an existing sessionClick Save Settings. Click Access Mapper in the left-navigation menu, assign the appropriate access to users for this session, and then click Save Settings again.
To view your session, click on Session Manager.
To test your first single sign-on macro:
After the session launches, the macro begins to play. Single sign-on macros always play at session startup, before any other startup macros and they do not appear in the Play Macro dialog box.
When macro playback completes successfully, your credentials are sent to the Reflection server for storage in the credential store.
This time when the single sign-on macro plays, the saved credentials should be inserted automatically and no prompts should appear.
If playback was not successful, or if you want to change the prompts or other settings for the macro, follow these steps:
Some macro changes may not be editable from the Edit dialog box. If this occurs, delete and re-record the macro sequence.
To handle situations beyond a simple successful logon, record additional single sign-on macros for your single sign-on macro collection. All single sign-on macros recorded in the same terminal session are automatically added to that session's collection.
For example, if a user's host password expires after six months, with just one macro in the collection the password previously stored in the credential store and transmitted by the macro to the host will fail. To prevent the failed logon, you can record a second macro that handles expired passwords.
Typically, when an incorrect password is sent to the host, the host responds with a prompt that differs from the one received after a correct password. By creating a second macro that records this alternate sequence, the macro playback system can proceed down a different branch when it encounters the failure prompt.
To create an expired password sequence, access your directory services system and expire the password of your test user. Then, follow the steps below to record a second macro for your single sign-on collection. When prompted, enter the test user name and expired password, respond to the system prompt to enter a new password and continue recording login steps as needed.
The following illustration shows two single sign-on macros to an IBM mainframe when laid out as a tree structure:
The first two steps for each sequence are identical, but the paths branch at step 3. In this example, steps 4 and 5 of Branch B prompt the user for input and save the responses as the values for future iterations of steps 1 and 2.
With this configuration, the next time the macro runs, the correct values will be transmitted in steps 1 and 2, and the macro will complete successfully down Branch A.
To record each addition macro for a single sign-on collection:
Note: When creating the second macro, you must rerecord any steps that are the same as the existing macro(s) in the collection associated with this terminal session. Remember, you are creating a tree-like structure with different branches for the different host logon sequences. If part of the tree is common to more than one macro sequence, those steps are duplicated in each macro.
If Reflection detects conflicting actions in any of the steps that are common to other macros in the collection, a message alerts you to the conflict. For details about the conflict, see the Java console.
Most conflicts occur when the host prompt for a common step is the same but different actions are configured in different macros. In this instance, the playback system can not determine which path to take though the macro collection.
Some conflicts and ambiguities can be corrected by editing the settings in the Save Macro dialog box. Other conflicts are more complex and may require that you rerecord the macro sequence.
Continue to record additional single sign-on macros for the collection, taking into account the different types of logon situations that user's may encounter.