Attachmate Worldwide  |   Contact Us  |   The Attachmate Group
Extend. Manage. Secure. More than 30 years in the business. Over 65,000 customers.

Technical Notes

Creating Reflection for the Web 2008 Single Sign-On Macros
Technical Note 1876
Last Reviewed 10-May-2007
Applies To
Reflection for the Web 2008 (All Editions)
Summary

This technical note explains how to create Reflection for the Web 2008 single sign-on macros using the Reflection for the Web credential store.

Note the following:

  • For information about single sign-on macros in Reflection for the Web 2011, see the product documentation.
  • For information about single sign-on macros using the Express Logon Feature (ELF), which uses RACF on the IBM host, see Technical Note 1865.

About Single Sign-On Macros

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:

  • a regular successful logon.
  • a logon during which the user mistypes a username or password.
  • a logon that handles password expiration.

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.

Prerequisite

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.

Configuring Reflection for Single Sign-On Support

To implement single sign-on, make the following configuration changes in the Reflection Administrative WebStation.

  • Click Security Setup and on the Credential Store tab, select Enable credential store, and then click Save Settings.
  • Optional: Enable an identity based authentication. Authentication enables user credentials to be stored uniquely on the server.

Click Access Control Setup > Configure and enable an identity based authentication method.

Note: Identity based authentication is not supported for methods None and NTFS.

Recording Your First Single Sign-On Macro

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:

  1. Go to the Reflection Administrative WebStation > Session Manager and create a new terminal session or edit an existing session.
  2. In the Connection (or Session) Setup dialog box, enter the name of the host, the port number, and any other required transport or connection options.
  3. Optional: To create a secure session, click SSL/TLS (or Security), select the appropriate security options, and then click OK to return to the Connection (or Session) Setup dialog box.
  4. Using the drop-down list at the bottom of the Connection (or Session) Setup dialog box, select Record a single sign-on macro, and then click Connect.
  5. Click OK to start recording. The "macro recording" indicator (a black dot) appears in the status bar of the session window while recording is in progress.
  6. Log on to the host as usual. The macro recorder will capture your actions.

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.

  1. When you arrive at the final screen of your recording sequence, click Macro > Stop Recording.
  2. In the Save Macro dialog box, enter a name and description for the macro, and set the options for each macro step.

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.

Prompt text:

Provides the prompt text for macro rows that always prompt the user for a value.

  1. Click Save.
  2. Click File > Save and Exit > Save/Exit to save the macro and exit the session.

Note the following:

    • The macro is not fully saved until you save and exit the session. If you discard the session without saving it, any recorded macros that have not been saved previously are discarded as well.
    • When working with macros in a session being configured or when logged into the Reflection server as an administrator, credential values are never saved to the Reflection credential store. Credentials are saved only when the macro is played back as a non-administrative user.
  1. To map the session access:

For a new session—Click Map session access, assign the appropriate access to users for this session, and then click Save Settings.

For an existing session—Click 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.

Testing Your Recorded Macro

To test your first single sign-on macro:

  1. Single sign-on macros cannot be tested from the Administrative WebStation. Launch Reflection for the Web as an end-user and log in as a user who has access to the session containing the macro.
  2. From the links list, click the session to launch.

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.

  1. Enter your credentials when prompted by the macro.

When macro playback completes successfully, your credentials are sent to the Reflection server for storage in the credential store.

  1. Log off the host computer and exit the terminal session.
  2. From the links list, click on the name of the session to relaunch it.

This time when the single sign-on macro plays, the saved credentials should be inserted automatically and no prompts should appear.

Editing Your Recorded Macro

If playback was not successful, or if you want to change the prompts or other settings for the macro, follow these steps:

  1. Return to the Session Manager in the Administrative WebStation and launch the session with the single sign-on macro.
  2. Click Macros > Choose Edit Automated Sign-on Macros, select the macro to edit, and then click Edit.

Some macro changes may not be editable from the Edit dialog box. If this occurs, delete and re-record the macro sequence.

Recording Additional Single Sign-On Macros

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:

Figure 1: Single Sign-On Macro Collection Flow Sample Figure 1: Single Sign-On Macro Collection Flow Sample

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:

  1. Launch the session containing the single sign-on collection from the Session Manager in the Administrative WebStation.
  2. Click Connection > Disconnect.
  3. Click Connection > Connection (or Session) Setup.
  4. Using the drop-down list at the bottom of the dialog box, select Record a single sign-on macro, and then click Connect.
  5. Click OK to start recording.
  6. Perform the desired sequence of actions for the second macro.

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.

  1. When you arrive at the final screen of your recording sequence, click Macro > Stop Recording.
  2. In the Save Macro dialog box, enter a name and description for the macro, and set the options for each macro step.
  3. Click Save.
  4. Click File > Save and Exit > Save/Exit to save the macro and exit the session.

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.

Related Technical Notes
1755 Integrating Reflection for the Web with SiteMinder
9988 Reflection for the Web Technical Notes

horizontal line

Did this technical note answer your question?

           


Need further help? For technical support, please contact Support.