Remote Desktop / Windows Credential Dialog

/*****************
* Remote desktop script (mstsc.exe, not windows 10 one)
*
* The Enc1 field on the user's bookmark contains the target server name:port
* The users need to be told to fill this in.
****
* Known Issues
*
* Credential selection dialog sometimes shows twice if more than one bookmark.
* Desktop startup only works if path does not contain environment variables.
*   i.e. it's C:\windows\system32\mstsc.exe rather than %systemroot%\system32\mstsc.exe
*****************/

OnError Terminate AlertUser

StartProcess bmAppPath SingleInstance
WaitProcess bmAppPath

SelectBookmark

// Open Advanced mode
SendKeys ALT+o
// Give the RDP app time to show the advanced controls
Wait 300

// Send the server name and username then open session
// The Enc1 field on the user's bookmark contains the server name:port
// The ctrl+A del is to clear out any old content in the username field

SendKeys bmEnc1 TAB CTRL+A DEL bmUsername ENTER

// Can't use WhenWinow on credential dialog as it's a different process
// Wait for credential dialog to open by its process exe name
// This requires the use of the Secondary option
WaitProcess Secondary "CredentialUIBroker.exe"

// Credential Dialog does not have a window handle, so need to just send to foreground window
SendKeys AnyWindow bmPassword ENTER

Electron App (Rezlynx Reservation System)

The Rezlynx Reservation System, in 2018, was implemented as an Electron type application on Windows, with an embedded browser.

The main challenge with this system was ensuring the desktop agent only tried to populate the login details when the window had drawn (which took a variable and significant length of time).

The secondary challenge was that the application almost always opened in the background and had to be forced to the foreground in order to trigger the credential injection.

OnError Terminate AlertUser
StartProcess bmAppPath 10000
WaitProcess bmAppPath

WhenWindow "Rezlynx Logon Screen"
{
 // Automatically injects credentials if vault launched
 // or if only one bookmark stored for the app.
 SelectBookmark

 // Occasionally the keys are sent before the window is
 // ready, so have a slight pause.
 Wait 250
 SendKeys TAB
 SendKeys "SITE-CODE" TAB bmUsername TAB bmPassword ENTER
}

// Bring the app to the foreground to trigger
// the WhenWindow option:
// Slower PCs may require a Wait before each command.
BringToForeground BtfAltTab
BringToForeground BtfAltTab

Selecting Specific controls

The Introductory Script Example shows how to select buttons based upon the text shown on them.

In this example we are considering an application where, depending upon context, the same login dialog box can have either the username or password control in focus. This script shows how to create a common method to correctly inject credentials in the window.

Target Application

The logon dialog for the target application (“Reception” a hospitality application) is shown below.

This dialog may be shown when the user initially logs in to the application or when the user session times out. These two scenarios result in different behaviours of the dialog:

• The username is sometimes pre-populated and the input focus is on the password field, or the usename is empty and the input focus is on it.

• Either the Change Password button or the login (tick) button is the dialog default button. This means pressing (or emulating) Enter can either log the user in or take them to a password change screen.

• The logon dialog does not always come to the foreground when it pops-up therefore the credential injection is not automatically triggered.

• The logon dialog has the caption “Reception”. Unfortunately other dialogs in the application also have the same caption. We need to ensure the login script only runs for the login dialog.

The script below addresses each of these issues.

OnError Terminate AlertUser
StartProcess bmAppPath 10000
WaitProcess bmAppPath

// Trigger when a dialog with the caption
// of "Reception" is visible and it has a
// text label containing "User Name"
WhenWindow "Reception" ControlStatic "User Name"
{
 // Allow the dialog box to finish painting
 // its controls
 Wait 100

 // Force the selection of the User Name field
 SelectControl ControlEdit 1

 SendKeys bmUsername TAB bmPassword

 // Force the selection of the Login (tick) button
 SelectControl ControlButton 3

 // Press the login button
 SendKeys ENTER
}

// Standard select bookmark behaviour
SelectBookmark

// Trial and error found that the following
// three calls were required to force the
// dialog into the foreground, thus triggering
// the automated login.
BringToForeground BtfAltTab
BringToForeground BtfSwitch
BringToForeground BtfAltTab

Note

The login button is visually the second button on the dialog, but programatically is the third button.

In this dialog, selecting the User Name field also selected its content, therefore typing in the username automatically overwrites the existing entry.

If the existing content was not automatically selected then the following command will do it for you:

SendKeys CTRL+a

SAP GUI Application

Covers morphing processes and selecting bookmarks after application starts.

This example is a real world case covering the SAP GUI. It’s quite involved as this isn’t a trivial app for a multitude of reasons.

The added complexity here is how we deal with an app that only allows one instance to be running on the computer. This means that when a second instance is started via a Vault launch, the new process is killed and focus is set to the currently running instance.

The complexity is how to tell the original process’ script that it’s vault launched and needs to use the bookmark supplied by the Vault launch. While incredibly complex behind the scenes this has been enabled by a simple parameter to the StartProcess command.

Reviewing the Default SAP GUI Behaviour Prior to Scripting

Starting the app shows the list of connections.

The user then double clicks on one of the named connections. That then launches a login dialog.

The user now enters their credentials and is logged in.

Connection string selection

The Extra Encrypted 1 field (bmEnc1 in the script) is used to store the connection text.

When the SAP GUI connection list is in focus you can just type the connection text to select it then press Enter to open it. So the script sends the content of bmEnc1 to the listbox to do this.

Identifying Credentials for a connection

The SAP system uses three letter abbreviations to identify different installations, the “NPL” in the Extra Encrypted 2, above, is the value for our test system.

It turns out that the SAP GUI can be configured to show these values in the login dialog’s caption bar (although they’re only visible when the window doesn’t have focus).

Showing these abbreviations allows us to use the SelectBookmark’s caption matching features to restrict the candidate set of bookmarks to those that have the bmEnc2 value (they system ID) at the start of the login dialog.

OnError Terminate AlertUser

// The SAP GUI only supports one instance running, so any
// subsequent processes are killed and focus set to the original
// process, so we need to use the Morphs setting to support this.
StartProcess bmAppPath Morphs
WaitProcess bmAppPath

// If launched from the vault then select the named connection
WhenVaultLaunch
{
  // This is only needed when the SAP GUI is started via the desktop
  Wait 150

  // Select the connection that matches the bookmark name
  // This opens the “SAP” login window which is detected
  // by the WhenWindow statement.

  SendKeys bmEnc1 ENTER
}

// Select the window that ends in SAP
WhenWindow "SAP$"
{
  // Match to bookmark whose bmEnc2 value matches the start
  // of the window's caption.
  SelectBookmark Caption StartsWith bmEnc2
  SendKeys bmUsername TAB bmPassword ENTER
  AlertInfo bmTitle " User: " bmUsername, bmTemplateName
}

Flash\Java Website

There is one major issue (from an SSO perspective) with Java and Flash based websites, we cannot programmatically detect when the page is ready to take input.

The Flash or Java app must load in the browser, and the time taken for this can vary enormously from under a second to tens of seconds, even for the same app. Therefore using a Wait command is not feasible.

The approach that we have taken is to present the user with a dialog box that allows them to tell the system when the website is ready to take the login details. This dialog supports a customisable message to the user and can be forced to restrict sending credentials to a browser tab with specific text content.

The screen shot below shows a Flash website and the prompt to the user to send the login details once the page has loaded.

The Flash app needs to be brought into the foreground for the SendKeys command to work. In the script below we use a left click on an empty area of the web page in order to force the Flash app into the foreground.

There aren’t many publicly available Flash websites, we chose one called Dedoose purely to illustrate the concept.

Note that there is no WaitProcess command because this script does not support desktop startup.

// Launch the app in the default browser
LaunchUrl "https://app.dedoose.com/App/?Version=8.0.42"

// Tell the user to click on the web page when it's loaded. Return the
// selected credentials to the script and only inject into a window
// that has “Dedoose” in its caption.
InteractiveSelectBookmark SelectOnly Restrict "Dedoose" "When the Dedoosse page is loaded, select the required user below, then click Send."

// Ensure the Flash app is in focus by clicking
// on it in an empty area.
LeftClick 20 VerticalMiddle

SendKeys bmUsername TAB bmPassword

// Slight pause to let the screen catch up
Wait 100

// Trigger login
SendKeys ENTER

IE Compatibility Mode

If an app forces IE to run in Compatibility mode then it is essentially forcing IE to run as if it were IE 5. This mode is not compatible with any SSO browser plugins.

My1Login allow you to provide SSO for Compatibility Mode apps via the desktop agent.

The example below shows how to amend the above Flash solution to force the site to open in IE rather than whatever the user’s default browser happens to be.

The Avaya Contact Center App example is for an app that requires compatibility mode.

The following script settings will open a URL in IE.

• Path to App: C:\Program Files\internet explorer\iexplore.exe

• Command Line Arguments: URL of target login page

• Replace the LaunchUrl command with: StartProcess bmAppPath bmAppArgument

The settings below show the IE specific version of the previous Flash example.

Note that there is no WaitProcess command because this script does not support desktop startup.

// Launch the app in IE
StartProcess bmAppPath bmAppArgument

// Tell the user to click on the web page when it's loaded. Return the
// selected credentials to the script and only inject into a window
// that has “Dedoose” in its caption.
InteractiveSelectBookmark SelectOnly Restrict "Dedoose" "When the Dedoosse page is loaded, select the required user below, then click Send."

// Ensure the Flash app is in focus by clicking on it
LeftClick 20 VerticalMiddle
SendKeys bmUsername TAB bmPassword
Wait 100
SendKeys ENTER

Avaya Contact Center App

As of 2019 the Avaya Contact Center web app (as used by our customers) forces IE to run in Compatibility mode.

This section presents two scripts that enable users to SSO into Avaya using the My1Login desktop agent.

The first script launches the user’s default browser while the second script forces IE.

// Launch the app in the default browser
LaunchUrl bmAppPath

// Show interactive dialog to user
// Restrict use to browser tabs with "Contact Center" captions

InteractiveSelectBookmark SelectOnly Restrict "Contact Center" "When the Contact Center page is loaded, select the required user below, then click Send."

SendKeys  bmUsername TAB bmPassword
Wait 100
SendKeys ENTER

// Launch the app in IE
StartProcess bmAppPath bmAppArgument

// Show interactive dialog to user
// Restrict use to browser tabs with "Contact Center" captions

InteractiveSelectBookmark SelectOnly Restrict "Contact Center" "When the Contact Center page is loaded, select the required user below, then click Send."

SendKeys  bmUsername TAB bmPassword
Wait 100
SendKeys ENTER

Password Change Example

This section shows how to integrate automated password change scripting into the Introductory Script Example.

The sample application from the introductory example has a Change Password option that shows the following dialog box:

Using the WhenWindow command allows script commands to be executed when this dialog box is shown. The script then uses the bmNewPassword attribute to carry out the password change.

The password policy (length, etc.) is set for the desktop template, see Password Change Attributes for details on this and on the working of the bmNewPassword attribute.

// Trigger when the "Change Password" dialog opens
WhenWindow "Change Password"
{
 // Inform the user that the password is changing
 AlertInfo "Changing Password...", bmTitle

 // Fill the old and new password fields
 SendKeys bmPassword TAB bmNewPassword TAB bmPassword ENTER

 // Update the details in My1Login
 SaveChanges

 // Tell the user the password has changed
 AlertInfo "Password Changed", bmTitle
}