How do I set up Login Agent?

Introduction

The Login Agent software is a separate installation providing functions which support the automation of user interactions with Windows desktop operating systems. This document is a supplemental guide to the existing “Blue Prism Login Agent - User Guide”, and is intended to offer further guidance specifically related to the configuration and operation of the Login Agent software.

The document uses the process called “Login” to check that everything is configured properly for using the Login Agent software. Once this process is running, then other Login Agent processes can be added to make a more sophisticated and robust automation procedure.

The Installation Stage

The procedure to install the Login Agent software is detailed in the User Guide. There are several factors which could affect the installation, and these are listed below:-

• The Login Agent software needs to be installed on every Resource PC which need to be automated using the software
  • For convenience, you may want to install Login Agent on a machine hosting the Blue Prism Interactive Client software in order to be able to import the provided Processes and Objects, and to develop your own processes.
• The Login Agent installer (.msi file) should match the operating system of the machine onto which it is installed. For example, a 64-bit operating system might use the ‘LoginAgent1.4.0_x64.msi’ file.

Login Agent software download

The software is available from the Blue Prism Portal, in the Addons section:

Login Agent registers itself as a separate installation within Control Panel.

Login Agent Configuration

During the installation process the Login Agent installation wizard asks for two important pieces of information:

• the Connection name – a current valid Connection name.
  • This Connection will be configured for either a Blue Prism Server type of connection (usual case), or to connect to a SQL Server database directly (less common).
• the installation path – a path to a folder which contains the Blue Prism software on the current machine
  • In the LoginAgentService.config file this is the “Working Directory” parameter.

These will be written to the LoginAgentService.config file used by the Login Agent service. Without these settings the service will not know which database to connect to, or where crucial files are stored. It is advised to check that the LoginAgentService.config file is correct and contains all the necessary values required to start up a Resource PC.

The default location of the LoginAgentService.config file is ‘%programdata%\Blue Prism Limited\AutomateV3’. Typing that address into a Windows Explorer address bar will reveal that folder, as it is normally a hidden directory.

Post Installation Steps

After installing the software on all the machines running Blue Prism software, the next steps are:-

• Import the “Login Agent Release.bprelease” file using the Import function in a Blue Prism Interactive Client
  • The file can be found in the Login Agent installation directory
  • The file only needs to be imported once for each Connection that will be using Login Agent, as it will be imported into the associated database
• Ensure that the Login Agent Service is running on all of the machines where the software is installed.
  • The service needs to run on all the Resource PCs that need to be automated using Login Agent
  • Installing the Login Agent service creates what we call a System Resource PC instance. This is used primarily to run the Login process before the “normal” Resource PC is started from your batch file when the machine starts up.

Testing the Resource PC

Log into one of the Resource PCs that you want to eventually automate the login process for. Start up a Resource PC using the appropriate command line, for example:

“C:\Program Files\Blue Prism Limited\Blue Prism Automate\Automate.exe” /resourcepc /public

Check that the Resource PC starts up without any issues. Once this is running, then transfer the command to start the Resource PC into a text file, rename it as a batch file (*.bat), and place the file into the Startup program group so that the batch file is run as soon as the Resource PC logs in.

Configuring the Resource PC to allow Login Agent to work

Login Agent needs to be able to interact with a Resource PC’s default login screen.

The correct format for a login screen is for the Lock Screen to be showing the user account tiles, and to include the account 'BluePrism' as an available tile on the lock screen. If this account tile is showing then it demonstrates that the Login Agent's credential provider is enabled.

Group Policy Settings

The following Group Policy settings should be set on each Resource PC that needs to be automated:-

1. Do not display the lock screen – Enabled

Computer Configuration --> Administrative Templates --> Control Panel --> Personalization

2. Interactive Logon: Do Not Required CTRL + ALT + DEL - Enabled

Double negative policy setting

The Group Policy for whether or not to require CTRL+ALT+DEL is worded as follows "Do not require CTRL+ALT+DEL". Therefore, you have to enable this setting in order to not require CTRL+ALT+DEL. We would therefore suggest ensuring that this policy is set to enabled for your client VMs.

Computer Configuration > Windows Settings > Security Settings > Local Policies > Security Options

• Machine inactivity limit – Not defined
• Message text for users attempting to log on – Not defined
• Message title for users attempting to log on – Not defined

Credentials

Set up some Credentials in the System Manager > Security screen. The Credentials must be named according to the Process Environment Variable called “Login Format String”. By default this has the format “Windows Login: [machine name]”. e.g. “Windows Login: CLIENT3” for a machine called “CLIENT3”.

The Credentials is created in the Security screen using the login format:

Test that the credentials is correct by logging into the Resource PC as that user. Also ensure that the Credentials has the correct access to Blue Prism Processes, Resources, and Roles.

The Login Process

To test the Login process run an Interactive Client interface on a machine other than the Resource PC which you intend to log into. You may already have a specific machine that is designated for testing or controlling Processes and Objects.

Open the Control Room screen in the Session Management section. In that screen check that the Resource PC is showing as an available resource. The Resource PC needs to be in a logged out state, and in that state the System Resource PC which Login Agent uses to run its processes will be running, making the Resource PC available for Login Agent processes.

Drag and drop the Login process onto the available Resource PC. It will appear as a job in the Environment pane, and will have a “Pending” status – ready to be run. Right-click the Login process and choose Start to run it.

Startup Parameters

The Login process has two startup parameters: Login Locally and Domain. If you are logging in with a Blue Prism user then it will be “local” and no domain will need to be specified.

If you have used an Active Directory Windows account then you may need to specify a domain name. This should be the fully-qualified domain name (FQDN).

Click the Start button to run the process with the supplied parameters.

The Login process will now run to completion. Check the log for further details (right-click the Process in the Environment list and choose View Log).

IMPORTANT! Do not attempt to use a tool such as Remote Desktop Connection to observe the process or check the results of any Login Agent processing.Only "non-interactive" console-style remote access tools should be used to do such operations.

Remote Desktop will create a new instance of the WINLOGON executable under a system context, and this will prevent the Blue Prism Credentials Provider from logging in correctly.

If you receive the message "Named Pipe handle is invalid" (or "LoginUI callbacks not disabled" in v5.0.23) then this often indicates that the Resource PCs login screen was not in the correct state, and you should reboot the Resource PC in order to reset the machine to a known state before running the Login process from Login Agent.

Specifying the correct credential information

For Login Agent to be able to login into, or to unlock a Resource PC, it is important that the correct credential information is used. Here is some advice on how the username and domain parameters need to be specified.

USERNAME

The username should have the user account name in it without any additional information such as the Netbios group, or the domain name.

Examples:

Correct format:

• myusername

Incorrect formats:

• myusername@mydomain1
• Domain1\myusername

The domain is the name of the domain - it's the name as recognised by Windows. It's not necessary to complete it if the machine itself is registered to the domain that you want to authenticate to - you only really need to fill it in if

                a) the machine is not attached to a domain or

                b) the domain you want to authenticate to is different to the one it is attached to.

For further information about the Login Agent configuration and installation, see the documentation published on the Blue Prism Portal in the Product -->Documentation section.