PS_Automate Utility
Use the Password Safe PS_Automate utility
Overview
The Password SafePS_Automate utility helps to avoid the need to manually enter credentials when launching Windows GUI applications from Password Safe, saving time and increasing security.
The PS_Automate utility allows you to seamlessly pass vaulted credentials from Password Safe to a remote application using the pass through option (using token pass instead of credentials). This includes the ability to launch and authenticate to a web page or to a standard Windows GUI application.
To ensure a seamless experience, the utility supports Incognito mode for popular web browsers, such as Chrome, Firefox, and Microsoft Edge, with Edge being the default. By using an INI file, you can easily specify the input and operational behavior for the utility.
The PS_Automate utility, as well as INI files for Amazon Web Services, Azure, Office 365, and Google, are made available when enhanced session auditing is enabled in Password Safe. The files are deployed by the session proxy when a session is created in Password Safe.
The system where the PS_Automate utility is deployed must have internet access, in order to automatically download the latest version of the required browser drivers on first use:
- chromedriver.exe
- msedgedriver.exe
- geckodriver.exe
The utility uses the browser drivers, and the versions of the drivers must match the versions of the browsers used.
Note
PS_Automate is a utility for Windows only. It is not supported on macOS.
Usage
The usage syntax for the PS_Automate utility is as follows:
Web applications
ps_automate.exe [ini=path to inifile][TargetURL=url] [BrowserName=name of browser]
Windows applications
ps_automate.exe [ini=path to inifile]
Note
For testing purposes the utility also accepts username and password on the command line: [username=username] [password=password]. However, this is not recommended for production use, as command line parameters can be written to Windows logs, such as the event log.
Example:
ps_automate.exe ini="BIWebApp.ini" TargetURL="https://localhost/WebConsole/index.html#!/dashboard" BrowserName="chrome"``ps_automate.exe ini= "C:\automate\AWSWebApp.ini" TargetURL="https://534949981440.signin.aws.amazon.com/console/" BrowserName="firefox"``ps_automate.exe ini="MSWebApp.ini" TargetURL="https://login.microsoftonline.com"BrowserName="msedge"``ps_automate.exe ini="ssms_database.ini"
ps_automate.exe ini= "C:\automate\AWSWebApp.ini" TargetURL="https://534949981440.signin.aws.amazon.com/console/" BrowserName="firefox"
ps_automate.exe ini="MSWebApp.ini" TargetURL="https://login.microsoftonline.com"BrowserName="msedge"
ps_automate.exe ini="ssms_database.ini"
Define command line arguments in INI file
INI files are commonly used configuration files for storing settings and preferences for applications. The PS_Automate utility uses INI files to specify its own settings and parameters. It is generally provided as a command line parameter, for example, ini=login.ini. If no file is specified, the utility looks for an INI file in the same source directory with the same name as the utility, i.e. ps_automate.ini.
When command line arguments are provided, they can technically be listed in any order as each is prefixed with the argument name, i.e. argument=value.
The following common predefined INI files are included with the deployment of the PS_Automate utility.
- AWSWebApp.ini for Amazon Web Services logins
- BIWebApp.ini for BeyondInsight logins
- GoogleWebApp.ini for Google URL logins
- MSWebApp.ini for Microsoft URL Logins
- ssms_database.ini for SQL Server Management Studio v18 logins
The INI file is in standard INI format consisting of one or more sections with each section containing one or more key/value pairs. Each of the sections and their key/value pairs are described below.
General section
The [General] section defines the main settings for the application. Each setting and its accepted values are listed below.
Credentials section
The [Credentials] section is an optional section used for hard coding the username and password values into the INI file. When this section is provided, both keys are required and override any command line values provided.
Note
This section is used for testing. We recommend you secure any INI files containing credentials.
| Setting | Definition |
|---|---|
| UserName | Value: Valid username Required: Yes Description: The username to provide to the security dialog. Specified as %username% to the provided task. |
| Password | Value: Valid password. Required: Yes Description: The password to provide to the security dialog. Specified as %password% to the provided task. |
TaskSequences section
The [TaskSequenceX] sections of the INI file define the tasks to take once the RunApp or TargetURL has been accessed.
Place each [TaskSequenceX] in its own section in the INI file in sequential order and ideally order them numerically as per the following example:
[TaskSequence1]
task=value
…
[TaskSequence2]
task=value
…
[TaskSequence3]
…
Each [TaskSequenceX] can perform one or more tasks. Generally, a specific task sequence consists of providing information to target the appropriate dialog box/control and then send text or a command to it, for example click. Most pages generally require a minimum of two task sequences, one to populate the username and one to populate the password. Since tasks can be combined within the [TaskSequenceX], the submission (posting) of these values can be tasks of the same [TaskSequenceX].
Sometimes additional task sequences must be performed before or after supplying credentials. However, it is possible to automate many actions with a single task sequence through the use of SendKeys for Windows applications only.
App and WebApp task sequences and their values are listed below. All tasks within a task sequence are optional, though some depend on others or are mutually exclusive.
Each task can be defined only once within each [TaskSequenceX].
App task sequences
App task sequences begin after being initiated by a RunApp.
The standard function of a sequence is to enter a string of data (SendKeys) into a particular control (AppWindowControlID) on a window. If a control is provided to the sequence, the utility attempts to attach to the control, focus it, and send it directly to the control. This is a very accurate way of targeting commands. If no control is provided (or one can’t be found), the commands can still be issued to the active window/control.
In addition to the tasks from the generic task sequences, the following tasks are applicable for the RunApp (App) task sequences.
WebApp task sequences
The web application depends on a TargetURL from the General section. Task sequences use Xpath to find and click the web page element.
The standard function of a web application task sequence is to enter an Xpath string for the element you want to interact with, as well as a value for the element.
The webapp tasks rely on browser drivers to accomplish their tasks. The utility automatically downloads the browser driver to the same location as the utility. The browser version (major.minor.build) must match the driver version or the utility may fail to launch the browser. For example, chromeDriver 100.0.4896 will work with Chrome browser 100.0.4896.x.
Ensure the functional account used for the RDS Session has network permissions that allow the PS_Automate to access the internet. For example, add the functional account to GPO, thereby allowing the functional account to use the proxy.
In addition to the tasks from the General section, the following tasks are applicable for the WebApp TaskSequences section.
| Setting | Definition |
|---|---|
| XPathElement | Value: Xpath string for the element Description: Goes to the element specified. |
| XPathValue | Value: Xpath string for the element value. Description: Enters the text specified into the element. |
| XPathAction | Value: String value click, clear. Description: Clicks on the element specified by XPathElement. |
Certificates
For keeping sensitive web traffic information secure, certificates are used. The PS_Automate utility has the ability to IgnoreCerts, which are provided for internal self hosted websites and for testing only.
Chrome and Edge browsers can ignore certificates for localhost only. The Firefox browser does not have this limitation.
Web app known issues
- When multiple RDP sessions are launched for the same machine at the same time, the end user may experience a delay with the automated logon for one of the sessions. One session blocks while the other loads. Once the session successfully loads (maximum wait time 30 seconds), the other session is able to successfully load its browser and begin the automated login.
- Manually clicking, opening new browser windows, or creating tabs on the launching of the automated browser can cause the automated login to fail.
- Issues automatically updating the Firefox driver (geckodriver) to the latest version. If PS_Automate fails to launch the Firefox browser, one possible cause is that the driver version is out of date. PS_Automate attempts to update the driver; however, there is a known issue where geckodriver updates may fail. In that case download the geckodriver, from https://github.com/mozilla/geckodriver/ and place it in the same directory as ps_automate.exe.
Updated 7 days ago