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

Technical Notes

Creating Single Sign-On Macros to Use with Passlogix v-GO
Technical Note 2524
Last Reviewed 31-Mar-2011
Applies To
Reflection for the Web 2008 (All Editions)

This technical note explains how to create Reflection for the Web sign-on macros for use with Passlogix v-GO SSO.

Note: 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 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.
  • Logon during which the user mistypes a username or password.
  • 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 follow as it plays back the macro and encounters different host screens. When the macro successfully completes playing, the credentials are stored in the Passlogix credential store and subsequent launches of the same session retrieve and play back the saved values.

Recording Your First Single Sign-On Macro

The following steps show how to record the first macro of your single sign-on collection. In this example, some steps are similar to those used for an IBM mainframe (for example, the use of fields), but you may use other host types, which 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 reach 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 used when working with v-GO:

Always prompt user for value: This setting causes the macro to always prompt the user for a response. It will always be used to prompt for the user ID and password and to handle an expired password.

Prompt text: Provides the prompt text for macro rows that always prompt the user for a value. It is recommended that you use a unique string in this field, since Passlogix will use it as a key to differentiate this dialog from other dialogs.

Embed fixed user response in macro: This transmits the literal string entered during the recording process to the host. If data is constant and never changes, leave this setting as it is recorded.

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

Note: 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.

  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.

  1. To view your session, click Session Manager.

Configure Passlogix v-GO to Use the Single Sign-on Macro

Setup Passlogix v-GO to recognize the username and password dialog boxes. If you need help configuring Passlogix, contact Oracle Customer Support:

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.

Note: During the playback of the sign-on macro. If you have setup v-GO to interface with the user ID and password dialog correctly, v-GO will prompt for the user ID and Password, and will then automatically enter the values in the user ID and password dialogs.

  1. Log off the host computer and exit the terminal session.
  2. From the links list, click 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 > Edit Automated Sign-on Macros, select the macro to edit, and then click Edit.

You may not be able to edit some macro changes from the Edit dialog box. If this occurs, delete and re-record the macro sequence.

Record 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.

Record Failed Password Macro

To prevent a failed logon, you can record a second macro that handles expired passwords. An incorrect password sent to the host typically results in 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 diagram shows the process of two single sign-on macros to an IBM mainframe:

Figure 1: Single Sign-On Macros

In the diagram above, 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.

Collection Flow Sample

To record each additional 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. From 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 re-record 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.

Resolving Conflicts

Consider the following when resolving single sign-on macro conflicts:

  • 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 cannot 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
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.