Set up with Windows Desktop Access (RDP)

Overview

Running automation that requires interaction with the Windows desktop requires an active user session to Windows.

For example, running Workforce Agent as a service can perform so-called "headless" operations. Still, it cannot interact with UI applications.

The standard solution is making and maintaining "infinitely" running user sessions. Still, these are pretty brittle and can be security risks, so a better solution is needed.

The main parts of the solution are:

  • A Windows Service that provides the secure connection to Robocorp Control Room to trigger robot executions.
  • Local RDP connection is used to open the user session (only for the execution duration) so that the robot can interact with the complete Windows UI.
  • Executor launched via Task Scheduler when the user logs in so that the robot executor is working with the target user's privileges.

Target goals, requirements and installation instructions are all on this page so check these out.

As we have seen, different enterprises can have quite varied ways of setting up Windows Group Policies, Active Directories, etc., so any feedback on the guides and tools is highly appreciated. Do not hesitate to contact us in the Robocorp Slack or Forum

Goals

  • Enable full desktop access for the robot execution on the target machine that does not have a user logged in.
  • Assign work to the machine from Robocorp Control Room just like any other Workforce environment.
  • Make Windows Remote Desktop access as limited as possible and fully controllable by the end-user or IT managing it.
    • RDP access from external networks is NOT required, only from localhost.
  • Solution works after the target machine reboots.
  • Make the setup as secure and straightforward as possible.
  • Enable running multiple setups on one Windows Machine using different user accounts.

Prerequisites

Before starting to set up the RDP service itself, you must verify these steps. Usually, this should be done by IT, so pass this guide onto your IT.

Standard Windows Virtual Machines from AWS service do not need any special settings so one can just jump to Installation and Use. However, many different policies and settings control Remote Desktop Connection, which is highly specific to company-level IT practices.

Able to open a local RDP connection

The solution does not take any RDP connections from external networks. Still, it requires opening an RDP session locally on the machine without any confirmation pop-ups or user interactions.

The list below is a collection of settings we have seen blocking the setup:

  1. Windows Remote Desktop enabled on the target machine.
    • The RDP session is only opened inside the target machine (localhost) and does not need to be open to external connections.
    • The connections are made from TERMSRV/127.0.0.2 using the default RDP port 3389
  2. The target machine cannot have Windows Interactive Logon messages enabled.
    • These usually come in the form of legal notices and cannot be bypassed by automation as they are designed to require human input.
    • Disabling this has to be done with the permission of the IT controlling the target machine as these are usually set up for a reason.
  3. Group Policies can allow/block specific user groups from opening local RDP connections
  4. Running more than two simultaneous user sessions on Windows Servers requires Microsoft RDS CAL licensing, read more behind the link.

You can test the connection as you are making the settings.

Please get in touch with us if you find any additional settings or details as company policies vary a lot, and we are trying to collect our list to be as comprehensive as possible

Users for running the automation

  • Add or select the user on the target machine you want this setup to use.
    • You can use this user to limit access to the machine the way you want.
    • User can be a local user or from AD; you need to know the user's domain.
    • You need to know the user's password when setting up the service.
  • The users will be added to the group Remote Desktop Users unless they are already there by the helper tool.
  • It is highly recommended to have these users be dedicated for automation runs only
    • Having humans using these user accounts should only happen for setting up and possibly debugging situations
  • Azure Active Directory (AAD) -users cannot be used to run Windows services
    • The user for the RDP setup needs to be either a local user or from a regular Active Directory.
    • Despite its name Azure Active Directory has very little in common with the regular Active Directory regarding functionalities, check out a summary of the differences here.

Installation and use

Check and test the Prerequisites first

Get Robocorp Service Helper tool to the target machine:

The following chapters are separated for different use cases as our tooling provides different usage for the cases:

Setting up a single environment for testing purposes

The Service Helper provides a simple interactive mode to get you started to set your first test service.

  1. Log in to the target machine with the user account that the service needs to run on

  2. Open Command Prompt in Administrator mode

  3. Run the command: whoami, you can use the value returned to verify the recommendations that the service-helper provides to you in the next step.

    C:\Installs>whoami
ec2amaz-7ssvr8i\rpajack

  4. Run command: robocorp-service-helper setup-desktop

    C:\Installs>robocorp-service-helper setup-desktop
Input windows login domain (EC2AMAZ-7SSVR8I):
Input Windows login username (RpaJack):
Input Robocloud link token: FRwFlv5illkjVHMZ3kko...
Input Windows login password (leave empty to set later):
    • The Service Helper recommends values for domain and username, which you can validate against the results of the whoami -command, and if correct, you only need to press Enter
    • The Robocloud Link Token is requested next:
      • Get the token from Control Room
        Control Room > Select a Workspace > Environments > Generate link token
      • Copy & paste the token to the command prompt
      • Note: The link token is consumed on use and does not need to be stored anywhere.
    • The last question is the user's password
    • At this point, Service Helper will load and install all needed components for the service.
      • If your user is already in the group Remote Desktop Users, you will see one error stating that the user was already there; no need to worry about this one.
    • If everything when fine, you should see the new environment in Control Room in the state: Offline

  5. Start the service by running: robocorp-service-helper start

    • The tool will again recommend values for domain and username again; just pressing enter should do here.
      C:\Installs>robocorp-service-helper start
Input windows login domain (EC2AMAZ-7SSVR8I):
Input Windows login username (RpaJack):
[2022-03-04T20:57:48.296] [INFO] Start - Starting service: Robocorp-WFA-EC2AMAZ-7SSVR8I-RpaJack
    • If everything when fine, the service should now be running, and you should see the new environment in Control Room in Idle -state
    • You are ready to rock!
      • If something went wrong, don't worry; you can just run robocorp-service-helper remove --all to get back to the beginning
      • You just need to remove the created environment from Control Room and generate a new link token on the next run.
      • Note: Most common cause for an error is a typo in the password so that you can fix following the guides:

  6. As the final step, you can now test if the desktop opening works:

Setting up multiple machines for production and maintenance

Setting up multiple machines using the interactive mode gets a bit clunky, so the Service Helper has support for using config files. Here you can define a config -file that contains all the settings needed, so you do not have to input them multiple times on the command prompt.

In this use case leveraging the Environment Groups -feature in Control Room becomes really powerful.
You can define an Environment Group first and there add a link token with expiration time.
This link token can be reused to link multiple environments, and environments are automatically added to the correct group.
Remember to keep the link token expiration time reasonable with security in mind though.

  1. The best way to build your config file is to log in to one of your machines with the targeted user

  2. Create the config file by following the comments in the template below:

    • This is just a YAML file, so any text editor will do

    • You can customize the values as you see fit

      # --- Arguments are optional, comment to use defaults. ---
# Environment name shown in Robocorp Control Room and name of the service on the machine
# Defaults to `echo Robocorp-WFA-%COMPUTERNAME%-%USERNAME%`
 resourceName: Robocorp-WFA-MACHINE_ABC-JohnDoe

 # User domain: Defaults to `echo %USERDOMAIN%`.
 # For Active Directory (AD), use command `whoami` to check the correct domain value.
 domain: MACHINE-ABC

 # Username: Defaults to `echo %USERNAME%`
 username: JohnDoe

 # Full path to location where run content is stored
 # Defaults to `echo %LOCALAPPDATA%\robocorp\workforce-agent-core-service`
 instancePath: C:\Users\JohnDoe\AppData\Local\robocorp\workforce-agent-core-service

 # Full path to the location where environment caching is done (no spaces or special characters in this path)
 # Defaults to `echo %LOCALAPPDATA%\robocorp`
 robocorpHome: C:\Users\JohnDoe\AppData\Local\robocorp

 # Link token from Robocorp Control Room
 linkToken: <link token>

 # You can give the user password here to avoid typos, but the password can also be left empty and set separately.
 password: <users password>

  3. Now that you have the config file, you can set up the service by running:
    robocorp-service-helper setup-desktop -c config.yaml

    • If everything when fine, you should see the new environment in Control Room in the state: Offline

  4. Start the service by running: robocorp-service-helper start -c config.yaml

    • If everything when fine, the service should now be running, and you should see the new environment in Control Room in Idle -state
    • You are ready to rock!

  5. Now, take the config file to the other machines, edit as needed and run the setups.

Setting up multiple environments running on a single machine

Running multiple RDP setups on one machine reduces the setup and maintenance cost of separate Windows machines (virtual or real). Running multiple Workforce environments on the same machine also enables parallel running, and you can use the machine's resources fully. Basically, the solution is just setting up the service on multiple separate user accounts on the same machine.

NOTE:
Running more than two simultaneous user sessions on Windows Servers requires Microsoft RDS CAL licensing, read more behind the link.

  1. Create/select separate user accounts on the machine or via AD.
    • Note: Each user needs to have logged in at least once to generate the user-specific folders.
  2. Set the amount of allowed RDP connections on the machine to match your needs:
  • Windows Group Policy editor:
    Computer Configuration
└─ Administrative Templates
   └─ Windows Components
      └─ Remote Desktop Services
         └─ Remote Desktop Session Host
            └─ Connections
    • Open and enable Limit number of connections and set the amount od connection to for example 10
  1. Setup the service according to: Setting up multiple machines for production and maintenance
    • Here you can just log in as administrator > create config files for each user > run the setups from the administrator user.

Limitations

User account per service

You need to set up a separate user account per service. It is also highly recommended not to use any existing human-user accounts. Having automation accounts separated keeps things clear. For example, these accounts can have long, complex passwords to avoid constant recycling. After setup, it is good to note that the solution does not require Remote Desktop Connections from external networks so that too can be used to secure the solution further.

Running multiple robots on a single Windows machine can cause resource collisions

Execution in the multiple RDP case can run the robot concurrently. For example, multiple robots can easily create file locking and race-conditions by accessing a common file outside the users' folder (e.g. C:\temp\test.txt).

Also, not all applications targeted by automation allow simultaneous use on one machine, but these are case-by-case checkups that need to be handled.

Robots need to be mindful of their resources on the machine and the boundary between user-specific and machine-wide items.

Assign work in Control Room

You can now configure steps under Workforce Process to point to the new environment and choose whether or not to Use RDP Connection:

rdp-setup-cloud

You can use a simple robot that takes a screenshot from the target machine to test the whole setup. Example:

*** Settings ***
Library  RPA.FileSystem
Library  RPA.Desktop

*** Tasks ***
Minimal task
    Create Directory    %{ROBOT_ARTIFACTS}
    Take Screenshot    %{ROBOT_ARTIFACTS}${/}screenshot.png

Technical guides

Updates and maintenance

The Workforce Agent Core -application is getting regular updates and new features, so maintenance of the service needs to have a known cadence for updates. We consider having at least a 6-month cycle to be the minimum, but we recommend having a monthly cadence around service updates. The changelog always shows the changes made.

We follow semantic versioning, which means only the major version updates can introduce breaking changes to the functionality. Minor and patch releases can only add or fix functionalities.

Updating the Workforce Agent running in the service requires three actions, all supported by Robocorp Service Helper:

If possible, verify from Robocorp Control Room that no automation is running or is about to start. Stopping the service will make the environment offline for the duration of the update. The update itself should only take under a minute as it only downloads the new executable,

  1. Stop the service
    • Interactive: robocorp-service-helper stop
    • With config file: robocorp-service-helper stop -c <config file>
  2. Update the Workforce Agent Core
    • Interactive: robocorp-service-helper update
    • With config file: robocorp-service-helper update -c <config file>
  3. Restart the service
    • Interactive: robocorp-service-helper start
    • With config file: robocorp-service-helper start -c <config file>

You should now see the environment in Idle -state in Control Room.

Uninstalling

If you need to remove the setup or want a clean start, the guide below helps you out.

Note: The uninstall sequence cannot at the moment remove the environment from Control Room, so it is good to identify the environment there so you can remove the correct environment once you have uninstalled the services.

  1. Get Robocorp Service Helper -tool to the target machine:
  2. To remove the service and related items, first you should stop the service with command:
    • Interactive: robocorp-service-helper stop
    • With config file: robocorp-service-helper stop -c <config file>
  3. You can remove the service with the command:
    • Interactive: robocorp-service-helper remove --all
    • With config file: robocorp-service-helper remove -c <config file> --all

After this, you can check the three places where the service is visible:

  • Windows Services: The service with the given name should no longer be listed.
  • Task Scheduler > Task Scheduler Library Schedule starting with the given service name should no longer be listed.
  • Credential Manager > Windows Credentials > TERMSRV/127.0.0.2: Should no longer be listed.

Set the password for the service

If you gave the correct password in the setup phase, you can start the service.
If you left the password empty or had a typo, you can set the password here.

  • Open Windows Services > Find & open Robocorp Workforce Agent properties > Log on
    • The username is set, but you need to input the user password here and Apply changes. service-password

Set the password to Windows Credentials Manager

If you gave the correct password in the setup phase, you can skip this.
If you left the password empty or had a typo, you can set the password here.

To securely use the password, the local RDP connection needs the user's access credential stored in Windows Credential Manager

  • Setup the RDP user and password to Windows Credential Manager:
    • Open Credential Manager by typing credential manager in the Start via
    • Modify the credential: TERMSRV/127.0.0.2 by setting the users password credential-manager.png

Group Policy: Add Group Policy: Allow local RDP connections for user groups

Goal: Avoid Group Policy blocking the local connection completely

  1. Open Group Policy Editor and navigate to:
    Computer Configuration
└─ Windows Settings
  └─ Security Settings
      └─ Local Policies
        └─ User Rights Assignment
            └─ Allow log on through Remote Desktop Services
  2. By default, Remote Desktop Users should be listed here.
    • If you are using different user groups, list the correct one here.

Testing the desktop access

If you want to verify the desktop access functionality or you are seeing timeout errors in Control Room. This guide shows you a way to locally test opening the desktop session.

  1. Log into the target machine with the user that is running the service
  2. Test the connection with the command below:
    • Note: If successful, this will kick you out of the remote desktop connection you are using.
    • The command to run is: robocorp-service-helper test-desktop
  3. If you get any pop-ups etc., that require user input, further actions are needed.
    • Check if the technical guides for solution
    • Please get in touch with Robocorp in these cases as we are trying to collect all the fringe cases in this document.
  4. If you were kicked out of your remote connection, everything should be working and you can start assigning work from Control Room

Service helper Command-line mode

The helper tool also has a normal arguments mode, so all the values can be given in the command line. This is valuable for CI/CD and fleet management usage (SCCM etc.) as it allows scripting and running without expecting user inputs.

To run from the CI system, use flag: --ci to ensure the tool is running in non-interactive mode.

Run:

robocorp-service-helper --help

...to get details on the arguments

CommandsDescription
robocorp-service-helper setup-desktopSetup the automatic Windows desktop login service when the process is executed with this agent
robocorp-service-helper test-desktopTest the desktop setup via local RDP connection
robocorp-service-helper startStart the service
robocorp-service-helper stopStop the service
robocorp-service-helper updateUpdate the Agent Core
robocorp-service-helper statusGet the service status
robocorp-service-helper setup-backgroundInstall the Agent Core as a background service
robocorp-service-helper removeRemove the service

Remote desktop configuration file

The setup creates a local config file that can be used to control how the local RDP connection behaves.

You can find the config.rdp file under %localappdata%\robocorp\workforce-agent-core-service

Note:
In basic cases, you do not need to do anything here and we have plans the enable this control directly from Control Room.
At the moment, the only known cases for needing this have been custom RDP port setting and desktop resolution control.

By default, the file content looks like:

full address:s:127.0.0.2:3389
authentication level:i:0
autoreconnection enabled:i:1
bandwidthautodetect:i:1
networkautodetect:i:0
screen mode id:i:2
desktop size id:i:2
desktopscalefactor:i:100

The official Microsoft documentation

Microsoft RDS CAL licensing

Let's open up the acronyms first:

  • Microsoft Remote Desktop Services (RDS)
  • Client Access License (CAL)

The full details and documentation at Microsoft's documentation

For companies already using multi-user Windows VMs, this is "business-as-usual". You probably only need to request to your IT (or who is managing the RD server) that you need an RDS license for machine A for user accounts X, Y and Z.

If you are unfamiliar with the topic, the summary is that without the licensing, providing a fully functioning Windows PC for REALLY cheap would be quite a simple task. So this is what Microsoft is tackling with the RDS licenses.

There are many ways to buy and manage RDS licenses, so it is tough for us to give a definitive guide on how to do the setup. Microsoft documentation is the best source to get started.

For the Workforce Agent RDP solution, this limitation can be seen when you try to open a third user session on one machine. The machine will prompt: "Two users are already logged in". This prompt will block the Workforce Agent from opening the connection, and it will time out.

April 5, 2022